Tutorial: reviews in Latex

Before the tutorial

Make sure to have install on your laptop a recent version of Latex.
download from here a test version of a review intro.tar
extract the files in the archive (if using a command line prompt, use tar -xvf intro.tar).
cd intro
compile it with the following commands:
- pdflatex intro
- bibtex intro
- pdflatex intro
- pdflatex intro
or alternative, if you have make installed, type the following command:
- make

if you have these packages installed, and updated, and still it does not compile, write an email to support@pdg.lbl.gov

We will use a dedicated database for the review: TutorialPdgWorkspace.
Once you open this webpage, you should see database: tutorial on the top left of the page, right under the PDGworkspace logo
More details about the workflow fore reviews and tip on naming conventions can be found here: https://pdgdoc.lbl.gov/Pdg/ReviewTool

Open PDGworkspace TutorialPdgWorkspace.
Select Reviews from the top row, and then select my reviews from the drop-down menu under Review Filters
In your list of reviews, you should see one titled "LaTeX Tutorial". Click on the title, and it will take you to the overview tab for this review.
Under the sources file tab, you can see the instructions on how to check out your review. If you can, please run the svn command in a command line prompt. Otherwise, download the tar file from the pdgworskpace interface and extract the archive.
cd latex_tutorial (or click on the extracted directory)
you need to compile the latex code. Type the following lines in a command line prompt:
- pdflatex latex_tutorial
- bibtex latex_tutorial
- pdflatex latex_tutorial
- pdflatex latex_tutorial
or
- make
Now you should have a pdf file available titled pdf_latex.pdf. Open and inspect it.

Now let's edit the main body of the review.
Open with your favorite text editor the file latex_tutorial-main.tex
After the command with the revision date (\revised{August 2018}), you can add some text.

Use the standard latex syntax:
\section{Title of the section}\label{basename:sec:_meaningful name_}

To add a figure, make sure to add a figure into the subdirectory figures (there is already a file in the subdirectory for your convenience)
the command to add a figure in your review is the following:
\pdgfigure{option to determine the position }{ the name of the file, found in the figures directory }{other options}{ your caption }{ label }
For example:
- \pdgfigure{intro96.pdf}{A typical ideogram}{latex_tutorial:figure:ideogram}
- \pdgfigure{intro96.pdf}{A typical ideogram}{latex_tutorial:figure:ideogram}{width=0.4\textwidth}
- \pdgfigure{intro96.pdf}{A typical ideogram}{latex_tutorial:figure:ideogram}{width=0.4\textwidth}{h!}
If you want to add a reference to the figure in the text, you can use the following command:
\ref{label}
For example: see Fig. \ref{latex_tutorial:figure:ideogram}
good practice for the label is to use: basename:figure:_some meaningful name_

To add a table, we use the following environment :
\pdgtable{}{ label }{ your caption }{ dimension of the table }

for example, to add a table with three columns, with the text centered:

    \begin{pdgtable}
    {h}{intro:table:mytable}{This is an example table}{|c|c|c|}
    My Table & 1.5 & $ 1.3\%$\\
    \end{pdgtable}

If you want to add a reference to the table in the text, you can use the following command:
see Fig. \ref{intro:table:mytable}

References are handled using BibTeX. To add a reference to your review:
- Look up the reference in 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.
For example, add the following reference: https://inspirehep.net/record/1691634 in latex_tutorial.bib, and then add a reference in latex_tutorial-main.tex, using the command:
\cite{}

open the tutorial pdg workspace using this link: TutorialPdgWorkspace
under Review Filters, choose "my reviews" from the drop-down menu
click on the name of your reviews that you want to migrate from texSis to Latex
under the source file tab, you can find the command to check out the teXsis version of your review
make sure that you have these files saved somewhere safe, you will need them later

ask Kirill in person, or send an email to support AT pdg.lbl.gov, to change your review in the tutorial database from teXsis to Latex
open again the tutorial pdg workspace using this link: TutorialPdgWorkspace
Under Review Filters, choose "my reviews" from the drop-down menu
Click again on the same review, and check that now the database point to the Latex version. To do that, once you click on the name of one of your review, you can check under the Technical Details tab if the format field correspond to LaTeX. If not, ask for help.
go back in the Overview tab
click on draft link under Generate latest version (PDF), the current version of the review will appear. It should contain only the title and the authors.
download the Latex version of your review, following the instructions under the source file tab. Make sure to check out this code in a different folder wrt of the code in teXsis

open the Tutorial pdgworkspace TutorialPdgWorkspace, navigate to the review you're about to modify, and then update its status under the Overview tab.
- click on update
- click on start editing draft
Now you can start copying the text from your review in teXsis to the main body of the review in Latex.
- Suggestions:
  - copy a small amount of text at the time, and then test if it compiles
  - if there are equations, you'd have to change to syntax. Equation in latex are added using the equation environment. A working example is:
```
           ==\begin{equation}\label{BASENAME:eq:myname}<br />
           N_{exp} = \sigma_{exp} \times \int L(t) dt.<br />
           \end{equation}==
          
```
Once you've migrate the all review (or part of it for testing), you can check the updated source code into svn. Make sure you run the following command from the directory where the Latex version of the review was downloaded. svn status : it will list the files that you modified svn commit -m "Brief summary of your changes" : it will copy the changes in the svn repository
Now you can go into the tutorial pdg workspace TutorialPdgWorkspace, select your review, and then under the Overview tab click on draft link under Generate latest version (PDF): you should see the updated version of the review. * If you're happy of your change and they are final, update the status of the review under the Overview tab.
- click on update
- click on pass to editor