The two volumes of The Architecture of Open Source Applications were typeset with LaTeX and printed through Lulu. I couldn’t have finished the AOSA books without the generosity of people all over the world who posted their LaTeX tips to forums and blogs. This series of posts pays some of that back by sharing what I learned.

This is the third post in the series.

#### LaTeX to Lulu

2. Fonts and Captions
4. Custom Commands and Environments
5. Other Useful Packages and Settings
6. Pulling It All Together

This post is about how we styled the tables of contents and the chapter titles for the two Architecture of Open Source Applications books.

\usepackage{tocloft}  % to typeset table of contents

\renewcommand{\cftchapfont}{\sffamily}     % set TOC entries to sserif
\renewcommand{\cftchappagefont}{\sffamily} % set TOC page numbers to sserif

Then I wanted to change the size and layout of the title for the contents
page.

% format title of TOC: make sure this matches chapter head format as set below
\renewcommand{\cfttoctitlefont}{\hfill\Huge\sffamily}

Even though you probably want your chapter titles and your contents page to have roughly the same look, they are set in different places in LaTeX. As you can see, I made a note to myself to make sure the table of contents title matches the chapter title pages. I’m looking at the book right now and it turns out they don’t match at all: the table of contents header is right-justified and the chapter headers are left-justified; the table of contents header is set to LaTeX’s Huge size and the chapter headers are merely huge. Well, at least they’re the same typeface!

Lesson Learned: I should have either flagged this with a “FIXME”, which we grepped for before finishing the book, or added it to my list of things to do in Things immediately when I wrote the comment, rather than hoping I would stumble on it again later on.

You can control how many levels of header you want to display in the table of contents, and how many of the levels should be numbered:

\setcounter{tocdepth}{0} % sets what level of header is shown in the TOC
\setcounter{secnumdepth}{1} % sets what level of subsect. are numbered

We only listed chapter names (level 0), not section names. Since each chapter was written by a different author or team of authors, everyone was using sections differently and listing them wouldn’t have been consistent or helpful.

LaTeX doesn’t expect each chapter to have a different author, so we had to set up some custom commands:

\newcommand{\chapterauthor}{}
\newcommand{\chapterauthortoc}{}

We created a custom chapter enviroment called aosachapter to declare the title, label and authors of each chapter. Each chapter starts something like this:

\begin{aosachapter}{Scalable Web Architecture and Distributed Systems}{s:distsys}{Kate
Matsudaira}

Here’s the declaration for that environment:

\newenvironment{aosachapter}[3]
{ \renewcommand{\chapterauthor}{#3} \chapter{#1} \label{#2}
\addtocontents{toc}{\hspace{1cm}\textit{\textsf{by \chapterauthor}}\protect\par} } {  }

The addtocontents command builds the table of contents using the chapterauthor value we defined. The chapter and label settings are built in to LaTeX.

In Volume I we ran into a problem. Some chapters had a long list of authors which didn’t break nicely in the table of contents or the chapter title pages, so we inserted LaTeX’s newline command (\\) in the list of names to force the list to break nicely.

However, in the table of contents the second line didn’t indent properly — it started flush with the left margin instead of lined up under the first line of names. So we created a new environment called aosachaptertoc based on aosachapter, but which took an extra parameter. Then we passed in a second list of authors with the same newlines, but with an \hspace*{0.9cm} at the beginning of the second line, and used that value to populate the table of contents.

\newenvironment{aosachaptertoc}[4]
{ \renewcommand{\chapterauthor}{#3}
\renewcommand{\chapterauthortoc}{#4}
\chapter{#1} \label{#2}
\addtocontents{toc}{\hspace{1cm}\textit{\textsf{by \chapterauthortoc}}\protect\par} } {  }

So in the chapters with many authors, we declared the chapter with \begin{aosachaptertoc} instead of \begin{aosachapter}, like this:

\begin{aosachaptertoc}{VisTrails}{s:vistrails}{Juliana Freire, David Koop, Emanuele
Santos, \\ Carlos Scheidegger, Claudio Silva, and Huy T.\ Vo}{Juliana Freire, David
Koop, Emanuele Santos, \\ \hspace*{0.9cm} Carlos Scheidegger, Claudio Silva, and
Huy T.\ Vo}

I know, incredibly kludgy. You do what you have to do.

#### Chapter Title Pages

Here’s how we formatted the chapter title pages. LaTeX has a perfectly sensible default for chapter title pages, but we wanted to mess around with it.

\usepackage{titlesec} % to format chapter title pages

titlesec is the package that gives you control over the format of chapter title pages.

Here’s how we defined chapter title pages in Volume II:

% format chapter title pages
\titleformat{\chapter}
[display] % shape/type of title
{\ttfamily} % formatting commands applied to both label and title
{\vspace{-2cm} \hfill \large [chapter\kern0.15em\thechapter]}
{2cm} % separation between number and chapter title
{\huge\sffamily} % code preceding title. Last cmd can take arg, which is title
[  % everything inside [] comes after the title
\Large % make text that follows large
\thispagestyle{plain} % suppress page numbers
\chapterauthor % insert chapter author name
]% end of what comes after title

titleformat is a command provided by titlesec. The display option means I want the label (“Chapter N”) in a different paragraph than the chapter title.

The next line says I want the label and the title to be in our code font (ttfamily), but I actually override that later and put the title in the sans-serif font.

The next line defines the label. I put in some vertical space to push the label down the page, and then a hfill which right-aligns the text by “filling” the horizontal space before it. Then I set the text size to be large and finally define the actual label: “[chapter n]“, in square brackets, all lower case. (It’s probably the most stylistically daring thing in the entire book!)

I had to use the kern command to bring the chapter number a little closer to the “chapter” label, because the spacing in Inconsolata is very loose.

The next line defines the horizontal space between the label and the title, and the line after it sets up the size and typeface for the title itself.

Next there’s the title, and then there’s the stuff after the title: in our case,the author name(s). I set the text size to be Large (a little smaller than the title), make the pagestyle plain (so there’s no page number on the first page of the chapter) and then display the chapterauthor, which you’ll remember we set in the aosachapter environment.

(I don’t know why I set the pagestyle in the middle of all that instead of at the end.)

Chapter titles are one of the few layout things I did differently from Volume I to Volume II. Here’s what they looked like in Volume I:

I never liked how the label looked. I wanted something really dramatic, like a really huge number, but LaTeX doesn’t like you to set type really huge. So I tried to create drama in the difference between the type size of “Chapter” and the number, but that ended up looking awkward, especially since I couldn’t get the kerning right for each chapter. I ended up throwing up my hands for Volume I, but I’m glad I got to revisit it for Volume II because I really like the funny little square-brackets-and-code-font label I came up with:

Next time: Special Commands and Environments