While writing my PhD dissertation, I procrastinated by heavily customising my LaTeX environment.

The basic problem is this: I wanted to use the same source to both typeset the entire book (in the end) and the individual chapters (while I'm working on them; to send to other people and so on). (I'm aware that ConTeXt should allow something like this, but I'm pretty dependant on a bunch of LaTeX packages so switching would be painful.) Some text should be in the individual chapters but not in the document as a whole (boilerplate saying this is a working draft, my name, per-chapter references section, &c. &c.). Formatting might vary quite a bit between them too.

Here's the system, in it's latest incarnation (the one I used myself). Every previous incarnation has had something wrong with it, so don't expect perfection. It's getting better though.



I'll start with the bits of the setup that make the book/article distinction possible; at the end there's a short list of additional config stuff that might be useful.

The basic idea

For each chapter you have a content file. That holds (surprisingly enough) everything you've written for that chapter. You have a book file that calls each content file in turn, just as you would expect for any setup splitting chapters into separate files. But you also have a ''chapter wrapper'' file (for each chapter) which sets up article-like formatting and includes the chapter content. So whether you get a book (with many chapters) or an article (with one chapter) depends on which toplevel file (book or chapter-wrapper) you run latex on.

Directory structure



The dir main is just a container for everything, while the texmf tree is a standin for "somewhere LaTeX can see". The style thesis.sty holds generic definitions that will be used everywhere, while thesisart.cls is the class that chapters-as-articles will use.

Each chapter directory holds a content file (called content.tex) and a chapter wrapper file (introduction.tex and so on). These get distinct names because you'll run latex on them; pdflatex introduction.tex will produce introduction.pdf, which is more useful than chapter-wrapper.pdf.

The main file thesis.tex ignores the chapter wrapper files (they're only for typesetting individual chapters) and directly includes introduction/content.tex, experiment/content.tex and so on for each chapter.

Chapter content files

One point of this whole exercise is to require minimal additional markup in the chapter files themselves. Here's what I came up with (introduction/content.tex):


% Text of chapter here, no extras needed


The macros \introformatting and \outroformatting are hooks; the trick is to give them different definitions depending on whether we're including the file from thesis.tex or from a chapter wrapper.

The book as a whole

This is the beginning of the file thesis.tex, which typesets to the whole dissertation.




\title{A Heartbroken Work of Genius, Staggering}
\author{Tikitu de Jager}




% ... don't forget to set up bibliography and \end{document}

The package thesis.sty is where I'm putting everything that is needed both for the book and the individual chapters. It specifies the packages I'm using, the bibliography files (I'm using biblatex, which handily puts this in the preamble), hyphenation patterns for "Stalnaker" and "Lewis", and so on.

So all that's left for thesis.tex to do is define what to do with chapter titles (they become chapters) and intro/outros (ignore them), the title-page info (which eventually will be replaced by the requirements of an UvA dissertation), include the chapters and place a bibliography.

Chapter wrappers

The chapter wrappers (introduction.tex and so on) are similarly bare and simple.





That's really all there is to one of these. To create a new chapter, you just copy the wrapper from another chapter and give it a new name. (You have to do a bit more than that; see below.)

Thesisart: where the work gets done

The interesting stuff happens in the "thesis article" class thesisart.cls. I'll only paste the stuff that's actually needed to make everything work (note that you'll need to tweak this for your bibliography setup).

\ProvidesClass{thesisart}[2008/07/16 Articles made from thesis chapters]




% Here's how you do it with biblatex:

\author{Tikitu de Jager}
\date{Draft of thesis chapter (\today)}

% Set up cross-referencing to other chapters (chap list needs to be kept up
% to date, sigh). Also need to keep .aux files current (by compiling
% thesis.tex, otherwise the chapter refs don't come out right). Ifthenelse
% suggested by Adam Reeve (thanks!), to avoid a warning about multiple includes
% of the same document (you will need to \RequirePackage{ifthen} in thesis.sty).

% ...

Okay. So we're basing these on the standard article class, and using all the extras defined in thesis.sty. The chapter title turns into the title of the article, and we add an author and boilerplate saying this is a draft (I've used the date field for that, but it could just as easily go somewhere in \introformatting). At the \outroformatting hook we print the bibliography (they way I have it set up is biblatex style again).

Since we expect to cross-reference sections and chapters from the rest of the thesis, we use \externaldocument from the xr package to make this possible. You'll need to keep the list of chapters there up to date.[^ Another tip from Adam Reeve: depending on how you handle including files in thesis.tex, you might or might not get content.aux files generated for you -- the "import" package doesn't, while plain old \include{} does. If what you're using doesn't, you should modify \externaldocument to pick up ../introduction/introduction and similar, and you'll have to keep the aux-files up to date individually. I suspect chapter numbers won't be correct in this case, but you should still be able to refer to sections (figures, equations, whatever) correctly. ^]

Where to build output from

The general rule is, run latex whatever.tex from the same directory that whatever.tex sits in. That means you build thesis.tex from the main directory, but you build a chapter from inside that chapter's directory. (This is handy if you use Emacs and AUCTeX, see below. If you use a Makefile, for instance to build all your chapters as articles, you'll have to change to the individual directories as part of your Make rules.)


A quick cheat-sheet of things to do and places to put stuff:

  1. To typeset the book: latex thesis.tex
  2. To typeset a single chapter: cd introduction/ then latex introduction.tex
  3. Definitions for everywhere: thesis.sty
  4. Definitions for the book only: thesis.tex
  5. Definitions for chapters-as-articles only: thesisart.cls
  6. Definitions for a single chapter-as-article only: introduction/introduction.tex
  7. Adding a new chapter:
    • mkdir mynewchapter
    • cp introduction/introduction.tex mynewchapter/mynewchapter.tex
    • cp introduction/content.tex mynewchapter/
    • remove old content from mynewchapter/content.tex
    • (if you're using a local variables block, change the TeX-master setting in mynewchapter/content.tex)
    • add \include{mynewchapter/content} to thesis.tex
    • add \externaldocument{../mynewchapter/content} to thesisart.cls

Possible improvements

A chapter-creation script would be very simple. Actually I've written one, but I couldn't resist adding some complications. That means there are a few extra files lying around (the list of chapters gets its own tiny little file) so that scripts can more easily manipulate things. You're welcome to test-drive it if you'd like, but it's not ready for public release.


Here are some other details of my setup that you might find useful.


I'm using biblatex for bibliography handling. It's an extremely flexible system that does the formatting of the reference list and the citation style in LaTeX code rather than the BibTeX postfix definition language used to write .bst files. Lots of handy styles are available as package options, or you can define your own if you need something more specific. It's still in beta, but has worked perfectly for me; you can find it on CTAN.

My definitions look like this (in thesis.sty):

%%%%%% Bibliography 
% biblatex works fundamentally differently!
% - no natbib package needed
% - specify bib files in \emph{preamble}
% - use \printbibliography to typeset the result
% - formatting, citation style &c via package options
\usepackage[style=alphabetic, % Citation marks as [Jef65]
            natbib=true,      % Natbib-style cite macros \citeauthor &c.
            hyperref=true,    % Cites in pdf are links to bib (hyperref conf.)


If you're generating pdfs to share around, having clickable links is pretty handy. Here are my hyperref definitions: page and section refs become links, as do citations, and urls defined using \url{} (from the url package); with biblatex any urls in the bibliography work too.

\usepackage[final,          % override "draft" which means "do nothing"
            colorlinks,     % rather than outlining them in boxes
            linkcolor=blue, % override truly awful colour choices
            citecolor=blue, %   (ditto)
            urlcolor=blue,  %   (ditto)

AUCTeX emacs mode and TeX-master-file

AUCTeX is the fantastic (La/Con/doc/...)TeX editing mode for emacs. If you're using emacs but not AUCTeX ... well, you shouldn't be.

One handy feature for this setup is that you can tell it where the "master" file is for the current file: the one that should be fed into pdfTeX or whatever to do the actual compilation. I add a local-variables block to all my content files, and that can point either at the chapter wrapper or at the thesis depending on what I'm working on more often (changing the variable for a session is possible too, of course).

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "introduction"
%%% TeX-PDF-mode: t
%%% End: 


Reut Tsarfaty did some test-driving and pointed out some things that weren't that comfortable (or even correct). Thanks Reut!

Adam Reeve has sent me some suggestions, including one that gets rid of a (harmless but) very annoying warning. Thanks Adam!