Guidance on Producing LATEX Documents for DUNE/LBNF › docs › guidance.pdf · 7 Prepare your section(s) to the level of peer-reviewed publications for an international science

Guidance on Producing LATEX Documents for1

DUNE/LBNF2

Instructions and Example3

Anne Heavey, Fermilab; technical editor, structure, style4

Brett Viren, Brookhaven; LaTeX machinery and GitHub repository5

David DeMuth, VCSU; LaTeX, images, general6

May 6, 20197

1

i

Contents1

Contents ii2

List of Figures v3

List of Tables vii4

1 General Information 15

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1.2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

1.2.1 Simple Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.2.2 Glossary Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

1.3 Requirements Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

1.4 Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

1.5 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

1.6 Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

1.7 Fixmes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

1.8 Sectioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

2 Creating Good Graphics 516

2.1 Graphic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

2.2 Color palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618

2.3 Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719

2.4 Annotated Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

3 LATEX Conventions for LBNF/DUNE Documents 1121

3.1 Defined Terms: Macros and the Glossary . . . . . . . . . . . . . . . . . . . . . . . . . 1122

3.1.1 The common/defs.tex File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223

3.1.2 The common/glossary.tex file . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224

3.2 Numbers and Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225

3.2.1 Bare Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326

3.2.2 Bare Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1327

3.2.3 Numbers with Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428

3.2.4 Common Compound Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429

3.3 Including “dunefigures” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430

3.4 Including “dunetables” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631

3.5 Tables Specifically for the DUNE TDR . . . . . . . . . . . . . . . . . . . . . . . . . . 1732

ii

3.5.1 Requirements/Specifications Tables . . . . . . . . . . . . . . . . . . . . . . . . 171

3.5.2 Interface Document Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

3.5.3 Risk Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

3.5.4 Cost Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

3.5.5 Schedule/Milestone Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

3.6 Labels and Intra-document References . . . . . . . . . . . . . . . . . . . . . . . . . . 256

3.7 Citations and the Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

3.7.1 The Bibliography File Containing the Citations . . . . . . . . . . . . . . . . . . 258

3.7.2 Referencing Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

3.8 Vendors and Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2610

3.9 Standard LATEX Sectioning, “The DUNE Way”! . . . . . . . . . . . . . . . . . . . . . . 2711

3.9.1 A Subsection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2712

3.9.1.1 A Subsubsection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2813

3.9.1.2 A Second Subsubsection . . . . . . . . . . . . . . . . . . . . . . . . . 2814

3.9.2 A Second Subsection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2815

4 English Standards for LBNF/DUNE Documents 2916

4.1 DUNE and LBNF-related Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 2917

4.2 Spelling, Voice, Grammar and Punctuation . . . . . . . . . . . . . . . . . . . . . . . . 3018

4.3 Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3219

4.4 Hyphenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3320

4.5 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3421

4.6 Common Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3422

5 Reviewing and Editing 3623

5.1 Inline “fixme” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3624

5.2 Margin Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3625

5.3 Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3626

6 Important Files in the Document Repository 3727

6.1 The Main File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3728

6.2 The Content Files: Text and Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 3829

6.3 The LATEX Class File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3830

6.4 Document-wide LATEX Files in common/ . . . . . . . . . . . . . . . . . . . . . . . . . . 3831

6.5 Getting the Files and Compiling after your Changes . . . . . . . . . . . . . . . . . . . 3932

References 4133

iii

1

iv

List of Figures1

2.1 DUNE design report color palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

2.2 Annotations: original graphic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

2.3 Annotations: TikZ modified graphic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

2.4 TikZ Code Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

3.1 An aerial photograph of Fermilab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

3.2 LATEX source for figure inclusions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

3.3 Guidelines for specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

v

1

vi

List of Tables1

3.1 The LoT caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

3.2 Efficiencies and background rates for nucleon decay modes . . . . . . . . . . . . . . . . 173

3.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

3.4 Risk Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

3.5 Cost Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

3.6 Consortium X Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

vii

Chapter 1: General Information 1–1

Chapter 11

General Information2

1.1 Introduction3

DUNE has developed standards and conventions for large documents, design reports in particular,4

that contributors are asked to follow. An infrastructure that reflects these standards is implemented5

in LaTeX on GitHub for each document. This guidance document provides instructions for using6

the infrastructure and guidelines for contributing high-quality text. It is written according to these7

conventions so that its LATEX source can be used as an example.8

This has been updated for the DUNE TDR. Earlier versions of this guidance document were9

updated for other important documents, e.g., the CDR and the ProtoDUNE-SP TDR. These10

versions can be found on GitHub at https://github.com/DUNE/document-guidance/releases/.11

This chapter provides a quick summary of some of the important LaTeX conventions described in12

this document. More information is found in the other chapters of this document.13

1.2 Definitions14

We have two ways of enforcing consistency of terminology and LaTeX rendering: definitions,15

which define simple LaTeX code to substitute for complicated or error-prone code, and a glossary16

database. Both allow definition of a macro to be used in place of the actual term. A separate17

files exists for unit definitions. In addition, the glossary provides a definition of the given term or18

abbreviation.19

Please use both of these features as appropriate, and feel free to add new ones to the appropriate20

files.21

DUNE Technical Design Report

https://github.com/DUNE/document-guidance/releases/


1.2.1 Simple Definitions1

Find the full description in Sections 3.1 and 3.2.

We recommend that you use (and add to, as needed) macros defined in common/defs.txt forcomplicated expressions like

$\bar\nu_\mu$.

Clearly, typing a macro like

\anumu

is easier and much less error-prone than the full expression.

1.2.2 Glossary Terms2

Find the full description in Section 4.1.

Please see the file common/glossary.tex for defined terms. To use terms defined there, youwill typically use \dword{label} in your text. Variations on this are described in Section 4.1.

1.3 Requirements Tables3

Find the full description in Section 3.5.1.

Requirements (specifications) will be managed in tables. The TDR team will provide a templateand guidance. Please follow the instructions in Section 3.5.1 carefully.

1.4 Figures4




\begin{dunefigure}[optional caption for LoF]{fig:required-label}{required full caption (Credit: xyz)}

\includegraphics[width=0.8\textwidth]{image-filename}\end{dunefigure}

To reference: See Figure~\ref{fig:required-label}. Please make required-label thesame as image-filename.

Please check that your figures are reasonably sized. We may want to add this document to thearXiv, which has a 10MB limit per document; bloated figures can use that up quickly.

Mac users: Please avoid the use of capital letters in graphics filenames; it causes errors thatyou don’t catch when compiling locally on your system. The Mac file systems are not trulycase-sensitive, and a mismatch in the capitalization of graphics file names causes problemsdown the line in the repository.

1.5 Tables1


\begin{dunetable}[The LoT caption]{cc}{tab:table-label}{The full caption that appears above the table.}

Rows & Counts \\ \toprowruleRow 1 & First \\ \colhlineRow 2 & Second \\ \colhlineRow 3 & Third \\

\end{dunetable}

To reference: See Table~\ref{tab:table-label}. The “cc” means: “two columns, bothcentered.” You can substitute “l” or “r” to left- or right-justify a column’s contents. Usep{’width’} if you need a column’s contents to wrap to multiple lines.

1.6 Citations2

Please email all the bibliography entries that you need to Luke Corwin



([email protected]); he is ensuring that they all make it into the github reposi-tory.

