dune-words.tex

\documentclass{article}
\usepackage[letterpaper,margin=2cm]{geometry}

\usepackage{xspace}
\usepackage{siunitx}
\input{common/units}

\usepackage[hidelinks]{hyperref}

\input{common/defs}
\input{common/glossary}

\title{DUNE Words}
\author{Brett Viren}

\begin{document}
\maketitle
\tableofcontents

\section{Overview}

The DUNE glossary gives a concise definitions of the special
\dwords{dword} and in some cases abbreviations that are part of the
DUNE collaboration's lexicon.
The terms make up a technical vocabulary which DUNE collaborators use
when speaking and writing about their detectors and experiment.

When authoring collaboration documents or papers, particularly those
that span large parts of the DUNE scope, it is best to always refer to
\dwords{dword} through a fixed reference key provided by the DUNE
glossary and avoid ever typing a term literally into the body of the
document (as described below).
This provides the following benefits:


\begin{itemize}
\item Enforces consistent use of terms which helps more easily convey
  meaning to the reader.
\item Reduces repetitive and potentially inconsistent explanation of
  terms.  
\item Synchronizes meaning between collaborators.
\item Optionally allows hyperlinks in a PDF document from a term to
  its definition in the glossary as well as reverse links from the
  definition to locations in the text where the term is used.
\end{itemize}

\noindent Of course, slavish adherence may not always be practical but
before writing and during editing a diligent author should find
themselves continuously checking the glossary for previously defined
terms and adding new terms as needed. 
If a term is used in an unexpected manner it means that there is a
lack of \textbf{conceptual cohesion} between the authors and this
\textbf{requires discussion} before changing the definition in the
glossary. 
Changes may also require reworking surrounding text. 
The glossary is a shared resource expressing our consensus and so must
be cared for by all.

For DUNE, a \LaTeX{} file \texttt{glossary.tex} is provided which
defines some DUNE-specific macros on top of the standard
\texttt{glossaries} \LaTeX{} package. 
The DUNE-specific macros merely provide a simplified view of a subset
of the full \texttt{glossaries} functionality for defining and using
terms.
In most cases, these DUNE-specific macros should be used to define and
refer to DUNE terms instead of directly using macros from the
\texttt{glossaries} package.
However, one is still free to use the underlying \texttt{glossaries}
macros directly, and indeed in some cases this may be needed.
Following the DUNE-specific macros the \texttt{glossary.tex} file
contains the definitions of the various DUNE terms, themselves.


The rest of this document describes how to use the \dwords{dword}
macros.   
First it shows how to use currently defined terms in the document body
text. 
If finishes by showing how to extend the glossary by introducing new
terms.
For documentation on the underlying \texttt{glossaries} package see
the
\href{mirrors.ctan.org/macros/latex/contrib/glossaries/glossaries-user.pdf}{glossaries
  user manual}.


\section{Usage}

This section describes how to use \dwords{dword} in a document. 

\subsection{Integrating into a document}

To use \dwords{dword} in a \LaTeX{} document include the
\texttt{glossary.tex} file:
\begin{verbatim}
\input{glossary}
\end{verbatim}
It should be included in the preamble \textbf{after} the packages
\texttt{siunitx} and \texttt{hyperref}. 
The latter is not strictly required but will allow the resulting PDF
to have clickable glossary links. 

To generate a list of \dwords{dword} used in the document, add the
standard \verb|\printglossaries| macro provided by the
\texttt{glossaries} package where you want it to appear.

\subsection{Referencing terms}
\label{sec:referencing}

The benefit of the glossary is to use a common vocabulary throughout
the document. 
To do that one should avoid typing a literal DUNE term and instead
reference it through its \textbf{label}. 
Besides assuring consistency it allows editors to easily make sweeping
changes to the ``spelling'' of a term across the document. 
In the case of DUNE terms with abbreviations some automated
conveniences are provided such as including the abbreviation in
parenthesis the first time a term is used and only using the
abbreviation thereafter while in the text always using the same macro.

To reference an item, use one of the following macros. 
The first four cover the case of capitalization and pluralization and,
if an abbreviation exists, will automatically follow the behavior
above. 
To force an abbreviated or long form one the final two may be used.

\begin{itemize}
\item \verb|\dword{label}| nominal term
\item \verb|\dwords{label}| plural term
\item \verb|\Dword{label}| capitalized term
\item \verb|\Dwords{label}| capitalized and plural term
\item \verb|\dshort{label}| force usage of the abbreviated term
\item \verb|\dshorts{label}| force usage of the abbreviated term, plural
\item \verb|\dlong{label}| force usage of the full term
\item \verb|\dlongs{label}| force usage of the full term, plural
\item \verb|\dfirst{label}| force first usage behavior
\item \verb|\dfirsts{label}| force first usage behavior, plural
\end{itemize}


\noindent Here are several usage examples followed what they produce

\begin{description}

\item[first time] \verb|\dword{sp}|: \dword{sp}

\item[second time, nominal] \verb|\dword{sp}|: \dword{sp}.

\item[second time, long] \verb|\dlong{sp}|: \dlong{sp}.

