Matthew West

LaTeX Quick Reference

Documentation

Templates

Miscellaneous Tips

Git repository layout for papers

Each paper is stored in its own git repository, with the following directory structure.
paper_topic_name                        #  string used for repo, tex, and bib files
+-- 1_submitted_paper
|   +-- paper_topic_name.tex
|   +-- refs_topic_name.bib
|   +-- journal_class.cls               # any files needed for the journal latex style
|   +-- figures
|   |   +-- temp_vs_time.pdf            # descriptive names for figures (not fig1.pdf, etc)
|   |   +-- error_vs_stepsize.pdf
|   |   `-- ...
|   +-- data                            # data files that generate the figures
|   |   +-- Makefile                    # Makefile that will re-generate all figures
|   |   +-- temp_vs_time.csv            # use the same name as the resulting figure
|   |   +-- plot_temp_vs_time.py        # plotting scripts, use names like plot_.py
|   |   `-- ...
|   `-- submitted_paper_topic_name.pdf  # actual PDF file submitted
+-- 2_reviews
|   +-- review_1.pdf                    # individual reviews
|   +-- review_2.pdf
|   `-- editor_statement.pdf            # instructions and summary from editor
+-- 3_response_to_reviews
|   +-- response_topic_name.tex
|   `-- sent_response_topic_name.pdf    # actual PDF file sent to editor
`-- 4_revised_paper
    +-- paper_topic_name_revised.tex
    +-- refs_topic_name_revised.bib
    +-- journal_class.cls               # copy here any other files needed
    +-- figures                         # copy here all the figures again
    |   +-- temp_vs_time.pdf            # edit figures as needed
    |   +-- error_vs_stepsize.pdf
    |   `-- ...
    +-- data                            # copy all data again and edit as needed
    |   `-- ...
    `-- submitted_paper_topic_name_revised.pdf  # actual PDF submitted

What is committed to the repository? Following the usual rules for git repositories, we don't commit any files that are automatically machine-generated, such as the latex .aux, .bbl, and .log files. This also includes the PDF file generated by LaTeX, which should not be committed to the repository. This rule is so that we don't continually have conflicts with these files. The figure PDF files should be committed, however, as they may be expensive or difficult to regenerate (needing a specific version of Python, for example).

Reproducible figure generation from data. Whenever feasible, all the data and scripts that are needed to generate the figures should be included in the paper repository. There should be a Makefile so that typing make will reproducibly regenerate all the figures. Running individual scripts like plot_temp_vs_time.py should regenerate the corresponding temp_vs_time.pdf figure. This system means that we always know what we are actually plotting, and we can easily make formatting changes to figures without having to do error-prone manual figure generation.

Making directories in order. As the paper progresses through each phase of the publication process we successively make the directories 1_submitted_paper, 2_reviews, etc. When we conclude each phase we commit a copy of the exact PDF files that sent to the journal with a submitted_ prefix. We then never edit the files in this directory again, but instead we copy everything to the directory for the next phase and make edits there. This means that we always have a clear record of exactly what happened during the publication process.

Extensions to more phases. If there are more rounds of revision then we continue to make new directories with names like 5_reviews_v2, 6_response_to_reviews_v2, 7_revised_paper_v2, etc. If we resubmit to a different journal then we will have 5_submitted_to_jcp, 6_reviews_from_jcp, etc.