Citations go in common/tdr-citedb.bib. When requesting additions to this file, please sendLuke the BibTeX rendering of the citation from http://inspirehep.net if it exists there. Fordocdb references, just send him the docdb number, and cite it in your text using a label of theform: \cite{bib:docdbNNNN}.

More information is in Section 3.7.

1.7 Fixmes1

More info and other options are described in Chapter 5.2

“Fixme” as in “fix me!” If you’re not sure about something or you find an error that somebodyelse has to fix, use:

\fixme{This is a fixme.}

1.8 Sectioning3


\chapter{A Chapter}\label{ch:blah}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\section{A Section}\label{sec:blah-sec1}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\subsection{A Subsection}\label{sec:blah-sec1-subsec1}

%%%%%%%%%%%%%%%%%%%%\subsubsection{A Subsubsection}\label{sec:blah-sec1-subsec1-subsubsec1}


http://inspirehep.net

Chapter 2: Creating Good Graphics 2–5

Chapter 21

Creating Good Graphics2

It is essential to use high-quality, efficiently sized figures (aka “graphics”). You may be asked to3

re-make any that egregiously violate some some basic standards. These standards are in place to4

avoid sub-optimal figures, bloated files sizes, and delayed publishing schedules. E.g., the arXive5

puts a limit of 10MB on documents.6

Often the best thing to do is to not process or attempt to optimize a graphic but provide the7

editors access to the most “raw” graphic which your software can produce. If at all uncertain,8

please contact the technical editors. The rest of this section provides guidance on how to create9

optimal figures.10

2.1 Graphic Types11

There two basic graphic content types; these are important to understand:12

raster a two dimensional array of pixels13

vector a two dimensional drawing description language14

The documents compile with pdflatex and so may use graphics in PDF, JPEG or PNG file15

formats. These formats have specific best uses:16

JPEG use for photographs17

PDF use of any line drawings, plots, illustrations18

PNG use due to some inability to produce proper JPEG or PDF (contact editors)19

It is possible (though unwise) to store inherently raster information in PDF or to rasterize inher-20



ently vector information into JPEG or PNG. This is the main cause for bloated, low-quality1

graphics. Here are some guidelines addressing this common problem:2

• Only save photographic images to JPEG, avoid re-saves.3

• Save line drawings, plots or illustrations directly to vector PDF.4

• Follow special guidance on annotation (see Section 2.4).5

• Never convert any raster data (JPEG/PNG) to PDF.6

• Never raster what is really vector data in to a JPEG/PNG.7

• Never use MicroSoft PowerPoint for any figure as it tends to lead to poor quality and bloated8

files.9

• Do save using native application formats to allow later modification10

• Leave any potential format conversions to the technical editors.11

• Consider providing plots as easy-to-reproduce ROOT, Python or other scripts. (see Sec-12

tion 2.3)13

If authors find these guidelines can not be followed for any given graphic, please contact the14

technical editors.15

2.2 Color palette16

When creating figures, we suggest that you choose colors from the DUNE color palette as shown17

in Figure 2.1. Matching LATEX colors are defined as shown below:18

dunebrown #5E3327dunebrown #5E3327

dunebrown #5E3327

dunenavy #003B71dunenavy #003B71

dunenavy #003B71

dunesky #7DAED3dunesky #7DAED3

dunesky #7DAED3

19

duneorange #FF671Bduneorange #FF671B

duneorange #FF671B

dunepeach #F19F53dunepeach #F19F53

dunepeach #F19F53

dunegold #FFD26Cdunegold #FFD26C

dunegold #FFD26C

20



Figure 2.1: DUNE design report color palette (From Diana Brandonisio (FNAL))

2.3 Plots1

Where possible, it is recommended that any plots be submitted in a form that allows easy repro-2

duction from data in the course of building the document. This allows the technical editors to3

attempt to apply consistent in-plot fonts, colors, wording.4

There is no one way to satisfy this high level of figure production because authors must remain5

free to use the plotting tools they find best suited. The following are some guidelines.6

• Commit the high-level code used to produce the figure in some clearly named sub-directory7

of the repository. Factor this code from any large code base. For example, supply a “stand8

alone” Python or ROOT script or one which depends on common modules/libraries.9

• Commit any data needed to produce the figure in some clearly named subdirectory. However,10

distill this data down so that it does not require substantial space. A suggested rule of thumb11

is that the data should not be an order of magnitude larger than the resulting PDF.12

• If a figure is drawn or otherwise generated directly from code or markup, include the source13

file as well as the resulting PDF/PNG.14

The two guidelines must typically be satisfied together. Here are some example strategies:15



• Produce a plot in ROOT and save the resulting TCanvas as a .C file.1

• Dump plot data as columns in a text file and provide a ROOT or Python (eg matplotib)2

script to read it in and produce the PDF.3

• Complex structured data can reduced to just what is needed for the plot and saved as ROOT4

TTree or compressed JSON files.5

• Create a shell script which takes no arguments, a Makefile, or other build file, or otherwise6

document any non-trivial command line steps needed to rerun the code.7

If the effort to provide this high-level of sophistication is considered prohibitive, then consider at8

least adding a note (for example in a figures/README.txt file or in a figures/my-figure.readme9

file) that associates the name of your figures with your contact info and/or the procedure needed10

to reproduce the figure.11

2.4 Annotated Figures12

It is a common activity to take a figure and annotate it with arrows, labels, etc. For example, as13

shown in Figure 2.2, annotations were made on a decaying kaon in the ICARUS T600 detector14

considered in a PDK analysis. Then shown again with similar markups after using the LATEX TikZ15

package in Figure 2.3.16

Figure 2.2: An image annotated by, for example Powerpoint, often leading to file size bloat.

If you find the TikZ approach tedious, then at a minimum take care not to produce a low-quality17



cathode

kaon decaymuon decay

time

wire no. 0.5 m

Figure 2.3: An image annotated using the LATEXTikz package.

\begin{tikzpicture}[scale = 1.0, font=\sffamily\LARGE]\node[anchor=south west,inner sep=0] at (0,0){\includegraphics[width=0.8\textwidth]{fig-kaon-coll-blank.png}};\node at (11.7,8.5) {\textbf{cathode}};\draw [line width=2pt, dotted] (0.3,7.8) -- (13.6,7.8);\node at (7.0,6.5) {\textbf{kaon decay}};\draw [line width=1.5pt,-latex] (7.0,5.9) -- (7.0,2.1);\node at (11.9,5.7) {\textbf{muon decay}};\draw [line width=1.5pt,-latex] (11.7,5.4) -- (11.7,3.5);\node at (0.9,4.1) [rotate=90] {\textbf{time}};\draw [line width=2pt,-latex] (0.4,0.4) -- (0.4,5.0);\node at (2.9,1.0) {\textbf{wire no.}};\draw [line width=2pt,-latex] (0.4,0.4) -- (5.1,0.4);\node at (10.7,1.0) {\textbf{0.5 m}};\draw [line width=1.5pt] (7.8,0.4) -- (13.5,0.4);\draw [line width=1.5pt] (7.8,0.2) -- (7.8,0.6);\draw [line width=1.5pt] (13.5,0.2) -- (13.5,0.6);\draw[red,ultra thick,rounded corners] (11.3,2.5) rectangle (12.3,3.5);

\end{tikzpicture}

