(r5) ReviewsInLatexTutorial < Pdg

---+ Tutorial: reviews in Latex

%TOC%<br /><br />

---+ Before the tutorial

---++ Setting up 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 [[%ATTACHURL%/intro.tar][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 neither of the set of commands work, check if you have available the following LaTeX packages required for PDG reviews in LaTeX (check error messages in the log file):
      * ifthen
      * color
      * float
      * amsmath
      * graphicx
      * xspace
      * titling
      * fancyhdr
      * titlesec
      * geometry
      * import
      * lineno
      * showlabels
      * bibunit

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

---+ At the tutorial

   * We will use a dedicated database for the review: [[https://pdgprod.lbl.gov/tutorial/PdgWorkspace/Reviews.action][TutorialPdgWorkspace]].
   * Once you open this webpage, you should see %RED% *database: tutorial* %ENDCOLOR% 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

---++ Check out and compile *LaTex Tutorial* review

   * Open PDGworkspace [[https://pdgprod.lbl.gov/tutorial/PdgWorkspace/Reviews.action][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.

---++ Edit the test *LaTex Tutorial* review

   * 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.

---+++ Add a section
   * Use the standard latex syntax: <br />
   ==\section{Title of the section}\label{basename:sec:_meaningful name_}==

---+++ Add a figure
   * 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: <br />
    ==\pdgfigure{option to determine the position }{ the name of the file, found in the figures directory }{other options}{ your caption }{ label }==
   * For example: <br />
      * ==\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: <br />
    ==\ref{label}==
   * For example:
    ==see Fig. \ref{latex_tutorial:figure:ideogram}==
   * good practice for the label is to use: ==basename:figure:_some meaningful name_==
<!--   * use ==\pdgfigure== or ==\pdgwidefigure== for a single-column or double-column wide figure in the book, respectively-->

---+++ Add a table
   * To add a table, we use the following environment : <br />
    ==\pdgtable{}{ label }{ your caption }{ dimension of the table }==
   * for example, to add a table with three columns, with the text centered:
    <verbatim>
    \begin{pdgtable}
    {h}{intro:table:mytable}{This is an example table}{|c|c|c|}
    My Table & 1.5 & $ 1.3\%$\\
    \end{pdgtable}
    </verbatim>
   * If you want to add a reference to the table in the text, you can use the following command: <br />
    ==see Fig. \ref{intro:table:mytable}==
<!--   * use ==\pdgtable== or ==\pdgwidetable== environments for single-column or double-column wide tables in the book format, -->

---+++ Add a reference
   * 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: <br />
    ==\cite{}==

---++ Start migrating one of your own review from teXsis to Latex %RED%-- Advanced, optional part%ENDCOLOR%

---+++ Download one of your reviews in teXsis
   * open the *tutorial* pdg workspace using this link: [[https://pdgprod.lbl.gov/tutorial/PdgWorkspace/][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

---+++ Download the empty Latex version for the same review
   * 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: [[https://pdgprod.lbl.gov/tutorial/PdgWorkspace/][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. %RED% Make sure to check out this code in a different folder wrt of the code in teXsis %ENDCOLOR%

---+++ Start updating the review in Latex
   * open the Tutorial pdgworkspace [[https://pdgprod.lbl.gov/tutorial/PdgWorkspace/][TutorialPdgWorkspace]], navigate to the review you're about to modify, and then update its status under the *Overview* tab.
      * click on %BLUE%update%ENDCOLOR%
      * click on %BLUE%start editing draft%ENDCOLOR%
   * 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:
         <verbatim>
           ==\begin{equation}\label{BASENAME:eq:myname}<br />
           N_{exp} = \sigma_{exp} \times \int L(t) dt.<br />
           \end{equation}==
          </verbatim>
   * 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 [[https://pdgprod.lbl.gov/tutorial/PdgWorkspace/][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 %BLUE%update%ENDCOLOR%
      * click on %BLUE%pass to editor%ENDCOLOR%

-- %USERSIG{ElisabettaPianori - 2018-10-15}%