Skip to content

Latest commit

 

History

History
144 lines (103 loc) · 5.32 KB

tools.org

File metadata and controls

144 lines (103 loc) · 5.32 KB

Build Tools

The DUNE LaTeX documents can be built with your favorite LaTeX tools in their usual manner. Support for some optional tools are provided which may simplify the process. See also the README file in the repository of the particular document. For help on using git see ./git.org.

Final vs Draft

In “draft” mode the PDF will have line numbers, “fixmes” and other features that may not be pretty but help in editing. These are all turned off in “final” build mode.

Normally, this would be handled by giving an option final to the class but instead we hard-code this switch in dune.cls as we often have many main volume and chapter TeX files that we want to switch between final and draft in a sweeping manner. To switch, find at the top of ./dune.cls (lines 11, 12):

\newif\iffinal
\finaltrue

or

\newif\iffinal
\finalfalse

pdflatex

The command pdflatex [filename], run twice, will compile a document, set up the chapter, section, figure and table numbering, and provide the tables of contents, figures, and tables. It will not create the bibliography; for that, run biblatex on the file, followed again by ~pdflatex.

Waf build

A Waf build system is provided which will build all the volume PDFs as well as generate per-chapter main TeX files and build them to PDF. The commands to run are as below.

For specifics on the waf output produced for the DUNE TDR, see Building the documents on the dune-tdr repository page.

./waf configure [--prefix=/path/to/install] (1)
./waf -p                                    (2)
./waf install                               (3)
  1. The one-time configuration of the build is required. Two options may be given. A --prefix to give a where you might want the resulting PDFs to be “installed”.
  2. Actually build the documents. This will run tasks in parallel on as many cores as your computer provides. Results will land in the build/ directory. After any changes to the documents (including a git pull this step should be redone.
  3. Optionally, “install” the results to the prefix specified in step (1).

Chapter files

The Waf build provides extra functionality to generate per-chapter TeX files and build them into PDFs. This is useful to hand out a focused part of an overall volume for review and can assist authoring as it allows one to more quickly rebuild the smaller chunk of the document you are actually working on.

To generate and build all chapter PDFs:

./waf --chapters

Once build you can rebuild just a particular chapter by narrowing the waf target:

./waf --chapters --targets=guidance-chapter-graphics.pdf

You can also exploit the chapter TeX file with automated tooling like latexmk (see below for more on this tool).

latexmk -pdf -pvc build/guidance-chapter-graphics.tex

You can now edit the actual chapter TeX (not the above file but ./guidance/chapter-graphics.tex in this case) and each time you save the file latexmk will automatically rebuild just that chapter.

The main chapter TeX file is generated using the script and template file which are under util/. Normally these are not user-serviceable.

Debugging problems with Waf

By default waf runs in a parallel mode which causes a lot of LaTeX output to flash by on your terminal. When things work adding -p can help quiet the output. But, when there is an error in your LaTeX you usually want more information, you want it serially and you may need to enter the LaTeX compiler’s interactive mode. This can be accomplished with:

$ ./waf -j1 --debug

The latexmk tool

The latexmk tool, mentioned already above, is very handy to use while editing as it can watch the TeX source, recompile each time a file is saved and refresh a PDF viewer. To use it effectively requires some special configuration which is in the .latexmkrc file in this repository. Simply running it from the source directory should work.

# one shot:
latexmk -pdf guidance.tex

Depending on if you have configured latexmk this probably sprays files into your current working directory. You can clean up with:

latexmk -c guidance.tex
# or:
latexmk -C guidance.tex

The former leaves the PDF and the latter also deletes it. To make latexmk watch for file saving and automatically rebuild add -pvc.

latexmk -pdf -pvc guidance.tex

This works best if your PDF viewer will auto refresh each time the PDF file is updated. On Linux evince/atril make good viewers. If your PDF viewer lacks auto-refresh feature additional configuration can work around its deficiencies. The .latexmk has some commented out suggestions. If these are useful to you, do not uncomment them in this file but rather copy them to your personal ~/.latexmkrc file.

See above for how to exploit the Waf build to operate at a per-chapter level for even faster automatic rebuilding. The auto-rebuild loop provided by latexmk can be applied to the generated chapter main tex as well.