Figure 2.4: LATEXTikZ Annotation Code Snippet



graphic with a large filesize (>3MB). Also, please choose fonts and colors that “work” with the1

document.2

If at all possible, provide the file in a format which can be further edited and which does not turn3

raster data into PDF nor vector data into JPEG/PNG.4

If this can’t be avoided and if the underlying graphic is JPEG then produce the final version in5

JPEG and not PNG nor PDF. If the annotation is on top of an original vector drawing and your6

annotation software will retain the vector information, save it as PDF.7

Feel free to consult [email protected] with any assistance on creating your image annota-8

tions.9


Chapter 3: LATEX Conventions for LBNF/DUNE Documents 3–11

Chapter 31

LATEX Conventions for LBNF/DUNE Docu-2

ments3

This chapter provides guidelines on sectioning, inserting figures, tables and references, and for-4

matting numbers and units according to the LATEX configuration we have set up for LBNF/DUNE5

documents.6

Prepare your section(s) to the level of peer-reviewed publications for an international science7

journal.8

Target your introductory section(s) at both scientists from the broad HEP community and at9

knowledgeable, but not necessarily expert, members of national and international science policy10

organizations. Recommendation: write the chapter first, then go back and write the introduction11

to it. It’s more likely to be coherent!12

Target the body of your section(s) at scientists and engineers from the broader HEP community.13

3.1 Defined Terms: Macros and the Glossary14

To enforce consistency among frequently used terms, we have defined LATEX macros for several15

names, expressions and parameter values in the file common/defs.tex. We also use a system16

called “DUNE Words” to enforce consistency of terminology. (Thank you, Brett.) Terms are17

defined in the file common/glossary.tex.18



3.1.1 The common/defs.tex File1

You may add terms to this file; this is useful if the name or term is subject to multiple “spellings.”2

Please add macros carefully, and test them before you commit.3

For example,4

• ν̄e is written as \anue,5

• ∆m221 is written as \dm{21},6

• sin2 θ13 is written as \sinst{13},7

• νµ → νµ is written as \numutonumu,8

• → K+ν is written as \ptoknubar,9

• the drift velocity parameter value 1.6mm/µs is written as \driftvelocity,10

• SURF is written as \surf, and11

• MINERνA is written as \minerva.12

3.1.2 The common/glossary.tex file13

“If you call it a spade here, call it a spade there.” We want to enforce consistency in terminol-14

ogy. We do this via a glossary filled with “DUNE Words.” This means you should check the15

common/glossary.tex for defined terms and use \dword{label} for these terms in your text.16

More information, including variations on \dword{label}, is given in Section 4.1, and the details17

are explained in Brett’s (short) document “DUNE Words” at18

https://dune.bnl.gov/docs/technical-proposal/dune-words.pdf.19

3.2 Numbers and Units20

All numerical quantities expressed as literal number must have units unless they are inherently21

unitless. The international audience demands consistent use of metric units throughout. Please22

follow this standard (fully documented at http://mirrors.sorengard.com/ctan/macros/latex/23

contrib/siunitx/siunitx.pdf).24

If and only if a detector component has been purchased or specified using a US/Imperial or another25

practical non-standard metric unit, then that unit should be listed as well in parentheses that follow26


https://dune.bnl.gov/docs/technical-proposal/dune-words.pdf

http://mirrors.sorengard.com/ctan/macros/latex/contrib/siunitx/siunitx.pdf




(use of the ambiguous but common kt is allowed). For example:1

“Holes are drilled to a diameter of 0.635 cm (0.25 in)... The 0.635 cm diameter holes are cleaned2

with...”3

In order to enforce consistency the siunitx package is used and a collection of common units are4

defined in common/units.tex.5

3.2.1 Bare Numbers6

To enforce consistent writing of numbers please encase them in the \num{} command:7

• “100” is written as \num{100}.8

• “1000” is written as \num{1000}.9

• “123.456” is written as \num{123.456}.10

• “1±2i” is written as \num{1+-2i}.11

• “3× 1045” is written as \num{3e45}.12

• “0.3× 1045” is written as \num{.3e45} (keeps the decimal point before the 3).13

• “10, 20 and 30” is written as\numlist{10;20;30}.14

3.2.2 Bare Units15

If you need to write a bare unit, one with not associated number, use \si{} (lower case “si”).16

Some combinations are defined in the file common/defs.tex.17

• “m” is written \si{\meter} (The European spelling \si{\metre} also works).18

• “V2 lm3 F−1” is written \si{\square\volt\cubic\lumen\per\farad}.19

• “V” is written \si{\volt}.20

• “kgm s−1” is written either as \si{kg.m.s^{-1}} or \si{\kilogram\meter\per\second}.21

• “kgm s−1” is written as \si[per-mode=symbol]{\kilogram\meter\per\second}.22



3.2.3 Numbers with Units1

When a quantity has a unit, write both the numerical part and the unit using the \SI{}{}2

command like:3

• “120GeV” is written as \SI{120}{\GeV},4

• “4850 ft” is written as \SI{4850}{\ft},5

These are defined in the file common/units.tex.6

No hyphens shall be used between numbers and units, even if the number-unit is used as an7

adjective, e.g., “a 40 kiloton detector.” (This is a change from past DUNE documents.)8

3.2.4 Common Compound Units9

There are some common units that rather long to type out each time especially when we require10

nice formatting. Again, see common/units.tex.11

• “per m · sr” is written as per \msr, and12

• “exposure in kt ·MW · years” is written as exposure in \ktmwyr{}s.13

3.3 Including “dunefigures”14

Instead of using the usual figure environment, please use the custom dunefigure environment15

in order to provide for a consistent presentation. The environment is called with one optional and16

two required arguments:17

1. An initial, optional short caption to appear in the List Of Figures (LoF), in square brackets.18

This caption only needs to identify the figure uniquely, it does not need to describe it fully.19

2. A (required) label for referencing. No spaces are allowed in the label. Curly brackets.20

Start the label with fig: then use the filename of the figure as the rest of the label,21

(image-filename, below).22

3. The (required) full caption. Curly brackets, again.23

Usually the figure contains a graphic via an includegraphics statement. The filename is assumed24

relative to a graphicspath as mentioned in Section 6.1 and as such, please (a) put the file in the25

right place and (b) don’t specify any directory parts in its name. The file’s extension may be26



omitted. Provide an image credit if appropriate. The entry looks like this (make the width/size1

appropriate for the image):2

\begin{dunefigure}[optional caption for LoF]{fig:figure-label}3

{required full caption (Credit: xyz)}4

\includegraphics[width=0.8\textwidth]{image-filename}5

\end{dunefigure}6

Do not prepend any directory information to the image-filename in the includegraphics line; it will7

cause an error. The LATEXsetup that we have already takes care of finding the image.8

Mac users: Please avoid the use of capital letters in graphics filenames; it causes errors that you9

don’t catch when compiling locally on your system. The Mac file systems are not truly case-10

sensitive, and a mismatch in the capitalization of graphics file names causes problems down the11

line in the repository.12

Remember, “image-filename” should match “figure-label.” This makes it MUCH easier to find13

associated references and figures in the LATEX source. Also, we recommend starting the filename14

with an abbreviated form of the subsystem it relates to, e.g., for the APAs,15

• image filename = apa-frame-and-wires16

• label = fig:apa-frame-and-wires17

