Project

General

Profile

Generalities

README

Details on how to build the plots and the document itself are here or in the README_build.org text file.

Types of text content

  • The document is separated into an abstract, a number of chapters and appendices, and acknowledgments.
  • Each chapter starts with a highlighted section ("introbox" style) giving main "take away points."
  • Other highlighted sections occur elsewhere in chapters, highlighting important points or results.
  • The "regular text" is targeted towards HEP (but not necessarily neutrino physicists)
  • (postponed) Some number of "sidebar" chunks ("inset" style) may be created to reword/re-illustrate primary concepts targeted to graduate student level

Technicalities

Directory Layout

After checkout the top level directory is

lbne-sci-opp/

The document files are in a sub-directory of the same name:

lbne-sci-opp/lbne-sci-opp/  Holds the  configuration, text and figure files needed to build with latex

The directories under lbne-sci-opp/lbne-sci-opp/ are:

author/               contains files pertaining to author list
common/               (still used?) contains preamble, init, defs, final, et al
figures/              one of several directories containing figures
*fig/                 other directories containing figures, some named by topic, others by contributor
insets/               (postponed) contains tex files for insets
lbnepaper/            contains tex files with formatting info for various aspects of the doc
plots/                contains figures that are plots (there may be other plots in other figure directories)
tmp/                  a temporary dir that you don't have to worry about
trunk/                empty

Files under lbne-sci-opp/lbne-sci-opp/ are:

abstract.tex              contains text of the abstract
acknowl.tex               contains text of the acknowledgments
appendix*.tex             each appendix's tex source
chapter*.tex              each chapter's tex source
color-palette.tex         defines colors in CMYK based on cover design (from Diana in FNAL VMS dept)
container*                old files, replaced by lbne-sci-opp*
lbne.cls                  (old) defines things like margins, spacing, section heading formats, etc.
lbnebibstyle.bst          adds eprint field?  (so used with lbnebibstyle.bst?)
lbnepaper.bst             UT Physics bibliographic style based on IEEE (do we use this? Diff from utphys.bst?)
lbnepaper.cls             defines things like margins, spacing, section heading formats, etc. (Replaces lbne.cls?)
                          Called via "\documentclass{}" in file on which you run pdflatex (e.g., lbne-sci-opp(-draft).tex)
lbne-sci-opp.tex          the tex file to specify in compilation command (takes lbne-sci-opp-main et al as input)
lbne-sci-opp-draft.tex    same as above, but produces pdf with "draft" elements (e.g., linenumbers)
lbne-sci-opp-main.tex     inputs tex files under lbnepaper dir, defines chapter/appx colors and names and inputs 
                          the tex files (called by lbne-sci-opp(-draft).tex)
refs.bib                  contains full entries (copied from inspirehep.net) of citations referenced in doc
tar4arXiv.sh              script (to create tar file for arXiv, I presume; is it current?)
utphys.bst                UT Physics bibliographic style based on IEEE (do we use this? how does it differ from the other .bst files?)
wscript                   This is a waf wscript file (in Python) to build this file.  It is like a Makefile.
*.py                      Not sure what these python scripts do ???
*.sty                     latex style files; needed for various features like draft watermark

Files under lbne-sci-opp/lbne-sci-opp/lbnepaper are:

appendix.tex              contains defs for the appx headings to use in latex code
color-palette.tex         contains "definecolor" statements for the colored elements of the chapters
defs.tex                  contains defs for various Greek letter combinations and other terms used frequently
draft.tex                 contains elements to use for draft (linenumbers, water mark etc.); the file 
                          lbne-sci-opp-draft.tex inputs this file to create a draft version
feynman.tex               defines 'tikz' elements to make Feynman diagrams directly with latex code
headers.tex               several 'usetikzlibrary' commands; customizes header/footers; used for frontmatter doc no.'s
                          defines orig command for color; 
hyperref.tex              defines style for citations, urls, cross-refs, toc links, etc.
insetbox.tex              defines style for inset boxes (NOT USED AS OF 4/1/14)
introbox.tex              defines style for intro boxes
moredefs.tex              similar to 'defs.tex' just more of it
nomenclature.tex          customizes an acronym/abbrev list (NOT USED)
prelim.tex                sets style for a 'preliminary' water mark; you would input it into lbne-sci-opp-draft.tex 
                          after 'lbnepaper/draft' to create a prelim draft (CHECK)
print.tex                 sets pagestyle to glossy for a printable (non-draft) compilation; input from 
                          lbne-sci-opp-print.tex
sections.tex              makes all the pretty colored stuff in the chapters (and maybe in the TOC, not sure)
tables.tex                customizes the table format (picks up chapter color automatically); shows what commands to use.
units.tex                 defines many units used throughout the doc; implements the SI package

