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.
- All graphics files (JPEG, PNG, PDF) go under ./graphics/. Use
simple file name with out any directory path regardless of the
location of
.texfile. 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 ach-*/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.
There are many ways to do this.
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
In volume/chapter text you may \input{} various files that live under
the ./generated/ directory. The files are named following certain
patterns.
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.