• reference = fig:ig:apa-frame-and-wires18

Example:19

Figure 3.1: An aerial photograph of Fermilab showing Wilson Hall and surrounding accelerator rings(Photo: Fermilab Visual Media Services).



An example can be seen in Figure 3.1, which is created with the LATEX shown in Figure 3.2. Notice1

that in the reference to the figures, we need to prepend fig: to the label. (See Section 3.6.)2

\begin{dunefigure}[An aerial photograph of Fermilab]{fig:fermilab-aerial}{An aerial photograph of Fermilab showing Wilson Hall andsurrounding accelerator rings (Photo: Fermilab Visual Media Services).}

\includegraphics[width=0.8\textwidth]{fermilab-aerial}\end{dunefigure}

Figure 3.2: LATEX source showing how to include Figure 3.1.

See Chapter 2 for guidelines on the graphics files themselves.3

3.4 Including “dunetables”4

Like figures, we use a special environment, dunetable for tables to achieve a degree of consistency.5

This replaces the usual double table + tabular environments. The dunetable environment takes6

one optional and three required arguments:7

1. An initial, optional short caption for the List of Tables (LoT). Square brackets.8

2. The tabular column specification. (Curly brackets for the last three items.)9

3. A label for referencing. Start the label with tab:.10

4. The full caption.11

Inside the actual contents of the table you are required to provide an initial row containing the12

headings for the table’s rows followed by a toprowrule macro. Following every regular row (except13

the last) you should include a colline macro. Both of these take the place of the usual hline.14

Table 3.1: This is a sample table.

Rows CountsRow 1 FirstRow 2 SecondRow 3 Third

Table 3.1 is thus made like (arguments can span lines):15

\begin{dunetable}16

[The LoT caption]17

{cc}18

{tab:table-label}19

{This is a sample table.}20



Rows & Counts \\ \toprowrule1

Row 1 & First \\ \colhline2

Row 2 & Second \\ \colhline3

Row 3 & Third \\4

\end{dunetable}5

6

See Table~\ref{tab:table-label}...7

The “cc” means: “two columns, both centered.” You can substitute “l” or “r” to left- or right-8

