ReviewTool < Pdg

---+ Review Authoring

%TOC%
---++ Introduction

The PDG review authoring system consists of:
   * The [[https://pdgprod.lbl.gov/pdgprod/PdgWorkspace/Reviews.action][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.<b><br /></b>

A few hints on how to install and run !LaTeX on different platforms [[LaTeXHints][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:

     <img alt="review-flowchart.png" height="400" src="%ATTACHURLPATH%/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 [[https://pdgprod.lbl.gov/pdgdev/PdgWorkspace/Reviews.action][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 [[https://pdgprod.lbl.gov/pdgdev/PdgWorkspace/Reviews.action][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 [[ReviewsInLaTeX][more detailed documentation on how to write reviews in !LaTeX]].
---+++ 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 [[https://pdgprod.lbl.gov/pdgprod/PdgWorkspace/Account.action?act=4][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

Figures must be included using \pdgfigure or \pdgwidefigure for a single-column or double-column wide figure in the book format, respectively. These !LaTeX macros are wrappers that include the figure, generate a label, and define the caption.
   * For now only .pdf figures can be used (automatic conversion of .eps and other formats may be enabled in the future).
   * Use vector figures (rather than raster images taken e.g. as screen) whenever possible.
   * Raster figures or images are only acceptable in high resolution, please use vector figures whenever possible.
   * Put all figures into subdirectory figures.
---+++ Tables

Tables must be included using the PDG table environments \pdgtable or \pdgwidetable environments for single-column or double-column wide tables in the book format, respectively.
   * If this is an unreasonable restriction for your table, please discuss with the editor.
---+++ Labels

To avoid name clashes with other reviews, all labels must be of the format BASENAME:TYPE:yourlabel, where TYPE is "fig" for figures, "tab" for tables, and "sec" for sections.
   * For figures use: BASENAME:fig:...
   * For tables use: BASENAME:tab:...
   * For section labels use: BASENAME:sec:...
---+++ References and bibliography

References are handled using !BibTeX (maintaining references as a series of \bibitem entries is only acceptable during the transition phase). To add a reference to your review:
   * Look up the reference in [[http://inspirehep.net/][INSPIRE]] and download its !BibTeX entry (see bottom of the "Information" tab for the article, under "Export").
   * Add the !BibTeX entry to your review's .bib file. Note the article tag assigned by !INSPIRE - you can see it in the first line of the !BibTeX entry, after "@article{".
   * Cite the reference with "\cite", using the article tag assigned by INSPIRE.
   * If INSPIRE does not have the reference you wish to cite (e.g. in the case of private communications), you may write your own !BibTeX entry using an article tag of the form "RPP:BASENAME:...".
---+++ Index

The Review of Particle Physics includes a global index. To add relevant terms from their reviews, authors should mark these terms using \index{keyword}. For example "Quantum Chromodynamics (QCD \index{QCD}) is ..." would add the term QCD to the index (note that the keyword provided to \index is not printed). In the default draft mode an index page showing the entries from your review is automatically generated.
---++ Technical information

The following pages provide further technical information:
   * [[ReviewsInLatexTutorial][Tutorial and technical HowTo on writing PDG reviews in !LaTeX]]
   * [[LaTeXHints][A collection of hints on how to run !LaTeX on different platforms]], including
      * A list of additional !LaTeX packages you may need to install
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
png	review-flowchart.png	r1	manage	184.9 K	2018-09-28 - 23:11	Beringer	Illustration of typical steps in review authoring
This topic: Pdg > ReviewTool
Topic revision: r12 - 2019-01-28 - Beringer