Review Authoring

Review Authoring

Introduction

The PDG review authoring system consists of:

The Reviews tool in PdgWorkspace, where you can see all PDG reviews, the list of reviews where you have any responsibility, download source files, generate PDF files of a review in different formats, and manage the status and other details of each review.
Packages in the PDG SVN repository, where the source files for reviews in LaTeX (RPP/reviews) and TeX (LegacyRPP/reviews) are stored.
The PDG LaTeX style and related tools and utilities.
Utility scripts for the editor.

While both reviews in LaTeX and in the old TeX/TeXsis format are supported for now, all PDG reviews will be converted to LaTeX as soon as possible. All new reviews must be written in LaTeX.

A few hints on how to install and run LaTeX on different platforms can be found here.

Steps in authoring a PDG review

The normal progression of a PDG review through the authoring and refereeing process is illustrated in the figure below:

As the review progresses through these steps, the correct review status must be maintained in PdgWorkspace by the authors and/or overseers. Authors and overseers are notified by automatic e-mail whenever an important status change occurs that may require an action. For example, when an author marks a review as ready for refereeing, the overseer will be notified automatically.

In PdgWorkspace, the capitalized status names (e.g. "EDITING DRAFT") are shown with a color code representing whether the review is on track or late. The meaning of the different colors is:

white - the next deadline is more than 30 days away.
grey - you have no responsibility for this review.
yellow - next deadline is less than 30 days away.
red - the next deadline was missed, the review is overdue.
light green (for review authors): the draft was delivered, but you may be asked to make corrections based on referee comments and still have to provide the final draft version.
light green (for overseers): the review is waiting for the editor to make any final adjustments.
dark green: everything is done.

Instructions for authors

Log into PdgWorkspace. If necessary click on "Reviews" in the top bar to access the Reviews tool. Make sure "my reviews" is selected in the Reviews Filter. You will see the list of your reviews. For each review, your role, your overseer, the current status of this review, and the next deadline are indicated. You can generate a PDF file of latest version committed to the PDG SVN repository by clicking on the "PDF" link.
In turn, click on the title of each of your reviews. This brings you to that review's Overview page. The Overview pages gives details on present and past responsibilities, deadlines, allows you to generate the different supported formats, and more. From there you can access tabs with further information (see below).
Use the "Source files" tab to learn how to get the latest source files for the review, either using SVN (strongly recommended) or by downloading an archive. You MUST get the latest version of the source files before starting to update your review.
Update your review, and either use SVN to commit the changed source files to the PDG repository, or send the source files to your overseer and ask them to commit them on your behalf. Then use the Overview page to change the review status to "REFEREE & FINALIZE".
NEW: if your review has a booklet version, prepare it at the same time as you prepare your full review.
If you decided that the review does not need to be updated, use the Overview page to change the review status directly to "EDITOR FINALIZING".
The overseer will provide instructions for the refereeing (if needed), and will ask you eventually to provide the final draft version after taking into account comments and suggestions from the refereeing.

Instructions for overseers (and coordinators)

Log into PdgWorkspace. If necessary click on "Reviews" in the top bar to access the Reviews tool. Make sure "my reviews" is selected in the Reviews Filter. You will see the list of reviews you are overseeing. For each review, your role, the overseer of the review, the current status of this review, and the next deadline are indicated. You can generate a PDF file of latest version committed to the PDG SVN repository by clicking on the "PDF" link.
Click on the title of a review to access that review's Overview page. Use it to maintain the correct review status while the review progresses through the different authoring steps.
If refereeing is needed, decide on the referees and add them in the system via the Overview page for the corresponding review (this is very important so that the referees will be acknowledged as consultants in the Review of Particle Physics). You can see the list of past referees under "previous responsibilities" toggle and reinstate them by clicking on the corresponding link. Remove referees that are not active in the current update cycle.
Organize the refereeing, make sure that the authors provide and commit the updated source files to SVN (or commit the source files on their behalf), then pass the final draft review on to the editor by changing the review status to "EDITOR FINALIZING" via the review's Overview page.
NEW: booklet versions (if applicable) are now prepared and refereed together with the full review.

Structure of reviews in LaTeX

Below is a brief summary of important points about writing PDG reviews in LaTeX using the PDG style. For details, please see the instructions provided as part of the review source files.

Notation

To avoid name clashes, each review is assigned a unique "basename", which is displayed in the review's "Technical details" tab in PdgWorkspace. In the following, "BASENAME" (written all uppercase) stands for the review's basename. For example, the Quantum Chromodynamics review has basename "qcd". Therefore, for this review "BASENAME-main.tex" refers to the file "qcd-main.tex".

Formats

PDG reviews written in LaTeX can be automatically produced in an number of different formats, namely:

draft - this is the default and includes line numbers, shows defined labels, and prints the index entries defined by this review.
web - the web format as posted on the PDG web pages.
book - the two-column format used for the journal publication and the printed PDG Book.
booklet - if applicable, the abridged version included in the Booklet.

All formats can be generated from the reviews Overview page in PdgWorkspace.

Source files

PDG review source files consist of files edited by the review author as well as generated files. Do NOT edit generated files - your changes will be lost as the files are periodically regenerated.

Files edited by review authors:

BASENAME-main.tex - this file contains the text of your review (you may include other files)
BASENAME-booklet.tex - contents of the booklet version (if there is one)
BASENAME-preamble.tex - for review-specific definitions or packages that need to go into the document's preamble
BASENAME.bib - BibTeX bibliography entries (see below)
figures - directory where to put all figures

Generated files (do not edit them!):

Makefile - Makefile to generate different formats
pdg.cls - PDG review sytle file
pdg.bst - BibTeX style file
pdgdefs.tex - PDG standard symbols and macros
BASENAME.tex - driver file for this review in standalone mode
examples.tex

Additional LaTeX packages and review-specific definitions

To avoid problems with incompatible packages used by different reviews, you must get the editor's permission before using any additional LaTeX package in your review.
Once you have permission to use another package, you can include it in file BASENAME-preamble.tex (however, in most cases we will decide to include the package as a standard PDG package via pdg.cls).
Place any review-specific definitions in BASENAME-preamble.tex.

Review authorship

The review author information shown at the top of each review is generated from the PDG database. To include this information, use either \written or \revised, giving only month and year of the update as arguments.

If the author list is incorrect, please ask the editor to update the corresponding review authors.
If an author's affiliation is incorrect, the corresponding author should correct his/her affiliation under Settings in PdgWorkspace. After the next nightly update of the generated review files, update your working copy or download the latest version of BASENAME.tex.
If not possible to get the correct author list as described above, you can provide the full text by using \customauthor instead of \written or \revised.