I'm writing up a PhD deliverable (which will show up here eventually) using LaTeX, which is my preferred tool for such things, since I also use it for papers, and will eventually be using it for my thesis itself. For this last document, I experimented with a few packages and techniques for organising the document which I found useful, so I thought I'd share them.

What version is this anyway?

I habitually store and develop my documents in git repositories. From time to time I generate a PDF and copy it off elsewhere to review (e.g., an iPad). Later on it can be useful to be able to figure out exactly what source built the PDF. I achieve this using

\newcommand{\version}{\input|"git describe --always --dirty"}

And \version\ somewhere in the header of the document.

Draft mode

The common document classes all accept a draft argument, to enable Draft Mode.


Various other packages behave differently if Draft Mode is enabled. The graphicx package, for example, doesn't actually draw pictures in draft mode, which I don't find useful. So for that package, I force it to behave as if we were in "Final Mode" at all times:


I want to also include some different bits and pieces in Draft Mode. Although the final version won't need it, I find having a Table of Contents very helpful during the writing process. The ifdraft package adds a convenience macro to query whether we are in draft or not. I use it like so:

This page will be cut from the final report.

For this document, I have been given the section headings I must use and the number of pages each section must run to. When drafting, I want to include the page budget in the section names (e.g. Background (2 pages)). I also force new pages at the beginning of each Section, to make it easier to see how close I am to each section's page budget.

\section{Work completed\ifdraft{ (1 page)}{}} % 1 Page


Two TODO items in the margin

Two TODO items in the margin

Collated TODOs in a list

Collated TODOs in a list

The todonotes package package is one of many that offers macros to make managing in-line TODO notes easier. Within the source of my document, I can add a TODO right next to the relevant text with \todo{something to do}. In the document, by default, this is rendered in the right-hand margin. With the right argument, the package will only render the notes in draft mode.


todonotes can also collate all the TODOs together into a single list. The list items are hyperlinked back to the page where the relevant item appears.

  This page will be cut from the final report.


comment 1
Thanks a lot! I don't know how I have written two theses and three books so far without todonotes. Am already including it in my PhD thesis!
Comment by Gunnar Wolf,
comment 2

As I tend to forget to use a trailing \ or \{} after a macro, I usually use the xspace package to work around that, i.e. something like that should work

\newcommand{\version}{\input{|"git describe --always --dirty"}\xspace}
Comment by CArsten,
comment 2

The \version command did not work for me because I am using latexmk(1) and generate dvi and ps files as well. So, it seems the \input{|cmd} command is only available in pdflatex(1). After reading a bit more, I came up with a version that works for my use case as well. Here is it (in case, you're interested in compiling ps and dvi files as well):

 {\immediate\write18{git describe --abbrev=4 --always --dirty  > version.tex}}


Version & \input{version}
Comment by Christian Barthel,