justify a column’s contents. Use p{’width’} (e.g.,p{0.2\textwidth} or p{5cm} if you need a9

column’s contents to wrap to multiple lines.10

Table 3.2 shows a more complex example. See the source for how it is written. Note that special11

column specifications are used.12

Table 3.2: Efficiencies and background rates for nucleon decay channels of interest for a large under-ground LArTPC, and comparison with water Cherenkov detector capabilities

Decay Mode Water Cherenkov Liquid Argon TPCEfficiency Background Efficiency Background

p→ K+ν 19% 4 97% 1p→ K0µ+ 10% 8 47% < 2p→ K+µ−π+ 97% 1n→ K+e− 10% 3 96% < 2n→ e+π− 19% 2 44% 0.8

3.5 Tables Specifically for the DUNE TDR13

In this section we show a sample table (shown for SP HV) for each standardized table to be used14

in detector-system chapters of the TDR.15

3.5.1 Requirements/Specifications Tables16

Enumeration of requirements is an important addition to the TDR, and a systematic way of doing17

this is in place.18

You will find a template Excel file in which to enter your requirements or specifications in19

• Single-phase: DUNE DocDB 11074 [2]20

• Dual-phase: DUNE DocDB 13244 [3]21



The file has several sheets (tabs). The TDR team has an automated way of turning the data in1

this file into LaTeX, hence the detailed instructions that follow:2

1. Download the file from DocDB (SP) 11074 or (DP) 11324.3

2. Read through the top-level requirements in the sheet labeled “Top-level to review.” The4

top five (colored yellow) are considered global; they may appear in all subsystem chapters5

(TBD). Of the others (orange and blue), some will apply to your chapter and others will not.6

3. Enter the unique ID numbers (column A) of the global requirements that apply to your7

chapter into column A of the tab labeled “Your selected top level reqs.”8

4. In “Your chapter” sheet, note the guidelines given in rows 1 and 2. Also note that a couple9

of example rows are given.10

5. Enter any additional requirements or specifications for your chapter into this sheet using11

proper LaTeX. See Figure 3.3.12

6. The TDR will pick up the brief rationale and validation fields, not the full ones. Please fill13

out both full and brief; this information may be used in other contexts in the future.14

7. In the validation field, be sure to include ProtoDUNE impacts and simulation studies, as15

appropriate. You may include additional validation information, as well.16

8. Please be concise! We expect no more than five or ten additional specifications here. Ques-17

tions on content? Ask Tim and Sam.18

9. Delete the example rows.19

10. Save your spreadsheet as DUNE-req-spec-(your chapter code)-DDMMMYYYY.xlsx, e.g., DUNE-20

req-spec-SP-PDS-30oct2018.xlsx.21

11. Upload your completed spreadsheet to your existing requirements DocDB entry, if you have22

one. (It should be labeled with the topic “Requirements” to allow easy searching.) If you23

don’t, create a new DocDB entry for it.24

12. Send the DocDB number to at least one of Anne, David, or Brett.25

13. Whenever you update your spreadsheet, remember to upload it to DocDB into a new version.26

14. Be aware that if any of the top-level requirements change, you will need to review and27

possibly update your spreadsheet. The TDR team will provide the information on what’s28

been updated.29

The TDR team will turn your Excel files into LaTeX tables and the generated files will reside30

under the “generated” folder in the repository structure. The TDR team will work with you to31

insert them into your chapter files.32



Figure 3.3: Guidelines for specifications

3.5.2 Interface Document Tables1

We have a standard table format for linking to interface documents in the DUNE docdb. In the2

first column, put the system to which you are interfacing; use the glossary entry for the system, if it3

exists. For the second column, we provide a macro to use to add linked references, \citedocdb{}.4

The parameter is the interface document’s docdb number.5

The output of the macro is a hyperlink to the version of the document in the docdb followed by6

a citation. The macro requires that the citation’s label be of the form: bib:docdbNNNN, where7

NNNN is the docdb number, and that the URL be of the form8

https://docs.dunescience.org/cgi-bin/private/ShowDocument?docid=NNNN&asof=2019-7-15.9

\begin{dunetable}10

[High Voltage System Interface Links]11

{p{0.25\textwidth}p{0.5\textwidth}l}12

{tab:HVinterfaces}13

{High Voltage System Interface Links }14

Interfacing System & Description & Linked Reference \\ \toprowrule15

\dword{cisc} & \dword{hv} vs. \dword{lar} level interlock, sensor locations in high-field regions, cold/warm camera coverage, \dword{hv} signal monitoring, etc. & \citedocdb{6787} \\ \colhline16

... & & \citedocdb{nnnn} \\ \colhline17

(last item)& & \citedocdb{} \\18

\end{dunetable}19

This is a reference to Table 3.3 (\ref{tab:HVinterfaces}).20



Table 3.3: High Voltage System Interface Links

Interfacing System Description Linked Referencecryogenic instrumentationand slow controls (CISC)

high voltage (HV) vs. liquid argon (LAr) levelinterlock, sensor locations in high-field regions,cold/warm camera coverage, HV signal monitoring,etc.

DocDB 6787 [4]

... DocDB nnnn [5](last item) DocDB [?]

3.5.3 Risk Tables1

As of March 2019, risk tables will be autogenerated similarly to specifications tables. The Excel2

format is in DocDB 14236 [6]. Generated tables will appear in the“ generated” folder, and you3

will need to insert them into your file, e.g.,4

\input{generated/risks-longtable-DP-FD-HV}5

The required fields are:6

• Integer to number the risk in order, starting at 1.7

• Risk ID (format RT or RO (for risk threat or opportunity), followed by consortium abbrevi-8

ation (e.g., SP-APA) followed by a sequential number (01, 02, etc.) E.g., RT-SP-APA-02);9

• Risk title;10

• Latex label (for processing), this should identify risk and have no spaces, e.g., apa-prod-11

quality;12

• Description (can be longer, will not appear in table but may be used later);13

• Risk Mitigation (full, may go in accompanying text, TBD)14

• Risk Mitigation (brief to go in table)15

• Probability (HML, post-mitigation, where: High >25%, Med 10-20%, Low <10%)16

• Cost impact (HML, post-mitigation, where: High >20% increase, Med 5-20% inc, Low <5%17

inc);18

• Schedule impact (HML, post-mitigation, High >6 mo delay, Med 2-6 mo delay, Low <2 mo19

delay);20

A sample might look like:21



\begin{dunetable}1

[Risk Table]2

{p{0.03\textwidth}p{0.08\textwidth}p{0.2\textwidth}p{0.3\textwidth}p{0.07\textwidth}p{0.07\textwidth}p{0.07\textwidth}}3

{tab:xyzrisks}4

{My subsystem’s post-mitigation risk summary}5

1 & ID & Risk & Mitigation & Probability & Cost Impact & Schedule Impact \\ \toprowrule6

2 & (id 1) & Sapien eget mi proin & Lorem ipsum dolor sit amet. & L& M& L \\ \colhline7

3 & (id 2) & Libero enim sed &Urna cursus eget nunc. & M& L& M \\ \colhline8

... &&&&&& \\ \colhline9

\textit{n} & (last id)& risk text &...&...&...& ... \\10

\end{dunetable}11

This is a reference to Table 3.4 (\ref{tab:xyzrisks}).12

Table 3.4: My subsystem’s post-mitigation risk summary

1 ID Risk Mitigation ProbabilityCostImpact

ScheduleImpact

2 (id 1) Sapien eget mi proin Lorem ipsum dolor sit amet L M L3 (id 2) Libero enim sed Urna cursus eget nunc M L M...n (last id) risk text ... ... ... ...

3.5.4 Cost Tables13

These will be generated automatically. Consortia need to get their cost items to Gina Rameika;14

the TDR team will do the rest. Generated tables will appear in the “generated” folder, and you15

will need to insert them into your file, e.g.,16

\input{generated/costs-... (filenames TBD)}17

We expect the tables to look something like this:18

This is a reference to Table 3.5 (\ref{tab:XXcostsumm}).19



Table 3.5: Cost Summary

Cost Item M&S (k$ US) Labor HoursDesign, Engineering and R&D(E.g., Photosensors design)(E.g., Mechanics design)

...Production Setup(E.g., Photosensors production setup)

...Production(E.g., Photosensors production)

...DUNE FD Integration & Installation

...(last line)

3.5.5 Schedule/Milestone Tables1

This is a standard table template for the TDR schedules. It contains overall FD dates from Eric2

James as of March 2019 (orange) that are held in macros so that the TDR team can change them3

if needed. Please do not edit these lines! Please add your milestone dates to fit in with the overall4

FD schedule.5

\begin{dunetable}6

[Consortium X Schedule ]7

{p{0.65\textwidth}p{0.25\textwidth}}8

{tab:Xsched}9

{Consortium X Schedule (fix short title, label and caption, and add your10

consortium items to table in chronological order among the fixed entries)}11

Milestone & Date (Month YYYY) \\ \toprowrule12

Technology Decision Dates & (your date) \\ \colhline13

Final Design Review Dates & (your date) \\ \colhline14

Start of module 0 component production for ProtoDUNE-II & (your date) \\ \colhline15

End of module 0 component production for ProtoDUNE-II & (your date)\\ \colhline16

\rowcolor{dunepeach} Start of \dword{pdsp}-II installation& \startpduneiispinstall17

% March 202118

\\ \colhline19

\rowcolor{dunepeach} Start of \dword{pddp}-II installation& \startpduneiidpinstall20

% March 202221



\\ \colhline1

\dword{prr} dates & (your date) \\ \colhline2

Start of (component 1) production & (your date) \\ \colhline3



\rowcolor{dunepeach}South Dakota Logistics Warehouse available& \sdlwavailable6

%April 20227

\\ \colhline8

\rowcolor{dunepeach}Beneficial occupancy of cavern 1 and \dword{cuc}& \cucbenocc9

% October 202210

\\ \colhline11

\rowcolor{dunepeach} \dword{cuc} counting room accessible& \accesscuccountrm12

% April 202313

\\ \colhline14

\rowcolor{dunepeach}Top of \dword{detmodule} \#1 cryostat accessible& \accesstopfirstcryo15

% January 202416

\\ \colhline17

End of (component 1) production & (your date) \\ \colhline18

... & ... \\ \colhline19

\rowcolor{dunepeach}Start of \dword{detmodule} \#1 TPC installation& \startfirsttpcinstall20

% August 202421

\\ \colhline22

\rowcolor{dunepeach}End of \dword{detmodule} \#1 TPC installation& \firsttpcinstallend23

% May 202524

\\ \colhline25

\rowcolor{dunepeach}Top of \dword{detmodule} \#2 accessible& \accesstopsecondcryo26

% January 202527

\\ \colhline28

\rowcolor{dunepeach}Start of \dword{detmodule} \#2 TPC installation& \startsecondtpcinstall29

% August 202530

\\ \colhline31

\rowcolor{dunepeach}End of \dword{detmodule} \#2 TPC installation& \secondtpcinstallend32

% May 202633

\\ \colhline34

... & \\ \colhline35

last item & (your date) \\36

\end{dunetable}37

38

39

This is a reference to Table 3.6 (\ref{tab:Xsched}).40



Table 3.6: Consortium X Schedule (fix short title, label and caption, and add your consortium items totable in chronological order among the fixed entries)

Milestone Date (Month YYYY)Technology Decision Dates (your date)Final Design Review Dates (your date)Start of module 0 component production for ProtoDUNE-II (your date)End of module 0 component production for ProtoDUNE-II (your date)Start of ProtoDUNE-SP-II installation March 2021Start of ProtoDUNE-DP-II installation March 2022production readiness review (PRR) dates (your date)Start of (component 1) production (your date)Start of (component 2) production (your date)Start of (component 3) production (your date)South Dakota Logistics Warehouse available April 2022Beneficial occupancy of cavern 1 and central utility cavern (CUC) October 2022CUC counting room accessible April 2023Top of detector module #1 cryostat accessible January 2024End of (component 1) production (your date)... ...Start of detector module #1 TPC installation August 2024End of detector module #1 TPC installation May 2025Top of detector module #2 accessible January 2025Start of detector module #2 TPC installation August 2025End of detector module #2 TPC installation May 2026...last item (your date)



3.6 Labels and Intra-document References1

Assume that any chapter, section or important sub-, subsubsection or any figure or table envi-2

ronment may need to be referenced elsewhere in the text.3

Just below a chapter heading and any significant section heading a label should be added so it4

can be referenced. Use the defined label in a \ref{mylabel} in order to make reference to the5

chapter, section, figure, etc.6

For example:7

\chapter{A Chapter}8

\label{ch:a-chapter}9

10

\section{A Section}11

\label{sec:a-section}12

13

\subsection{A Subsection}14

\label{sec:a-subsection}15

16

... as described in Chapter~\ref{ch:a-chapter} ...17

or Section~\ref{sec:a-section} ...18

or Section~\ref{sec:a-subsection} ...19

20

When you reference a chapter, section, subsection, figure, table, etc., capitalize the word “Chapter”21

or whatever it is, e.g., “as shown in Section 6.1.” Use the word “Section” even if it’s a subsection22

or subsubsection, and use the tilde sign to keep the number on the same line as the word that23

precedes it.24

For figures, the labels and references need to include “fig:” before the actual label name, as25

mentioned in Section 3.3; for tables, “tab:” must be prepended to the label name (see Section 3.4).26

3.7 Citations and the Bibliography27

3.7.1 The Bibliography File Containing the Citations28

For the TDR, we have created the file common/tdr-citedb.bib to contain all the citations. Please29

email all the bibliography entries that you need to Luke Corwin ([email protected]); he is30

ensuring that they all make it into the github repository.31

Before requesting a new entry to tdr-citedb.bib, please search through it to see whether the32



entry you wish to add is already there.1

When possible, send Luke the BibTeX rendering of your needed citation from http://inspirehep.2

net. Except...3

For any documents in docdb, just send him the docdb numbers. Please use the form bib:docdbNNNN4

for the label in your text; Luke will format the actual reference properly.5

(For the TDR you can stop reading this section here.)6

Note that the bib file is not in LATEX format and in particular does not indicate comments via %7

characters. (Again, guidelines are in the file itself.) The generated bibliography reflects the order8

in which citations are referenced in the text, not the order of entries in this file.9

JabRef (http://www.jabref.org/) is a cross-platform Java GUI that can be used to search bib-10

liographies, possibly investigating duplicities, by working on any loaded .bib file.11

3.7.2 Referencing Citations12

Referencing citations is done like \cite{strunk} which gives [7]. To reference multiple citations13

at the same place, use \cite{strunk,ref2,ref3} which gives [1,2,3].14

(Compiling the bibliography entries into the document requires an extra step: run “bibtex” on15

guidance.tex, then run pdflatex on it again a couple of times. Otherwise you’ll see [?] here and no16

bibliography entry at the end.) The key strunk matches an entry in the common/tdr-citedb.bib17

file (as relative to the top-level directory).18

3.8 Vendors and Trademarks19

Please only reference specific vendors when the particular vendor choice is significant. We should20

use a consistent scheme for these.21

Accompany the first mention of a commercial product with a footnote. This will improve read-22

ability by allowing for quick identification of the commercial term in question. Do not use the23

trademark symbol ™ or registration mark ® in the text, but use it in the footnote where appro-24

priate. Add the footnote only on the first occurrence of the product name in a chapter. Most25

commercial product names should be capitalized. Use a short version of the commercial product26

name in the text itself.27

The structure of the footnote should be the following: Begin with a short descriptive phrase. Then28

give the name of the company. Add ™ or ® according to what the company does on their web site.29

Then provide the company’s top-level URL. If an electronic address does not exist, use a physical30





http://www.jabref.org/


mailing address. Example:1

In your text, write “The component installation requires one Widgetmaster2

2000\footnote{Widgetmastermaker\texttrademark{} Widgetmaster 2000 iron bending machine,3

Widgetmastermaker\texttrademark{} Power Widgets http:widgetmastermaker.com.} because4

...”5

3.9 Standard LATEX Sectioning, “The DUNE Way”!6

Most documents get subdivided into chapters (for larger documents) and/or sections and subsec-7

tions. Please subdivide according to these standards:8

• A subdivision of a larger portion should have content that relates to some aspect of the larger9

portion.10

• If you create one subdivision, create at least one more. Otherwise, the topic of your one11

subdivision is (by definition) the same as that of the larger portion.12

• In your LATEX source, add lines of percent signs (comments) to make it easy to find where13

sections begin and end, as illustrated in the source for this file. (This really helps the editor!)14

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%15

Please capitalize all significant words in a heading (this is a change from previous DUNE docu-16

ments).17

The following sectioning macros are available, ordered from bigger to smaller:18

\chapter{A Chapter}19

\section{A Section}20

\subsection{A Subsection}21

\subsubsection{A Subsubsection}22

We recommend that you stop the subsectioning at this point, but you can go down a couple of23

levels further. Starting from \subsection, this produces the following:24

3.9.1 A Subsection25

This is a subsection.26



3.9.1.1 A Subsubsection1

This is a subsubsection.2

3.9.1.2 A Second Subsubsection3

Remember, if you have one, you need at least one more.4

3.9.2 A Second Subsection5

Ditto.6


Chapter 4: English Standards for LBNF/DUNE Documents 4–29

Chapter 41

English Standards for LBNF/DUNE Docu-2

ments3

This chapter provides guidelines on terminology, grammar, punctuation, and other general writing4

guidelines for use in LBNF/DUNE documents.5

4.1 DUNE and LBNF-related Terminology6

Please see the file common/glossary.tex for defined terms. To use terms defined there, you will7

typically use \dword{label} in your text. Variations include:8

• \dword{label} nominal term9

• \dwords{label} plural term10

• \Dword{label} capitalized term11

• \Dwords{label} capitalized and plural term12

• \dshort{label} force usage of the abbreviated term13

• \dlong{label} force usage of the full term14

For example, to refer to the photon detection system, a glossary term has been defined:15

\newduneabbrev{pds}{PDS}{photon detection system}16

{The \gls{submodule} system sensitive to light produced in the LAr}17

Now, everyone can refer to this in the text as \dword{\pds}, and it will compile as “PDS.” If the18



editors decide to change it to “PD” later, they can easily do it globally.1

Not all of the following terms are in the glossary; those that are, are labeled as such (purposely2

starting each line with lower-case letter for clarity):3

• antiwhatever not anti-whatever (e.g., antineutrino, antimatter...);4

• “muon antineutrino,” not “antimuon neutrino”;5

• minimum ionizing particle: MIP (use \dword{mip});6

• beamline, not “beam line” or “beam-line” (use \dword{beamline});7

• “dual-phase module,” not “double-phase module” (use \dword{dp});8

• “detector” should be used for the entire ND or FD, not for a module;9

• use Far Detector or Near Detector with initial caps. (use \dword{fd} or \dword{nd});10

• use ProtoDUNE not protoDUNE;11

• avoid ProtoDUNE jargon, e.g., “APA-2”;12

• “Facility” is a common noun, unless the word “facility” is in the name of the structure;13

• “detector module” = any 10 kt portion of the 40 kt FD (use \dword{detmodule});14

• for non-reference design, call it “alternative,” not “alternate” (moot for TDR?);15

• “a TPC in a 10 kt module,” not “a 10 kt TPC”; Remember 1 kt is metric and defined as 1Gg;16

• co-spokespersons not co-spokespeople;17

• “universe” in general, not “Universe.”18

• computer program names: Use italics on first use per chapter. Exceptions, e.g., art, should19

always be italicized to distinguish them from common English words, in this case “art.”20

4.2 Spelling, Voice, Grammar and Punctuation21

First, Nora Ransom’s Red Pen Retired blog collects much wisdom for the scientific and technical22

writer. In particular, we recommend the entries on conciseness and efficiency: Use Anglo-Saxon23

and Cowboy English.24


http://redpenretired.blogspot.com/

http://redpenretired.blogspot.com/2014/07/use-anglo-saxon.html

http://redpenretired.blogspot.com/2014/07/cowboy-english.html


In this section we provide the standards for DUNE.1

Spelling, voice:2

• Standard English rules for capitalization apply. Do not promote common nouns or adjectives3

to proper nouns or adjectives.4

• Use American spelling: e.g., ionization (not ionisation), flavor (not flavour) and so on.5

• In general, avoid use of first person (e.g., I, we, our). “We” may appear in introductory6

sections.7

• Avoid use of second person, i.e., “you.”8

• The gender-neutral “singular they” is to be used in preference to “he” or “she” or “he/she”9

or other ; e.g., “the installer must wear a hard hat when they enter the cryostat.”10

• Use tables and figures to highlight content. It increases readability. Accompany this content11

with appropriate text.12

• Use active voice wherever possible, e.g., “the field shaping coils and the cathode structure13

share identical features...” or “the design follows an extensive review...”14

• Use consistent terminology. (If you call it a spade here, call it a spade there.) Use DUNE15

Words as much as possible!16

• Expand abbreviations at first occurrence. Use DUNE Words (https://dune.bnl.gov/17

docs/technical-proposal/dune-words.pdf)!18

• Do not split infinitives (see exceptions below). E.g., “to choose carefully” is good, but “to19

carefully choose” is bad.20

• Depending on placement, the words just, only, not may need to split infinitives, e.g., “just21

to prove a point” versus “to just prove a point” versus “to prove a point just...” have slightly22

different meanings.23

• Avoid starting sentences with an acronym; precede it with “A” or “The” if possible, or spell24

out the term.25

Numbers:26

• Generally, spell out numbers one through ten. Use numerals for 11 and above.27

• Avoid starting sentences with a numeral.28

• Use numerals when giving dimensions, weight, distance, etc. Other usages that always use29

numerals, for example, are dollars ($1 billion, not $1,000,000,000), ratios, etc. Also tables30






use numerals exclusively (exceptions may exist).1

• Speaking of monetary amounts, symbols for currencies are acceptable, e.g., \euro \textsterling2

(or \pounds) \textyen \rupee to get e, £, ¥, | respectively. The Brazilian real is written3

R\$ to get R$.4

• Examples of adjacent numbers: seven one-ton-rated-or-less pickups ... two vans (one cargo,5

one equipment)... one eight-passenger suburban, one-hundred fifty 7m cables or 150 seven6

meter cables ...7

Punctuation:8

• Notice that “e.g.,” (means “for example”) has two periods and a comma; so does “i.e.,”9

(means “this is”).10

• Normally commas and periods go inside of quotations; semi-colons and exclamation points11

go outside. (In previous item, the commas are part of the terms in quotes.)12

• Minimize capitalization in captions.13

• Even if a normal English word is used as part of the proper name of an element of the14

experiment (part of the detector, a software package, etc.,) leave it in lower case, e.g., anode15

plane assembly.16

• Do not pluralize abbreviations using an apostrophe (’) following the abbreviation. Example:17

TDRs are important design documents. Not TDR’s. (See Problems with the Apostrophe18

– Exception: Use an apostrophe when the abbreviation or acronym has internal periods.19

– Exception number 2: Use nu sub e plural (and others) with apostrophe; e.g., many ν’s20

do not make light work. You may use the full word, e.g., “neutrino” in this case.21

• Avoid single quotation marks (’). Best to use italics to set off special references. Use double22

quotes for actual quoted material.23

• Use “Oxford commas” (e.g., after the y in “x, y, and z”)24

4.3 Abbreviations25

• look for commonly used terms and abbreviations in common/defs.tex, and add to it as you26

see fit27

• can use ND, FD for near and far detector28


http://redpenretired.blogspot.com/2014/10/problems-with-apostrophe.html


• USA not US1

• UK not U.K.2

• Ph.D not PhD.3

• “a” liquid argon TPC, and also “a” LArTPC (i.e., a “lar” TPC not an “ell-ay-are-TPC”)4

• kt not kt (kiloton only when used as in “a kiloton of LAr is...”)5

• Avoid the use of “ton” or “tonne”; instead use 1000 kg. Also use the abbreviation kt as called6

for.7

• Use LAr and LN (not LN2) for liquid argon and nitrogen, respectively.8

• Avoid GAr or GN for gaseous argon and nitrogen, just write them out.9

4.4 Hyphenation10

• to separate for emphasis: use two dashes together: -- in text, e.g., “the system – not to11

mention its three subsystems – does such and such”12

• antiwhatever not anti-whatever (e.g., antineutrino, antimatter...)13

• beamline not “beam line” or “beam-line”14

• “long-baseline experiment” (with hyphen) vs. “long baseline of the experiment” (without)15

• world-class but worldwide16

• readout, not read-out (when used as a noun or adjective); e.g., “the DAQ readout (system)17

supports...” but “in order to read out the DAQ...”18

• offline, not off-line19

• hyphen in double-beta decay, (and inverse-beta decay)20

• hyphen when first adjective modifies following adjective, not the noun. E.g. “deep-underground21

location” vs. “located deep underground”; this is not strictly necessary; use as you see fit for22

clarity.23

• no hyphens between number and unit (this is a change from CDR); i.e., an 8m pipe.24

• avoid use of the slash between words, use “and” or “or”. (Only use and/or when really25



necessary).1

4.5 Lists2

• In paragraphs that enumerate lists of things, use bullet or numbered lists (itemize or enu-3

merate in LaTeX) unless it seems overblown.4

• Normally use bullets. Use numbers only if there is an implied order to your list; e.g., steps5

in a procedure, priority, etc.6

• If bullets seem overblown, use open-close parens with number, e.g., (1) blah, (2) blahh, ...7

and (n) blahhhhh. I.e., do not use other formats like 1), 2), or (a), (b)... etc.8

• Use a stem sentence to introduce a list and write the stem in a complete sentence, wherever9

possible.10

• Avoid using the term “list,” “listed,” “below,” and so on, in stem sentences. It is redundant.11

• Follow parallel construction in lists; e.g., all phrases, all single words, all sentences, all phrases12

beginning with an action verb, ...13

• Use the right punctuation, i.e., use periods after complete sentences. Use either commas or14

semicolons after phrases. No punctuation at all for lists of words. There can be variations15

on this.16

• Use consistent capitalization. Initial cap the first word in a list if it is a sentence or phrase.17

• Use only up to two sub-levels of lists.18

• It is an oversight if some of the lists in this chapter don’t follow all these rules!19

4.6 Common Errors20

• Element names are not capitalized except when their symbols are used. I.e., “argon” and21

“Ar”; “gold” and “Au.”22

• Use the term “comprise” to mean “include” not “compose.” The word comprise means “to23

be composed of.”24

• Verbiage does not mean “text.” It means wasted or superfluous text.25



• Enormity does not mean huge as in “enormous.” Enormity means evil.1

• Do not interchange the words “affect” and “effect.” Affect is used as a verb and effect is2

almost always used as a noun to mean the result of a cause. (As a verb it means “to bring3

about” as in “to effect a change.”)4

• Use “impact” as a noun and not as a verb to mean “affect.”5

• Use of “less” and “fewer”: Fewer is associated with quantity that can be counted. Less is6

associated with volume or mass. “Fewer people have less mass after eating at McDonald’s7

than have more mass.”8

• Use of “that” and “which”:9

– Use “that” for restrictive clauses (clauses that cannot be removed without altering the10

meaning of the sentence). E.g., “She uses the chair that goes with this desk.”11

– Use “which” for non-restrictive clauses (clauses that can be removed without altering12

the meaning of a sentence.) Tip: Use “which” in conjunction with a comma and check13

if that clause can be removed without changing the sense. E.g., “A desk like this, which14

would be too low for you, should have a chair like that.”15

• Use of the word “concur”: You concur with someone and you concur in an idea or an opinion.16

• The opposite holds true with the word “disappoint.” You are disappointed with something17

and disappointed in someone.18


Chapter 5: Reviewing and Editing 5–36

Chapter 51

Reviewing and Editing2

While reviewing, it is possible to mark up the document with simple LATEX macros as provided by3

the “todonotes” class.4

Note: if you do not see the examples in this section your copy may have been built with the5

“final” option turned on.6

5.1 Inline “fixme”7

You may prefer to place an inline note to mark up the text. This can be accomplished with a8

\fixme{...} command, e.g.,9

5.2 Margin Notes10

You can easily add notes to the margine which are associated with some text using: run spellcheckerrun spellchecker

11

\todo{run spell checker.}12

5.3 Highlighting13

If you wish to add a comment on some section of text you may with a comment.14

\hlfix{highlight it}{This shows how.}15


Chapter 6: Important Files in the Document Repository 6–37

Chapter 61

Important Files in the Document Repository2

This chapter describes some of the more technical aspects of the LBNF/DUNE LATEXsetup. Various3

aspects of the configuration are pulled out into separate files to keep things well organized. Some4

files are meant to be edited by contributors, others are only for the technical editing team; these5

latter are labeled “Please do not edit this file” below.6

6.1 The Main File7

A new main file will likely be started only by the technical editors. There is one for each volume8

(if a document is split into volumes). It is the file that you compile to create the document9

or the volume. It appears in the top level directory of the repository. These files are named10

volume-(something).tex (or (document-name).tex if not multi-volume). They should be the11

only (name).tex files at this directory level.12

The main file...13

1. sets the document class (see Section 6.3;14

2. sets the graphics path;15

3. inputs the preamble;16

4. opens the document environment;17

5. inputs the “init” file;18

6. Redefine the volumes subtitle when document is split into volumes19

7. inputs each chapter file;20



8. inputs the “final” file (which provides the bibliographical information); and1

9. closes the document environment.2

To start a new document, you would copy the guidance.tex to a new name and edit as directed3

by the comments. As an example, the main file of the physics volume of the DUNE TDR might4

be volume-physics.tex.5

Please do not edit this file.6

6.2 The Content Files: Text and Figures7

These are the content files that you create and/or edit. Depending on the document, they may be8

collected at the top directory level of the repository or under a subdirectory. Images typically go9

under a figures directory.10

If several volumes of a document are collected into a single repository, each under its own sub-11

directory, it is recommended to have a figures directory under each subdirectory. Only figures12

common to multiple volumes would be placed in the top-level figures directory.13

6.3 The LATEX Class File14

All of the LATEX configuration for the document that pertains to the general LBNF/DUNE style15

is in the td-pdr.cls file. (The name of this file may change from document to document; it will16

be the only xxx.cls file.) The class takes some options that control high-level style, e.g.,:17

\newcommand{\toprowrule}{18

\arrayrulecolor{gray}19

\specialrule{1.2pt}{0pt}{1pt}20

\arrayrulecolor{black}21

}22

Please do not edit this file.23

6.4 Document-wide LATEX Files in common/24

Multi-volume documents are supported and should use the common/ subdirectory to house any25

information that is to be shared between volumes. Because we reuse formatting from one document26



to the next, the single-volume documents (e.g., the ProtoDUNE-SP TDR) also use this directory.1

The expected “common” files include:2

defs.tex macros defining common terms. You may want to work with your team to determine3

an appropriate set of them, then enter them into this file.4

units.tex macros defining how to use quantities and units. You may want to add some.5

preamble.tex a file that largely includies the above files along with any extra LATEX configuration6

that goes before the document environment begins. Please do not edit this file.7

glossary.tex containing words and abbreviations that you want in a glossary.8

citedb.bib the BibTeX database file (name may change; ‘bib’ will remain the same). You will9

add your references here in the proper format; examples are provided at the head of the file.10

init.tex Any content that goes in the document environment but before the first chapter. It11

typically should set the title page, ToC/LoF/LoT. Please do not edit this file.12

final.tex Any content that goes in the document after the last chapter. It typically contains13

the commands related to producing the glossary and the bibliography. Please do not edit14

this file.15

clean.sh When compiled in unix with pdflatex or similar, intermediate files get created. This16

script removes all the generated files except the output pdf.17

The content of many of these files should in part be kept in sync across all document repositories.18

Specific documents may place additional files in this common/ directory that should be shared19

document-wide. For example, volumes of the TDR may include a standard common/intro.tex.20

6.5 Getting the Files and Compiling after your Changes21

Detailed instructions for getting the files and compiling a volume are given on main GitHub page22

for the repository supplying this document at https://github.com/DUNE/document-guidance.23


https://github.com/DUNE/document-guidance



REFERENCES 6–41

References1

[1] DOE Office of High Energy Physics, “Mission Need Statement for a Long-Baseline Neutrino2

Experiment (LBNE),” tech. rep., DOE, 2009. LBNE-doc-6259.3

[2] A. Heavey and B. Viren, “DUNE TDR SP Requirements/Specs Excel Template,”.4

https://docs.dunescience.org/cgi-bin/Private/ShowDocument?docid=11074.5

[3] B. V. David DeMuth, Anne Heavey, “DUNE TDR DP Requirements/Specs Excel Template,”.6


[4] A. C. Villanueva et al., “DUNE FD Interface Document: High Voltage to CISC,”. https:8

//docs.dunescience.org/cgi-bin/private/ShowDocument?docid=6787&version=1.9

[5] D. Christian, G. Karagiorgi, D. Newbold, and M. Verzocchi, “DUNE FD Interface Document:10

SP TPC Electronics to joint DAQ,” DUNE doc or LBNF doc NNNN, 2018. https:11

//docs.dunescience.org/cgi-bin/private/ShowDocument?docid=NNNN&asof=2019-7-15.12

[6] B. V. David DeMuth, Anne Heavey, “DUNE TDR DP Risks Excel Template,”.13


[7] W. Strunk, Jr. and E. B. White, The Elements of Style. Macmillan, third ed., 1979.15


https://docs.dunescience.org/cgi-bin/Private/ShowDocument?docid=11074


https://docs.dunescience.org/cgi-bin/private/ShowDocument?docid=6787&version=1



https://docs.dunescience.org/cgi-bin/private/ShowDocument?docid=NNNN&asof=2019-7-15