\item[second time, force first time] \verb|\dfirst{sp}|: \dfirst{sp}.

\item[first time, multiple] \verb|\dwords{adc}|: \dwords{adc}.

\item[second time, singular] \verb|\dword{adc}|: \dword{adc}.

\item[long] \verb|\dlong{adc}|: \dlong{adc}.

\item[long, plural] \verb|\dlongs{adc}|: \dlongs{adc}.

\item[short] \verb|\dshort{adc}|: \dshort{adc}, and \verb|\dshorts{adc}|: \dshorts{adc}

\item[first time, singular] \verb|\dword{daq}|: \dword{daq}.

\item[second time, plual] \verb|\dwords{daq}|: \dwords{daq}.

\item[first time, singular] \verb|\dword{detmodule}|: \dword{detmodule}

\item[second time, capitalized, plural] \verb|\Dwords{detmodule}|: \Dwords{detmodule}

\item[first time, special plural] \verb|\dwords{apa}|: \dwords{apa}

\item[second time, special plural] \verb|\dwords{apa}|: \dwords{apa}

\item[second time, long] \verb|\dlong{apa}|: \dlong{apa}

\item[second time, long plural] \verb|\dlongs{apa}|: \dlongs{apa}

\item[second time, first] \verb|\dfirst{apa}|: \dfirst{apa}

\item[second time, first plural] \verb|\dfirsts{apa}|: \dfirsts{apa}.

\item[first time with capitalization] \verb|\Dword{cpa}|: \Dword{cpa}. \verb|\dfirst|: \dfirst{cpa}, \verb|\dlong|: \dlong{cpa}, \verb|\dlongs|: \dlongs{cpa}

\end{description}

\noindent Note the special pluralization for ``\dlongs{apa}''.

\section{Extending}

As of this writing, the \texttt{glossary.tex} file is included with a
larger document (currently the DUNE Technical Proposal). 
For future documents some effort to break out this glossary into an
independently managed file should be pursued. 
Until that happens, it is expected that this file will evolve along
and as part of each major DUNE document.

\subsection{Adding new terms}

In general, new \dwords{dword} may be added to the DUNE glossary using
the macros provided by the standard \texttt{glossaries} package. 
However, to simplify the most common cases a small number of
DUNE-specific macros have been developed. 
Their use should be preferred.

 To define a DUNE term that has no abbreviation use:

\begin{verbatim}
\newduneword{label}{term}{description}
\end{verbatim}

 To define a DUNE term with an abbreviation use:

\begin{verbatim}
\newduneabbrev{label}{abbrev}{term}{description}
\end{verbatim}

 To define a DUNE term with an abbreviation and a special plural form use:

\begin{verbatim}
\newduneabbrevs{label}{abbrev}{term}{terms}{description}
\end{verbatim}

 The macro arguments are as:

\begin{description}
\item[\texttt{label}] a key that is used to connect this definition to
  a reference in the text (referencing described above in
  Section~\ref{sec:referencing}). 
  A good choice for a \texttt{label} for a term with an abbreviation
  is to lowercase that abbreviation. 
  For terms that lack an abbreviation it is suggested to invent a
  \texttt{label} which is concise, memorable and similar to the full
  term.
  The \texttt{label} may contain spaces.
\item[\texttt{abbrev}] the abbreviation or acronym for the term (only used for \verb|\newduneabbrev|).
\item[\texttt{term}] the \dword{dword} term itself written out in
  long-hand words.
\item[\texttt{terms}] the plural form of the \dwords{dword} term.
\item[\texttt{description}] a concise but descriptive explanation of
  what the term means. 
  Avoid over specifying and over generalizing. 
  Shoot for one or two sentences. 
  One quirk is that the description must not end in punctuation. 
\end{description}

The term shown in the examples of Section~\ref{sec:referencing} are
defined like:

\begin{verbatim}
\newduneabbrev{adc}{ADC}{Analog Digital Converter}{A sampling of a voltage
  resulting in a discrete integer count corresponding in some way to
  the input}
\newduneabbrev{daq}{DAQ}{data aquisition}{The Data Acquisition system
  accepts data from the detector \acrshort{fe} electronics, buffers
  it, performs a \gls{trigdecision}, builds events from the selected
  data and delivers the result to the offline \gls{diskbuffer}}
\newduneword{detmodule}{detector module}{The entire DUNE far detector is
  segmented into four modules, each with a nominal \SI{10}{\kton}
  fiducial mass}
\newduneabbrevs{apa}{APA}{anode plane assembly}{anode plane assemblies}{One unit the SP
  detector containing the elements sensitive to activity in the LAr. 
  It contains two faces each of three planes of wires, cold
  electronics and photo detection system.} 
\end{verbatim}

Note, the use of \texttt{siunitx} to handle units and numerals in a
consistent way.
Also note that it is acceptable to use \texttt{glossaries} macros (eg
\verb|\gls{}|) to reference DUNE terms inside the descriptions of
other DUNE terms. 
Because the final glossary below only includes terms that have been
referenced, this is a good way to assure completeness.
 



\cleardoublepage
\printglossaries


\end{document}