Templates for building tex documents by several authors =============================== (E.Chudakov gen@jlab.org) 03 Oct 2011 15 Jan 2016 The idea is to keep the sources in the SVN system, that different people can edit it and build various documents. You can check it out (make a snapshot in your space) by: svn checkout https://halldsvn.jlab.org/repos/trunk/docs/tex-docs By default, the documents are build using pdflatex. It makes pdf directly (no dvi). The advantages against dvips: a) accepts JPEG, PNG and PDF for pictures b) easy cross-referencing A) STRUCTURE The structure is as follows: scripts/ # directory with several useful scripts src/ # the sources (the .tex files and pictures) README # this file run/ # directory for compiling the documents - NOT IN SVN ! - created when the first document is built The structure of src/: apparatus/ # HallD/GlueX apparatus bibl/ # bib databases computing/ # Computing for Hall D/GlueX engineering/ # Engineering for Hall D gluex_general/ # General documentation on GlueX, including full texts of older documents (pdf) icons/ # useful icons (JLab/DOE logos etc) mains/ # contains one "main" directory for each document to be built management/ # Hall D management physics/ # physics (GlueX, PrimeX etc) texnical/ # tex templates, preamble files, styles etc Directory src/apparatus/ contains subdirectories for various subsystems: bcal/ beamline/ cdc/ cher/ electronics/ fcal/ fdc/ general/ solenoid/ start_counter/ target/ tof/ trigger-daq/ upv/ For example, the directory "beamline" contains: figs/ # directory used for figures, pictures etc tdr_description.tex # various files for the CDR/TDR tdr_electron.tex tdr_intro.tex tdr_main.tex # the main CDR/TDR file for the beamline part tdr_polarimeter.tex tdr_rates.tex tdr_tagger.tex tdr_technical.tex The pictures are located in the proper directories, say beam/: beam_rates.tex # a section about the beam/protoproduction rates figs/ # appropriate figures At the start, the directory for the "mains" contained the mains for three documents: src/mains/tdr # TDR document src/mains/gx_1610_solenoid_shorts # GlueX-doc-1610 on the impact of turn-to-turn shorts in the solenoid src/mains/talk_pac38 # a talk on PAC38 - hall D status report - the BEAMER style B) BUILDING DOCUMENTS Let us assume you want to build the tdr (building the tcr document is similar) the main is in src/mains/tdr 1) cd to tex-docs 2) ./scripts/config tdr Start config Directory tdr created. 3) cd run/tdr 4) make pdf (or just make) make pdfnb - if bibtex is not needed It will build tdr.pdf By default, pdflatex is used. C) EDITING (the TDR document in this example) Tips: SVN allows to find the difference between the revisions of a text file, basically the "diff" command of UNIX. It shows the difference line-wise. Using text editors that automatically reformat every line of the text to their liking would make this tool useless. So, please try to avoid such editors, in particular if several people may contribute to the same file. 1) One can edit the existing file, say src/mains/tdr/collab.tex and rebuild the document repeating B) Then one may commit the changes to the repository: svn commit -m "A very important improvement" collab.tex 2) A new .tex file and a new picture should are added to apparatus/beamline/ apparatus/beamline/diamonds.tex apparatus/beamline/figs/diam_photo_1.jpg # this file is called from diamonds.tex apparatus/beamline/figs/diam_schem_1.png # this file is called from diamonds.tex apparatus/beamline/figs/diam_plots_1.ps # this file is called from diamonds.tex apparatus/beamline/figs/diam_plots_3.pdf # this file is called from diamonds.tex a) the file diamonds.tex must be included in apparatus/beamline/tdr_main.tex or mains/tdr/main.tex \input{diamonds} % similar to other files in the main.tex % please do NOT use \input diamonds.tex b) build other formats of diam_plots_1.ps: cd src/apparatus/beamline/figs/ ../../../../scripts/myps2epdf diam_plots_1 # convert to pdf cd ../ cat ../../../scripts/svn.template.verb >> diamonds.tex # optional - add a SVN keyword which describes the last revision c) rebuild the document, see B) d) commit the changes to the repository: cd src/apparatus/beamline/figs/ svn add diam_photo_1.jpg svn add diam_schem_1.png svn add diam_plots_1.ps svn add diam_plots_1.epsi svn add diam_plots_1.pdf svn add diam_photo_2.pdf cd ../ svn commit -m "Another change" cd beamine/ svn propset svn:keywords "Date Author Header Id" diamonds.tex # enable the keyword replacement (optional) 3) Some parts of the structure and of the text can be redefined or excluded. Many section use commands \mysection and \mysubsection. They must be defined or redefined before the section is included, say \def\mysection{\section} or \def\mysection{\subsection} depending on the document structure. The commands \fulldoc{} and \skimdoc{} are used to include or exclude parts of the text in the input files. Command \controldoc is defined in order to include only the proper parts of the controlled documents. D) PICTURES Example from beamline/ \begin{figure}[ht]\centering \includegraphics[angle=-90, width=1.0\textwidth]{figs/tdr_fixedarray} \caption[Fixed array of tagging counters]{\label{fig:fixedarray} Layout of the tagging counters on the high-energy end of the tagger focal plane, corresponding to the lowest-energy electrons from the spectrometer. The view is from above.} \end{figure} Please note that NO extension should be used in the filename. The sequence for file searching is defined in src/common/preamb_common.tex (pdf,png,jpg). Getting a piece of a page from a pdf document: \includegraphics[page=1,viewport=150 250 610 601,clip,angle=0,width=1.1\linewidth]{gluex_general/fulldocs/T2-alex_cal_rev_feb-2008} E) BIBLIOGRAPHY BiBTeX is used. I found a few duplications (with different labels) and a few typos - mostly the page numbers. I replaced the entries, whenever possible, with the standard SPIRES format. The standard SPIRES lables are not that easy to memorize, but they can be easily checked for duplications. There several bib files in src/bibl/: physics.bib # physics papers instrumentation.bib # instrumentation papers tech_reports.bib # tech report (not the GlueX docs) magnets.bib # about magnets and superconductivity gluex_docs.bib # GlueX docs (numbered, from the portal) gluex_misc.bib # miscellaneous GleuX material proceedings.bib # miscellaneous proceeding, not fit in the "physics" and other files software.bib # references to software packages, as GEANT, ROOT, PYTHIA etc books.bib # books thesis.bib # thesis material (as a rule - not easily available...) Thigs like "private communications" or other document-specific references should be put close to the main.tex of the document, to, say local.bib (see the src/mains/tdr/). F) BEAMER TALKS A BEAMER-style talk is added as an example. It is a talk on the Hall D status, given at PAC38: see the directory talk_pac38 It can be treated similar to other documents: a) tex-docs> ./config/ talk_pac38 b) tex-docs> cd ./run/talk_pac38 c) talk_pac38> make talk # this will skip the unneeded bibtex part One would need the package tikz. It is available, for example in texlive-texmf-latex-2007-37 but surely in other distributions too. G) ADDING NEW DOCUMENTS How to add a new document, say a gluex note 9999 ? a) create the main directory mkdir src/mains/gx_9999 cd src/mains/gx_9999 b) use some existing main.tex for the template: cp ../tdr/main.tex . Edit the main.tex There are a few rules: 1) TeX will search for files in several directories in the following order: src/mains/gx_9999 ; src/ ; src/texnical 2) The path to the figures can be either explicit, starting with src/ as: \includegraphics[width=0.5\textwidth]{apparatus/beamline/figs/myfigure} or one may use an offset: \graphicspath{{apparatus/beamline/}} # somewhat before \includegraphics[width=0.5\textwidth]{figs/myfigure} 3) One can add a subdirectory gx_9999/figs The pictures from this directory can be linked from, say, gx_9999/main.tex as \includegraphics[width=0.5\textwidth]{figs/myfigure} 3) The bibliography files are defined in main.tex (see the tdr document) H) EXPORTING THE DOCUMENT SOURCE There is a script to export the document source, say to the arXiv.org a) A note: one should use the \listfiles command somewhere in the preamble. It is specified in the standard preamble texnical/preamb_common.tex b) Build the document (see B)), say tdr c) in the directory run/tdr type: ../../scripts/extract_dir.com A new directory "extract" contains all the files needed d) cd extract; pdflatex main - several times to find the labels/citations A note: the BiBTeX result main.bbl is taken from the tdr directory. Actually "arXiv" expects to have the *.bbl file and does not run BiBTex. Therefore, one should not do any editing in the directory "extract", if it may change the citations. It is better to re-make the tdr directory and create the "extract" anew. % % =========== SVN info % $Header$