How to Write PDG Reviews in LaTeX

Overview

PDG reviews are written using a custom documentclass 'pdg' which defines various aspects of the layout.

[In all that follows, we write 'BASENAME' as a placeholder for the actual name of the review]

After the initial svn checkout of a review you will have the following files:

pdg.cls
pdgdefs.tex
pdg.bst
Makefile
BASENAME.tex
BASENAME-preamble.tex
BASENAME-main.tex
BASENAME.bib
figures/

pdg.cls, Makefile, pdgdefs.tex, pdg.bst and BASENAME.tex should not be modified in any way.

pdg.cls is the class file for the custom pdg document class. You should not modify this file in any way.

Makefile is used for compiling the review. Do not modify it in any way.

pdgdefs.tex contain standard macros (e.g. '\ev' and '\etal'). Do not modify in any way. If you have your own additional macros, put them in BASENAME-main.tex

pdg.bst is the bibtex style file, insuring that the bibliography will be in the format used by PDG. Do not modify this in any way.

BASENAME-preamble.tex can be used to add \includepackage commands specific to your review. In general, it is better to work within the predefined standard environment of the pdg class, but if you have extra packages that you find useful, you may add them here. If you have a package that you believe would be useful to other authors, you should suggest that it be included in the pdg class, removing the need for you to include it separately.

The file BASENAME-main.tex will contain the body of the review. This is where most of your work will occur.

Bibliography data must go in the single file, BASENAME.bib.

Figures must be put in the 'figures/' directory.

Review Structure

The custom pdg class is based on the latex book class. Each review is built as a chapter within a book. The basic framing commands are contained in the top-level BASENAME.tex file. The \begin{document} and \end{document} commands, and the commands related to the bibliography are contained in this file. The file that you will edit, BASENAME-main.tex, should not contain these commands.

Here is a sample valid BASENAME-main.tex file:

%%% Every BASENAME-main file should start with either \written{}, \revised{}, or \customauthor{}
%%% Note that this file must not contain a \begin{document} command.
\written{September 2018}

%%% Use section, subsection, etc, to organize content.
\section{First Section}

%%% All labels should start with 'BASENAME:' to ensure that they are globally unique throughout the RPP
\label{revtestA:sec:sec1}

This is the start of section 1 of this review.  I am typing very interesting content here.

%%% Citation tags should match those from Inspire
This is a reference to a journal article you may have seen \cite{PDG2014}

%%% You can reference tags from other reviews if you like.  Extra steps will be needed to resolve them.
This is a reference to an equation from another review:  Eq.~\ref{revtestB:eq:RadRate}

%%% We provide two custom table environments:  pdgtable and pdgwidetable.  A pdgtable should fit comfortably in a single column when the review is produced in two-column mode.
\begin{pdgwidetable}{lcccc}{This is a sample pdgwidetable}{revtestA:widetab}{h}
\pdgtableheader{Name & First & Second & Third & Fourth}
Hahahaha  & 1 & 50 & 837 & 970 \\
Bwahahaha & 2 & 47 & 877 & 230 \\
Ahahahah  & 3 & 31 & 25 & 415 \\
Tatatata  & 4 & 35 & 144 & 2356 \\
Hmmmmmm, or so they say   & 5 & 45 & 300 & 556 \\
\end{pdgwidetable}

\section{test 2}
This is another section filled with very interesting information.

%%% We provide two custum figure commands:  \pdgfigure and \pdgwidefigure.  a \pdgfigure should fit comfortably in a single column when the review is produced in two-column mode.
\pdgfigure{dalitz.pdf}{Dalitz plot distributions for $\Lambda_b^0\to\jpsi p K^-$ decays as observed by LHCb. The backgrounds have been subtracted}{revtestA:fig:dalitz}{ht}{}

This is some more text.

\begin{pdgtable}{c c c c}{This is a sample pdgtable}{revtestA:tab}{ht}
\pdgtableheader{First Column & Sec Col & Third Col & Fourth Col}
 1 & 50 & 837 & 970 \\
 2 & 47 & 877 & 230 \\
3 & 31 & 25 & 415 \\
4 & 35 & 144 & 2356 \\
5 & 45 & 300 & 556 \\
\end{pdgtable}

%%% End of the review. Note no \end{document} command here.  Also no explicit mention of the bibliography.
 

You will notice a few features:

