This repository holds the source for a document that provides guidance on writing and editing The DUNE TDR in LaTeX according to the standards that we’ve set up for DUNE and LBNF. It is designed to follow its own guidance and thus can be used as an extended example and as a reference. Previous versions of the guidance document have been used for:
Please look at the LaTeX files under the “guidance” directory to see how to make headings, labels, tables, figures, etc., according to standards we’ve set. Compare it to the built PDF of the document.
See Physics TDR Volume Development for information on coordination and management for the physics volume of the TDR.
This page tells you how to access and build the LaTeX guidance document contained in this repository. These instructions are also valid for accessing and building the document that you will be contributing to, e.g., The DUNE TDR.
This page also provides all the instructions you will need for interacting with git as you pull and push document files.
This shows how to clone the TDR repository and build the physics volume. Bare bones. See more detailed and non-TDR-specific information in the “Best practices” and “Getting Started” sections below.
- Get a github account and send your username to Brett (see bottom of page).
- See below or Click here if you experience authentication problems.
- Install Git on Mac, requires Mac OS X, Apple ID, XCode, and Command Line Tools.
- Github Desktop Manage your GitHub flow using this dandy interface.
If you need a reliable LaTeX installation, Tom Junk has installed texlive 2017 in his area on the dunegpvm’s at Fermilab. Feel free to use it! Just login and run his setup file:
$ ssh dunesl7gpvm01.fnal.gov for bash and sh: $ source /grid/fermiapp/products/dune/texlive2017/setup.sh for tcsh and csh: $ source /grid/fermiapp/products/dune/texlive2017/setup.csh $ mkdir /my/work/area
- Type this sequence to clone the repository:
$ cd /my/work/area $ git clone https://github.com/DUNE/DUNE-TDR.git
- Do a test edit and test build (yes, run pdflatex twice)
$ cd DUNE-TDR $ pdflatex volume-physics $ pdflatex volume-physics
- Type this sequence to commit (after it builds successfully):
$ git commit -a -m "Brief explanation of what you updated" $ git push
Please follow these four important guidelines that will help avoid headaches:
- Always do a pull immediately before you begin working on a file just in case someone else modified it recently.
- We recommend that you compile frequently as you compose and edit; it will be easier to resolve any compilation problems.
- Make sure the document compiles before you commit it and push it to the repository. Ask Anne if you need help.
- Commit and push immediately after you finish your edits so that others have the best chance of picking up your changes before they edit. (Yes, git can resolve conflicts, but it’s better to avoid them.)
This section describes how to
- check out the source to a document from GitHub, and
- build the document locally, either as draft or print-ready,
using the document-guidance document as an example. Note that you don’t have permissions to push anything to this repository. When working on a “real” document, substitute the actual document repository name for document-guidance in the commands shown on this page.
To get “push” access to a repository, sign up for a GitHub account if you do not yet have one, then send the user name to Brett Viren (see contacts below) and indicate which repository(ies) you need to access. (If you instead prefer to fork and issue pull requests, that can likely be accommodated. Check with the document technical editors, listed below.)
If you plan to use SSH, make sure you’re authenticated:
- Go to Settings/Keys
- Click on big green “New SSH Key”
- Paste your public SSH key
- If problems click here for information to help you or, just use HTTPS and password authentication.
You will “clone” each desired remote repository from GitHub into a dedicated directory on your local machine. First, set up a “parent” directory to contain the repository(ies), shown here as: /my/work/area.
Each GitHub repository web site provides a URL above the list of files; it starts with “https” and ends with “.git”. The HTTPS URL can be used for anonymous cloning and then later can be pushed to (see below) by supplying your GitHub password. The SSH URL requires uploading a public key to GitHub but then no password need be given. More information is at Which remote URL should I use?. Pick the URL you like and then cloning is simple:
$ cd /my/work/area $ git clone <URL>
For example, to clone this document-guidance repository using the HTTPS URL, do:
$ cd /my/work/area $ git clone https://github.com/DUNE/document-guidance.git
You should now see the directory
/my/work/area/document-guidance
that includes the directories and files in this repository. Now you can cd to it and start editing.
$ cd document-guidance
To make it easier to work as a team, we want people to be able to add and see editing comments in documents, and to refer to line numbers. These features are designed to appear by default when you compile.
To build the document, run pdflatex and bibtex on the main LaTeX file, in this case guidance.tex. Each repository will have a main LaTeX file; the bulk of the .tex files containing the document content should be in one or more subdirectories.
$ pdflatex guidance $ bibtex guidance $ pdflatex guidance $ pdflatex guidance
Unless bibliographic references change, you can usually see all the changes in subsequent builds by running:
$ pdflatex guidance $ pdflatex guidance
It needs to be run twice to pick up any changes to the paging and numbering.
For documents with an acronym list, we provide a compileitdraft script that includes a makeindex command. To fully compile it as draft, you would run, e.g.,
$ ./compileitdraft guidance
The technical editors are responsible for producing a clean
and properly built version of any document for internal and final
release, but anyone may compile a clean version.
To do that, replace each pdflatex guidance command
with this one like:
$ pdflatex "\def\isfinal{1} \input{guidance}"
There is also a compileitprint script that produces a clean copy. To fully compile the document print-ready, you would run, e.g.,
$ ./compileitprint guidance
Once you are done with a set of edits and have verified that the document compiles locally, it is time to commit the changes to your local cloned directory and push them to the master repository in GitHub.
Again, we strongly recommend that as you make changes to a document, you compile it frequently to easily catch and correct any errors you may have introduced. Also, please push your (compile-tested) changes to GitHub frequently so that they are available to your colleagues.
If you know that someone else may want to edit the same files, it’s a courtesy to let them know that you plan to edit them, and ping them again once you’ve pushed your updates. It’s easier than resolving conflicts later.
If you installed the GitHub for Mac (or for other platforms as available), you can use the GUI provided to pull, commit and push, if you prefer. If you use a terminal command line, here is the procedure.
$ cd /my/work/area/document-guidance # Pull down the latest commits from others just before you start: $ git pull # If this works, continue with next step. If it fails, see below. # Compile the document before you begin your editing session, to verify that it works. # Edit your files, frequently saving your changes and verifying that the document compiles. # If any of your files are new, add it/them before committing, e.g.,: $ git add path/to/the-new-file.tex $ git add path/to/figures/the-new-picture.pdf ... # When you're done, compile again, then commit and push: $ git commit -a -m "Brief explanation of what you updated" $ git push # If this fails, see below.
Sometimes git pull fails due to a conflict. If git pull doesn’t work, you need to “stash” your changes, then try to “pull” again to get the latest commits (it should work after git stash). Then “unstash” (or “pop” your changes back in) and resolve conflicts in the editor. Here is the procedure:
$ git stash $ git pull $ git stash pop # Resolve the conflicts in the affected file(s); this can be tedious. # Edit, save, add files (adding is shown above). # Make sure the entire document compiles, then commit and push: $ git commit -a -m "Your commit message" $ git push
If any commits have been pushed by others since the last time you did a git pull (or since your initial git clone if you haven’t yet pulled) then git will not allow you to push until you have done a fresh git pull.
If all else fails, save your changed files somewhere, blow away the repository and reclone it. Then remake your edits.
Note from Glenn Horton-Smith about “git merge”:
A “git merge”” will pull in the content from other commits that happened since you did the pull on which your last commit was based, and those will appear as changes or added files. So add them to the list of things to commit before you commit your merge. Don’t delete them. (The .gitignore file is set up to not bug you about extra files, so if you see changed or added files, you can be pretty sure they’re good stuff.)
Git works on all major computing platforms and many minor ones and is successfully used by all manner of people. If for some reason you don’t want to use Git we can work around that, however you need to always start by downloading the latest files from GitHub.
The Github Desktop application can be used to interface the DUNE Github repository, saving some command-line headaches.
If you are willing and able to edit in LaTeX, but don’t want to deal with Git, download the latest version of the desired file from the web-based repository, edit it and send it to Anne (see contacts below).
For those new to LaTex, you might find the real-time preview feature using the Overleaf a useful practice environment.
If you don’t want to edit in LaTeX, please talk to Anne.
- Anne Heavey <aheavey@fnal.gov> 630-840-8039 (technical editor, structure, style)
- Brett Viren <bv@bnl.gov> (LaTeX machinery and repository)
- David DeMuth <david.demuth@vcsu.edu> (LaTeX, images, general)
(last updated 25 Sept 2017)