#260 Documentation for latex rules

[Jonathan Dushoff]

I was unable to find clear online documentation for what the latex rules are supposed to do. I tried the two main pages, the latex example, the WW tutorial (which is predominantly about latex) and looked at "What links here" for the latex example.

This relates to the bug Nested LaTeX dependencies, which I am about to post.

[Lee Worden]

It's true. Since the LaTeX and LaTeXML rules are supposed to "just handle anything you throw at them", I've figured naive users shouldn't need to know about their internals, and advanced users would need to look at their source code anyway. This is the same way the .R rules are being handled, no?

But of course it should all be documented.

[Jonathan Dushoff]

It's complicated. I wasn't referring to nitty-gritty details. I just wanted a general idea of what they're supposed to do. Ie., I hesitated to file the bug report because I couldn't find anything that claimed that dealing with nesting was a feature. If it says somewhere that the rules are supposed to handle anything that you throw at them, I did not find it.

Of course, details are good, but maybe a lower priority.

The R rules do have a page where I try to explain in detail what they're supposed to do (although not how). But it's badly out of date ...

JD

[Lee Worden]

Yes, it would be good to have a page about WW latex processing, that
would at least say the rules are "supposed to" process all your files
into a .pdf and .html outputs and be smart enough that you don't have to
worry about syncing, writing extra makefiles to declare dependencies, etc.

It would also be useful, though perhaps secondary, to document what the
make rules actually do, and to write something about advanced
applications like .tex files that are generated by other make rules,
whether knitr/sweave or custom stuff. And definitely to document the
use of environment variables like DEFAULT_LATEX and WW_TEX_D_FILES, or
whatever they're called.

[Lee Worden]

I've collected stuff about latex and latexml from various parts of the projects wiki onto http://lalashan.mcmaster.ca/theobio/projects/index.php/Latex_tricks and http://lalashan.mcmaster.ca/theobio/projects/index.php/WorkingWiki/LaTeXML_Notes.

There is no detailed discussion of the makefiles' design there, but it does say that it's "supposed to" rebuild your documents successfully without help, including in cases where .tex and/or .bib files are made by other rules.