README.md

Characterisation of biotic interactions between a Dyadobacter strain and the diatom Achnanthidium minutissimum (Katrin Leinweber, PhD thesis, 2012-2015)

This repository stores both the content of my thesis (sources, data, figures and supplemental files), and the software toolchain used to compile it into the final printed and electronic, official version. This repository is an experimental tech-demo & backup.

Toolchain: mixed Markdown & LaTeX

Text

1. Write in AcademicMarkdown in Sublime with Citer, as explained by Christopher Grainger.
2. Separate .md file per chapter; number in filename determines order.
3. Figures as mixed MD & LaTeX: ![**Caption.** Some more legend.\label{label}](images/image.pdf)
4. Conversion to LaTeX, then PDF with pandoc via a makefile adapted from Jens Erat's "Scientific Markdown".

References

1. Manage in Zotero collection "thesis".
   • keep selected, so that new items are automatically collected there
2. Zotero autoexporting addon set to:
   • Autoexport mode
   • timer triggered every few hours (trying to avoid temptation of make-ing PDF every few paragraphs)
   • BibTeX fileformat & thesis.bib into some backup directory
   • only custom collection/saved searches activated & thesis ticket
   • postprocess deactivated
   • simpler alternative, but with notable freezing of Zotero for few seconds & no ability to export different collections to different files: Autoexport mode, Trigger by events, C:\path\to\thesis\references.bib & [...] whole library
3. Cite by letting Citer expand known BibTeX key from thesis.bib & references.bib followed by auto-pasting it into text with PhraseExpress rule for [@{#insertclipboard}] (Win) and [@%clipboard] in TextExpander (Mac).
4. Let makefile copy thesis.bib from backup to working directory.
5. Let makefile replace PDF's link color with black for printing.

Git

1. GitHub apps for Win & Mac, or Tower.
2. Track whole working dir, except TeX, R, Windows temp files & final PDFs.
3. Create doctor branch from default master & delete default ;->
4. Try working on logical chunks, eg.
   • sentence about goal of study in introduction plus figure & paragraph about that goal in results plus raw data & R script of figure in supplemental section plus discussion with literature reference about that result
   • proof-reading of a chapter => highlight advantages of Markdown+Git workflow to supervisor at this point ;-)
   • adjusting all diagram styles (ggplot2 | theme())
   • rearranging chapters, sections or files
5. Summarise logically connected edits in single commit to branch doctor.
6. Experiment (technically and content-wise) by branching:
   • merge successes back into doctor
   • simply leave unsatisfactory experiments be => "stale" branch accessible later
   • remember to always switch the GitHub app to the right branch before 4. Try working on logical chunks

Helper tools

• helper-ansi2html.sh: exports changesets/diffs for review by non-Git user. Usage: make diff. See makefile for details. Credit: Paige Lo, yingted, Pádraig Brady & Brendan O'Connor
  • In case of error -bash: ./helper-ansi2html.sh: Permission denied, try running the command chmod +x helper-ansi2html.sh. Credit: pedro3005
• helper-checkurls.R: help to investigate broken or expired URLs. Usage: run in the R console or RStudio. Credit: Thomas Leeper.

Known issues & miscellaneous advice

• Due to an incompatibility between titlesec and pandoc v1.15.1 is required to produce an exact copy of the accepted version.
• Be prepared for newly introduced incompatibilities when updating LaTeX packages or pandoc. Don't update on a Friday and automate the testing of the final PDF for control characters like ~, {, _, etc.
• Cygwin shortcut for working directories
• Try to avoid tinkering too much & often with citation style, makefile etc. by working on a content branch most of the time, only rarely on format. Merge both into doctor only for review (maybe weekly) & final printing.