Start documenting cli options

[PHPirates]

As mentioned #373, I started with just copying the output from tectonic --help into markdown. If you agree, I will document some more tips and other things that are now sort of hidden in old issues etc.

I don't understand where the option --hide would be used for, can you give an example?

[pkgw]

Thanks!

The --hide option is needed to get repeatable multi-stage document builds with Tectonic using a dependency system like make or ninja. For example, I have a workflow that uses a tool that processing the .aux file during a build to produce an updated .bib file. In pseudo-Makefile code, the workflow looks like this:

paper.aux: paper.tex
    tectonic --pass=tex --outfmt=aux paper.tex

paper.bib: paper.aux
    ./generate-bibtex.py <paper.aux >paper.bib

paper.pdf: paper.tex paper.bib paper.aux
    tectonic --pass=bibtex_first paper.tex

The problem with the rules as written above is that after the first build, the file paper.aux exists on disk, and will get used by the aux-generating command if the build is rerun. This essentially introduces a circular dependency, which you can work around in make but really makes things a lot more complicated and unstable. By adding a --hide=paper.aux option to the first tectonic command, the circular dependency is prevented.

Hopefully that helps. Would you want to update this PR with any further changes, or is it good to merge now?

[PHPirates]

Wait, you use Tectonic that way (with the python script to update the bib file) or is that how Tectonic implements things? The workflow isn't making any sense to me, why and with what would you update a bib file from the aux file?

Did you use things like Ninja yourself? Someone once tried to get me to use Bazel, in order to have reproducible builds, but I never managed to get it working. I'm not familiar with Ninja, but if it works well with Tectonic it may be useful to note somewhere (if it isn't already).

Thanks for the explanation, I think it makes sense to document it once I understand the use case of the workflow you mentioned, but for now you can merge this PR and I'll create a new one when I have additions.

[PHPirates]

I don't know why the circleci build is failing, is it getting stuck on compiling arrayvec and then just timing out on the no_output_limit you set?

[pkgw]

@PHPirates The CircleCI failure is a known intermittent issue associated with the fact that that build happens in a QEMU environment. It can safely be ignored.

[pkgw]

As for your other question, the example Makefile is a workflow that I use. I have a tool that maintains my bibliography in a real database, rather than a giant BibTeX file, and it has a mode where it can emit a .bib file for only the entries used in the .aux file, with some options for how they are rendered because BibTeX style files aren't always completely compatible with each other.

I use Ninja for all of my builds; it's really nice! I posted a forum thread documenting my workflow a while ago.

[PHPirates]

Thanks, I found the blog post, and I see you automated a solution for one of the problems that I talked about with someone only last week: when you maintain a central bib repository it can get so large that it's unmaintainable (he used a makefile and a huge central .bib file).

It sounds promising, I will try it out and copy it to the mdbook also when it works.