The DUNE TDR repository

Autobuilt PDFs

Every working commit pushed to this repository on GitHub may trigger an automated build of the LaTeX source into PDFs. The output of this automated process will refresh files found here:

https://dune.bnl.gov/docs/dune-tdr/

Please register a working email address with GitHub if you wish to get notification of build failures due to problems in your commits. Notification is not sent in the case of successful commits.

Repository layout

All graphics files (JPEG, PNG, PDF) go under ./graphics/. Use simple file name with out any directory path regardless of the location of .tex file. E.g.,: \includegraphics{filename}.
The LaTeX content of each volume is under its own directory, e.g., ./vol-exec/ except for the volume’s main LaTeX file which is at top-level, e.g., ./vol-exec.tex
Likewise, each chapter of a volume has a LaTeX file in the volume directory, e.g., ./vol-exec/ch-exec-overall.tex.
Chapter editors are encouraged to retain one file per chapter but if they must be broken up the chapter file must remain and other section-level files should NOT be named with a “ch-” prefix. It is not required but section files can remain in the vol-*/ directory or be moved to a ch-*/ sub-directory.
The common/ directory holds important LaTeX files such as defs.tex, units.tex, glossary.tex and tdr-citedb.bib which authors and editors should familiarize themselves with and contribute to.
shared/ holds special case LaTeX content that must appear identically in more than one volume.
util/ holds some scripts that assist in building the document in particular for generating files.
generated/ holds some the automatically generated files. Human-edited files must not be placed in this directory. See section Generated files below for some details.

Building the documents

There are many ways to do this.

Official build

The full, official build method uses the provided waf command. It is fast, portable and performs many tasks. Primarily the volume PDF files are built with:

$ ./waf configure
$ ./waf

The final PDFs are under build/. So are all the intermediate files. To clean out you can do:

$ ./waf clean

If you want to keep the final build results safe from a clean then you install them somewhere.

$ ./waf configure --prefix=/path/to/some/install/location
$ ./waf install

In addition to the volume PDF you can generate and build per-chapter PDFs:

$ ./waf --chapters

For a specific chapter compliation, e.g. dune-tdr/vol-sp/ch-sp-hv.tex, while in dune-tdr/:

$ ./waf --chapters --targets=vol-sp-ch-sp-hv.tex,vol-sp-ch-sp-hv.pdf

The results are under build/ but may also be installed:

$ ./waf --chapters install

You can also prepare a tar file with just the files for each volume.

$ ./waf --arxiv

Generated files

In volume/chapter text you may \input{} various files that live under the ./generated/ directory. The files are named following certain patterns.

Requirements/specification tables

Requirements tables in various forms are made available. They are organized by a table type and by a “code name” which is associated to a spreadsheet in DocDB via this file ./util/dune-reqs-docids.txt. The “top level” specs have a code name like SP-FD. Some examples:

req-longtable-<code>.tex: the “top 5” + “selected top level” + “consortium level”.
req-just-<code>.tex: just the “consortium level”.
req-<code>-<label>.tex: a table holding a single requirement identified by its label and consoritum “code name”.
req-<code>-<NN>.tex: a single table row if one wants to construct the table manually in the body of the volume/chapter text.