Paper Template

meireles@umn.edu

General template for my academic papers. Its main features are:

Uses git for version control;
Taps into my centralized bibliography repo bibtexlib.
Is compatible with the online collaborative TeX platform Overleaf.
Can be embedded into git controlled R projects; see research_project_template and scifi.

Catches

The workflow relies heavily on third party git tools:

bibtexlib is embedded using non-standard git commands in git subrepo.
Embedding this template in an R project template relies on scifi and on git-utils.

Structure

main.tex: Manuscript itself.
figures: Should be the only directory holding the images that go into the manuscript.
tables: Houses all .csv files to be rendered as tables in the manuscript.
references Should be the only directory sourced for bibtex .bib libraries. It is divided into two sub-directories:
- bibtexlib: A git subrepo of my centralized bibliography repository. This repo evolves slowly, and shouldn't be written to from a paper_template instance (at least not very often).
.misctmp hidden directory used for temporary files. For example, the word counting macros write files to it.

Workflows

This is a template and thus is meant to be instantiated. There are two ways I do this: 1) instantiating it inside a research project like scifi (99% of the time), or 2) instantiating it directly, by 'forking' and cloning.

Workflow 1 (preferred)

Really nothing to do here. I simply instantiate my research_project_template using scifi, and I have an R project set up with my manuscript inside. If I choose to use overleaf with it, the scifi instantiated project will have a init-overleaf script that helps to set things up.

Workflow 2 (rarely used)

1. Basic set up

Fork this remote, giving it a name that makes sense for the paper, say my_paper
Clone the my_paper fork to a local repo.
Sanity check: Do a git remote -v and a git subrepo status --all at the root of my_paper.

Meireles:my_paper Meireles$ git remote -v
origin	https://meireles@bitbucket.org/meireles/my_paper.git (fetch)
origin	https://meireles@bitbucket.org/meireles/my_paper.git (push)

Meireles:my_paper Meireles$ git subrepo status --all
1 subrepo:
Git subrepo 'references/bibtexlib':
  Remote URL:      https://github.com/meireles/bibtexlib
  Tracking Branch: master
  Pulled Commit:   c6b2712
  Pull Parent:     6e27c16

2. Add repo to Overleaf (optional)

Log in to Overleaf and create a new blank project. I'll call it my_paper.
By default Overleaf adds a main.tex with a basic outlines to you project. Make sure to delete the contents of main.tex, otherwise you'll have to resolve a conflict when trying to git pull.
Get the git link <overleaf_git_link> from the Share menu.
Set up Overleaf (see code below)
1. Add Overleaf as a remote for my_paper. Name the remote overleaf!
2. Pull contents from Overleaf's project (usually their default main.tex).
3. Revert to previous commit.
4. Push my_paper to the Overleaf remote overleaf!

git remote add overleaf <overleaf_git_link>  # name the remote overleaf!
git checkout master                          # Make sure to be in master
git pull overleaf master                     # May complain about conflicts if I forget to delete 
                                             # the contents of Overleaf's default main.tex.
git revert --mainline 1 HEAD                 # reverts the commit generated by `git pull`
git push overleaf master                     # Now just push it!

3. Work normally...

The cycle of pull, write, commit, push happens normally, without worrying about the subrepo.
If Overleaf is set up, remember that:
1. I'll have two remotes to push and pull from!
2. Overleaf creates commits from their web interface when you snapshot a version -- so you need to remember to pull changes!

4. Updating your local `bibtexlib`.

To pull changes made to the remote bibtexlib, run the following (at my_paper root):

git subrepo pull references/bibtexlib/

Caution: Must watch out for updates in bibtex tags. A change from meireles2016 to meireles2016a can mess up my manuscript.

5. Pushing local changes to `bibtexlib`!

In principle, I will avoid making changes to bibtexlib from a paper_template fork.

If these changes in subrepos happen though, I can push them to bibtexlib with:

git subrepo push references/bibtexlib/

Sausage factory: Adding `bibtexlib` as a subrepo

This just documents how I added bibtexlib as a subrepo to this project.

Installed git-subrepo.
git subrepo clone https://github.com/meireles/bibtexlib references/bibtexlib

And that's it! Much easier than submodules or subtrees.

meireles/paper_template