1. No \begin{document} or \end{document}
2. The review author line is generated with one and only one of the three macros \written{}, \revised{}, or \customauthor{}
3. Labels for sections, equations, figures, and tables are prepended with 'BASENAME:' This insures that labels are globally unique throughout the RPP
4. Several customized environments are defined. Namely, pdgtable, pdgwidetable, pdgfigure and pdgwidefigure. You can still use the standard table and figure environments of latex if necessary, but these custom environments have been created to ensure uniform appearance and behavior.
5. No bibliography commands. The bibliography will be included from the BASENAME.tex file, which you must not alter.

It is important that the review appearance and layout is checked for both book (two-column) and web (single column) formats.

Author Line

The BASENAME-main.tex file should start with a command that generates the authorship line.

One and only one of the following three macros should be invoked

\written{DATE}

This will produce a line like this:

'Written on DATE by REVIEWAUTHORS' where REVIEWAUTHORS is automatically filled from a PDG managed database.

\revised{DATE}

This is like \written, but the output is 'Revised on DATE by REVIEWAUTHORS'

\customauthor{STRING}

This simply prints STRING. Use this in the uncommon case where neither \written nor \revised is appropriate.

Labels

As mentioned, all \labels should be prepended with 'BASENAME:'

E.g. \label{pentaquarks:eq:massrelation}

Custom Environments

We define a few custom environments for figures and tables. These have been created for your convenience. The default options have been chosen to ensure a uniform look-and-feel amongst all reviews. You may still use the bare latex environments if necessary.

pdgtable

\begin{pdgtable}{FORMAT}{CAPTION}{LABEL}{OPTS} ....... \end{pdgtable}

OPTS are the usual table placement options that you would set for a table. E.g. 'ht'

LABEL is the table label

CAPTION is the table caption

FORMAT is the formatting string that you would pass to the tabular environment. E.g. 'cccr'

pdgwidetable

\begin{pdgwidetable}{FORMAT}{CAPTION}{LABEL}{OPTS} ........ \end{pdgwidetable}

Usage is the same as pdgtable, but used when the table will not fit in a single column when the review is compiled in two-column (book) format.

pdgverywidetable

\begin{pdgverywidetable}{FORMAT}{CAPTION}{LABEL}{OPTS} ........ \end{pdgverywidetable}

Usage is the same as pdgwidetable, but used when the table will not fit on a single page. It will be shrunk a small amount. Additional measures may be necessary to make the table fit on a page. If pdgverywidetable is used and the table still cannot be made to fit on a page, the table will probably have to be restructured by the author.

pdgtableheader

\pdgtableheader{Col & Col & Col ...}

This is a special macro we provide for creating the labels row of a table. You do not need to use it, but if you do, it will handle spacing and horizontal lines in a consistent way.

pdgfigure

\pdgfigure{FILENAME}{CAPTION}{LABEL}{OPTS}{GRAPHICSOPTIONS}

OPTS are the figure placement options you would have passed to the \begin{figure} command

FILENAME is the bare filename of the figure. All figure files must reside in the 'figures/' directory, but you do not include 'figures/' in this option

GRAPHICSOPTIONS are any options you would have passed to the \includegraphics command. You will usually leave this blank.

CAPTION is the figure caption

LABEL is the figure label

pdgwidefigure

\pdgwidefigure{FILENAME}{CAPTION}{LABEL}{OPTS}{GRAPHICSOPTIONS}

Usage is the same as pdgfigure, but used when the figure will not fit in a single column when the review is compiled in two-column (book) format.

Bibliography

Bibtex will be used to compile the bibliography. You will create a bibtex database file, BASENAME.bib. The reference format and tags should be those produced by inspire.

Compiling

The same latex source files will be used to produce the book and web versions of the reviews. You should not attempt to add special formatting or layout commands that "fix" one format or the other.

There is a Makefile that should be used to compile reviews. The valid targets are:

'make book' -- Produces a two-column format, as published in the RPP book

'make web' -- Produces a single column format, as displayed on the PDG website

'make draft' -- Produces a single column format, with line numbers, and tags in the margins. Useful for the editing stage. In draft mode only, a per-review index will be generated. This is so you can see what index entries your review will generate when published in the full RPP book.

When checking the appearance and layout of your review, you should make sure that it renders well in both book and web formats. When recompiling you may want to start by typing 'make clean' to remove old .aux and .log files.

-- No permission to view TWiki.UserReports