Coding Conventions

Structure

There is a Src/ and a Tex/ top-directory. Use Src/ for the root -files, root -macros (.C), and any other raw file format which has to be changed to pdf and any other complimentary information to be stored. The Tex/ is for everything! which should go into the document.

Please place the graphics and the files related to particular sections in their respective Tex -subdirectory. The current subdirectories for Src/ and Tex/ are:

• exp - Detector and Accelerator chapter
• int - Introduction
• main - Common files and Front material
• phys - Detailled Physics chapter
• scripts - Root and other macros
• soft - Software and Analyis Framework chapter
• sty - Style files
• sum - Summary

Substructure

Please use different files for structuring the major parts (as listed above). It makes not much sense to have everything in a single document. The major parts are LaTeX-\chapters subdiveded into LaTeX-\section, LaTeX-\subsection, and LaTeX-\subsubsection. They all reside in seperate files. Sometimes a even finer splitting is neccessary. Please keep in mind: the more files you have, the easier the maintainance is in the final editorial process.

Graphics

The document will be typeset in pdflatex rather than in usual LaTeX. This might imply a few changes to your usual coding habits which are not severe but have to be known. One is that eps -files can be used, but they have to be transcoded to pdf -files for their use inside the document. In order to make this happen, you have to use includegraphics instead of and other eps -include environment which you may have used so far. You also need epstopdf being installed to run the makefile. Please also refrain from using the file extension. If the filename is my-picture.eps, just use my-picture as the filename. You also can use png - and jpg -files. But please avoid pixeled files if you show root -histograms!

Please make sure, that all file names relate to the Tex/ top directory and do not use absolute paths.

Example: \includegraphics[width=\swidth]{tgt/pe/tgt_pe.pdf}

To have consistent width of the plots you may consider using

• \hwidth (half width of a column)
• \swidth (width of one column)
• \dwidth (width for a 2-column figure)

Bibliography

We will use bibtex to do the bibliography for us. Sample bibtex files are located in each Tex/ -subdirectory. Please add the references you need and the makefile (or build at Windows machines) will take care of it. Please do not add more bibliography files to the repository. The following examples may act as a guide for your own references.

Example: Article

@Article{bib:phy:amsler2004kn,
author    = "Amsler, C. and others",
collaboration = "Crystal Barrel",
title     = "Study of antiproton annihilation on neutrons into omega pi-pi0",
journal   = "Nucl. Phys.",
volume    = "A740",
year      = "2004",
pages     = "130-146"
}      

Example: Technical Report/Proposal

@TechReport{bib:vtx:ATLAStdr,
author = {The ATLAS collaboration},
title = {ATLAS Technical design report}
}

Example: Proceedings

@InProceedings{bib:phy:page00,
 author = {Page, P.R.},
 title = {Proceedings of the `pbar2000 Workshop'},
 editor = {D.M. Kaplan and H.A. Rubin},
 year = {2001},
 pages = {55--64},
 address = {Chicago}
}

Units and Tools

We have included myunits.sty (command for units), mymath.sty (some math tools) and pennames.sty (particle nameing scheme) for general use. You may find other useful abbreviations in def_panda_sym.tex (abbreviations for particles and particle pairs as well as some more units) and def_panda_cmd.tex (latex shortcuts). For any value with unit, please use the style $123\,\mm$ (for 123 mm). This uses the standard unit command and has the right space between the number and the unit.

Here are some of the definitions: (all require mathmode, if you need some others, have alook into the files!)

• fm -> \fm
• micron -> \mum
• mm -> \mm
• cm -> \cm
• m -> \m
• ^o (degrees) -> \degree
• % -> \percent
• ' (add a prime) -> \prm
• MeV -> \mev (same for keV, GeV)
• MeV/c -> = \mevc (same for keV, GeV)
• MeV/c² -> \mevcc (same for keV, GeV)
• MeV²/c⁴ -> \mevccsq (same for keV, GeV)

To have the figures equal in size, the commands \hwidth (half width) \swidth (single column width) and \dwidth (full width=double column width) have been defined, please use them for the width option in includegraphics (Example \includegraphics[width=\swidth]{file.pdf}. Since we may change the layout a little bit before publication, using these abbreviations makes a change much easier.

Naming conventions

In order not to mix up references in latex from several parts of the manuscript, it is essential to introduce rules for the naming of all labels which can be referenced to (i.e. \label{} and \ref{}).

We have agreed on the a structure of levels, separated by colons ":".

• 1st level denotes the type of reference, i.e.: sec, fig, eq, tab, bib (Section, Figure, Equation, Table, References)

• 2nd level denotes the chapter, as in the naming convention chosen for the files; e.g.: int (Introduction)

• 3rd level labels are up to the ones, who write the chapters. There may, of course, be further sub-levels like qcd, spin if a QCD section and a spin pyhsics section.

So one can already refer to, say, the Software chapter by stating: see Sec.~\ref{sec:soft} and a figure on the eta_c in the Physics chapter could possibly be labeled:

\label{fig:phys:qcd:ccbar:eta_c}

To make the use of references consistent please use

• \refeq{label} for equations,
• \refsec{label} for sections,
• \reffig{label} for figures, and
• \reftbl{label} for tables.

Or one of the following, if its the first word in the sentence \Refeq{label}, \Refsec{label}, \Reffig{label}, and \Reftbl{label}.

Examples

... this is shown in \reffig{fig:vtx:geom} ...

... more details can be found in \refsec{sec:trk:stt} ...

\Refeq{eq:pid:cherenkov} has been derived ...

Tables and Figures

We will have a twocolumn document (apart from frontmatter). So tables and figures may be typeset in a single or spanning over two columns. Please use different environments to select your choice.

Within one column use

\begin{table} ... \end{table}

\begin{figure} ... \end{figure}

If it should span over the full width of the document please use

\begin{table*} ... \end{table*}

\begin{figure*} ... \end{figure*}

Tables and figures should be centered and have captions with an entry for the list of figures (avoid \cite and \ref therein) and an entry for the text appearing at the figure/table like

\caption[list of figures entry]{caption in the text}

Histograms

A set of .C root -macros can be found in the Src/scripts repository branch. There are

• palette.C (for a nice color chart for 2D-density plots)
• style.C (global settings for improved fonts, ticks etc and to get rid of 3-d effects)
• logo.C (a macro which creates a stripped panda logo in each histogramm) and
• example.C (shows how to use it) The example also produces the pdf file needed for the Tex code.

Please use them. We may update style.C and logo.C frequently to accomodate whishes and to solve problems, therefore don't cut-and-paste the code, but use it as shown in the example. Please make also sure that - like in the example - the pdf output goes into the designated Tex/Xyz subdirectory. We will include the macros in the make process.

-- KlausPeters - 11 Jan 2008