Additional directories to hold figures and plots which can be (re)generated in order to apply a consistent theme.

lbne-sci-opp/<plots1>/    the plotting code for plot set 1, built along with document
lbne-sci-opp/<plots2>/    the plotting code for plot set 2, built along with document
lbne-sci-opp/<plots3>/    the plotting code for plot set 3, built along with document
lbne-sci-opp/plotutil/    holds plotting utility code (at least for PyROOT, ROOT/CINT)

The build system will "install" the generated files into the associated figures directory under lbne-sci-opp/lbne-sci-opp/

SVN help

Various help on SVN. Always exchange files through SVN and not directly via email or other out-of-band methods.

Checkout

See below for checkout instructions.

Conflicts

If SVN refuses to let you commit because someone else has updated a file since you first checked out here is the procedure:

$ svn update

If no conflicts then you can commit as usual. If a conflict occurs select the

p
option to "postpone". This will leave the conflicting file with both chunks of conflicting text. It will need to be hand-edited. When that is done:

svn resolve --acept working the-file.tex

Then commit.

Consistent plots and figures

Ideally, the figures/ directory is empty and that all figures are built along with the document in a way that they have a consistent look and feel. This includes label and plot sizes, fonts and colors.

Figures built with the document

In order to apply consistent style it is best if figures and plots can be built by code that is committed to the document repository and which makes use of the supplied utility code (described below). This will allow the editors to assure consistency and to remake/tweak plots independently from their original authors.

Each <plots>/ sub directory holds the code to produce one or more related plots. These directories may be chosen based on author or section name or some other criteria.

Plotting utility code documentation

t.b.d. for PyROOT and ROOT/CINT.

Guidelines for plotting code

  • Commit a simple script (PyROOT or ROOT/CINT preferred) which produces plots or figures using the above utility code in PDF format
  • Commit a concise data file (ROOT preferred) file which contains the input on which the plotting code uses. This should be histogram level data, not (large) ntuples/trees.
  • Structure your script so that it can be called by specifying input data file and output PDF files. Eg:
# for PyROOT implementation:
$ ./myscript.py data.root plot.pdf
# for ROOT/CINT implementation:
$ root -l 'myscript.C("data.root","plot.pdf")'

In the second case you can pass in the command line arguments by writing myscript.C as:

void myscript(const char* infile, const char* outfile) { ... }

Non-ROOT (t.b.d.)

Final form figures

If figures and plots must be provided in final form and not built as part of the document they should strive to:

  • Follow the agreed document styles
  • Be provided in a suitable format (do NOT run them through PowerPoint!)
    - PDF/EPS for truly vector content (plots, lineart, wireframe CAD)
    - JPEG for photographs or renderings with color shading
    - PNG for image data that is inherently rasterized. Using this format almost always means the image has already been reduced in quality.

Feynman diagrams

All Feynman diagrams should be produced in LaTeX using: t.b.d.

Automated build system

The build system handles:

  • produce figures/plots from committed plotting code
  • "installs" the results into the appropriate sub-directory under lbne-sci-opp/lbne-sci-opp/<topic>/
  • run LaTeX (pdflatex) to produce a final PDF document
  • produce an archive file (tar/zip) ready and suitable to submit to the arXiv

Automated document building

The document comes with all that is needed to build the document except for LaTeX itself and related tools. For building/rebuilding the figures and plots ROOT, nuosc and and other software is required to be installed.

To check out the document, pick your favorite method:

# SVN, no commit
$ svn checkout http://cdcvs.fnal.gov/subversion/lbne-sci-opp
# git-svn, no commit
$ git svn http://cdcvs.fnal.gov/subversion/lbne-sci-opp

# SVN, with commit
$ svn checkout svn+ssh://p-lbne-sci-opp@cdcvs.fnal.gov/cvs/projects/lbne-sci-opp
# git-svn, with commit
$ git svn clone svn+ssh://p-lbne-sci-opp@cdcvs.fnal.gov/cvs/projects/lbne-sci-opp

Remember to get a valid Kerberos ticket if you wish to commit.

To build the document use the supplied "waf" program.

$ cd lbne-sci-opp/
$ ./waf configure build

The built document (and any temporary files) are found under build/. You can direct it to another location by giving waf the argument --out=/path/to/build.

Manual build

The document can also be built in "the usual manner" as in fact it must be for arXiv submission.

$ cd lbne-sci-opp/
$ pdflatex main.tex
$ pdflatex main.tex

This assumes that the bibtex .bbl file is up to date and the included plotting code has been run and the results available.