Overview of PDG Review Authoring

Introduction

PDG review articles are written in LaTeX using a PDG specific LaTeX class that supports the generation of each review in different formats, namely - draft version with line numbers - single-column version for posting on the PDG website - double-column version for journal publication and for the PDG Book - abridged version for the Particle Physics Booklet

The exception to this are a few small articles or sections that were previously called "mini-reviews" (note that most former mini-reviews have become "regular" review articles authored in LaTeX). These are included within the Particle Listings and must be written using TeXsis (a version of plain TeX). If you need to update one of these small articles, please contact the editor for instructions.

The authoring and refereeing of PDG review articles is coordinated via the Reviews tool in PdgWorkspace, which is used by authors, overseers, coordinators, and the editor to keep track of the responsibilities for and status of each review article. This tool provides the necessary information to access and edit the source files of a review and to update its metadata in the PDG system. It also allows to generate PDF files of the latest version of a review in the different formats.

To edit review articles, PDG supports the following methods:

  • Overleaf (NEW). If you'd like to start using Overleaf, contact Richie Bonventre to enable access to Overleaf.
  • Use local LaTeX installation and access/upload source files via git (NEW). If you'd like to start using git, contact Richie Bonventre to enable access to git.
  • Use local LaTeX installation and access/upload source files via SVN.
  • Use local LaTeX installation and download source files as an archive (.tar.gz or .zip), then share updated source files by e-mail with your overseer. If you use this method, it is ESSENTIAL that before starting to work on your updates you first download the latest version of the review source files rather than continuing with any files you may still have from a previous update cycle. Otherwise, final formatting and editing from the previous update may be lost. This method of authoring PDG reviews is discouraged but still supported for the time being.

Please note that all co-authors working together on the same review must use the same method for editing their review's source files.

If you wish to use a local LaTeX installation, you can find some hints and recommended LaTeX distributions for different platforms here.

Using the PDG LaTeX style

Detailed instructions for typesetting PDG reviews using the PDG LaTeX style are provided in the file instructions.pdf that is included with the source files of each PDG review article. Please note that use of the PDG LaTeX style is mandatory.

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:

review-flowchart.png

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 page 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, git or Overleaf (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. With Overleaf, your changes are automatically synchronized to the PDG system. When using git or SVN, commit your updates when you are ready. If you started by downloading an archive of the source files, send the revised files by e-mail 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 (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(s) 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.

Figures, tables, labels, references, index entries, etc

Details on how to add figures, tables, references and more can be found in the instructions provided as part of the review source files.