logophile

I'm currently writing my PhD dissertation, and procrastinating by heavily customising my LaTeX environment.

The basic problem is this: I want 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, as currently working. (If it ever gets a bit stable I'll post .sty files here; if anyone wants the alpha versions feel free to mail and ask for 'em.)

1.  Necessaries

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.

1.1  Directory structure

main/thesis.tex
    /introduction/chapter.tex
                 /introduction.tex
    /experiment/chapter.tex
               /experiment.tex
    /...

texmf/tex/latex/thesis/thesis.sty
                      /thesisart.cls

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. The named chapter wrappers (introduction.tex and so on) contain basically a tiny piece of boilerplate which sets up the environment and calls the chapter.tex file in the same directory. The main file thesis.tex ignores the boilerplate files (they're for typesetting individual chapters) and directly calls introduction/chapter.tex, experiment/chapter.tex and so on for each chapter.

1.2  Contentful chapter 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/chapter.tex):

\chaptertitle{Introduction}
\introformatting

% Text of chapter here, no extras needed

\outroformatting

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.

1.3  The book as a whole

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

\documentclass{book}
\usepackage{thesis}

\let\chaptertitle=\chapter
\let\introformatting=\relax
\let\outroformatting=\relax

\begin{document}

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

\tableofcontents

\include{introduction/chapter.tex}

\include{experiment/chapter.tex}

% ... 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.

1.4  Chapter wrappers

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

\documentclass[draft]{thesisart}

\begin{document}

\input{chapter}

\end{document}

1.5  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).

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

\LoadClassWithOptions{article}

\RequirePackage{thesis}

\let\chaptertitle=\title
\newcommand{\introformatting}{%
  \maketitle
  \tableofcontents\bigskip
}

\newcommand{\outroformatting}{
  \appendix
% HERE SET UP YOUR BIBLIOGRAPHY
% Here's how you do it with biblatex:
  \printbibliography[heading=bibnumbered]
}

\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).

\RequirePackage{xr}
\externaldocument{../introduction/chapter}
\externaldocument{../experiment/chapter}
% ...

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 the xr package to make this possible. You'll need to keep the list of chapters there up to date; you'll also get warnings about multiply-defined labels because the current chapter turns up as an "external" file as well, but this doesn't seem to cause any difficulties. (You'll also need to make sure each chapter has an up-to-date chapter.aux file, otherwise xr has nothing to work with. Do this by compiling thesis.tex, otherwise chapter refs won't come out right.)

1.6  Usage

To recap:

1. To typeset the book: latex thesis.tex
2. To typeset a single chapter: latex introduction/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/chapter.tex mynewchapter/
   • remove old content from mynewchapter/chapter.tex
   • (if you're using a local variables block, change the TeX-master setting in mynewchapter/chapter.tex)
   • add \include{mynewchapter/chapter} to thesis.tex
   • add \externaldocument{../mynewchapter/mynewchapter} to thesisart.cls

2.  Possible improvements

A chapter-creation script would be very simple.

3.  Optionals

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

3.1  biblatex.sty

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 .bst postfix definition language. 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.)
            ]{biblatex}
\bibliography{strings,papers}

3.2  hyperref.sty

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)
            ]{hyperref}

3.3  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 contentful chapter files, and that can point either at the chapter template 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: 

4.  Thanks

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