On the Use of the tufte-book Document Class

The Tufte-LaTeX document classes define a style similar to the style Edward Tufte uses in his books and handouts. Tufte’s style is known for its extensive use of sidenotes, tight integration of graphics with text, and well-set typography. This document aims to be at once a demonstration of the features of the Tufte-LaTeX document classes and a style guide to their use.

Page Layout

Headings

This style provides a- and b-heads (that is, \section and \subsection; ## and ### in Markdown), demonstrated above.

If you need more than two levels of section headings, you’ll have to define them yourself at the moment; there are no pre-defined styles for anything below a \subsection. As Bringhurst points out in The Elements of Typographic Style,Robert Bringhurst. The Elements of Typography. Hartley & Marks, 3.1 edition, 2005. ISBN 0-88179-205-5 you should “use as many levels of headings as you need: no more, and no fewer.”

The Tufte-LaTeX classes will emit an error if you try to use \subsubsection and smaller headings. This theme warns about ##### and ###### (warning id tufte-heading-depth).

In his later books,Edward R. Tufte. Beautiful Evidence. Graphics Press, LLC, first edition, May 2006. ISBN 0-9613921-7-7 Tufte starts each section with a bit of vertical space, a non-indented paragraph, and sets the first few words of the sentence in small caps. To accomplish this using this style, use the newthought shortcode:

{{< newthought >}}In his later books{{< /newthought >}}, Tufte starts…

Sidenotes

One of the most prominent and distinctive features of this style is the extensive use of sidenotes. There is a wide margin to provide ample room for sidenotes and small figures. Any footnotes will automatically be converted to sidenotes.This is a sidenote that was entered using a Markdown footnote, the equivalent of the \footnote command. If you’d like to place ancillary information in the margin without the sidenote mark (the superscript number), you can use the marginnote shortcode.This is a margin note. Notice that there isn’t a number preceding the note, and there is no number in the main text where this note was written.

The specification of the sidenote shortcode is:

{{< sidenote number="number" offset="offset" >}}Sidenote text.{{< /sidenote >}}

Both the number and offset arguments are optional. If you provide a number argument, then that number will be used as the sidenote number. It will change the number of the current sidenote only and will not affect the numbering sequence of subsequent sidenotes.

Sometimes a sidenote may run over the top of other text or graphics in the margin space. If this happens, you can adjust the vertical position of the sidenote by providing a dimension in the offset argument. Some examples of valid dimensions are:

1.0in    2.54cm    254mm    6bl

where bl is one \baselineskip (2rem). If the dimension is positive it will push the sidenote down the page; if the dimension is negative, it will move the sidenote up the page.

While both the number and offset arguments are optional, in LaTeX they must be provided in order. To adjust the vertical position of the sidenote while leaving the sidenote number alone, use the following syntax:

{{< sidenote offset="offset" >}}Sidenote text.{{< /sidenote >}}

The parameters are named, so leaving one out tells the sidenote shortcode to use the default sidenote number.

If you only want to change the sidenote number, however, you may completely omit the offset argument:

{{< sidenote number="number" >}}Sidenote text.{{< /sidenote >}}

The marginnote shortcode has a similar offset argument:

{{< marginnote offset="offset" >}}Margin note text.{{< /marginnote >}}

References

References are placed alongside their citations as sidenotes, as well. This can be accomplished using the cite shortcode.The first paragraph of this document includes a citation.

The complete list of references may also be printed automatically by using the bibliography shortcode. (See the end of this document for an example.) If you do not want to print a bibliography at the end of your document, set tufte.bibliography.list = false, the equivalent of the \nobibliography command.

To enter multiple citations at one location,Edward R. Tufte. Beautiful Evidence. Graphics Press, LLC, first edition, May 2006. ISBN 0-9613921-7-7; and Edward R. Tufte. Envisioning Information. Graphics Press, Cheshire, Connecticut, 1990. ISBN 0-9613921-1-8 you can provide a list of keys separated by commas and the same optional vertical offset argument: {{< cite "tufte2006,tufte1990" >}}.

{{< cite keys="bibkey1,bibkey2,…" offset="offset" >}}

Figures and Tables

Images and graphics play an integral role in Tufte’s work. In addition to the standard figure and table shortcodes, this style provides special figure and table shortcodes for full-width floats.

Full page–width figures and tables may be placed with the fullwidthfigure or fullwidthtable shortcodes. To place figures or tables in the margin, use marginfigure or margintable as follows (see figure 1):

A helix inside a box with axes x, y and zFigure 1: This is a margin figure. The helix is defined by x=cos⁡(2πz)x = \cos(2\pi z), y=sin⁡(2πz)y = \sin(2\pi z), and z=[0,2.7]z = [0, 2.7]. The figure was drawn using Asymptote (http://asymptote.sf.net/).

{{< fig type="margin" src="helix.svg" label="fig:marginfig" >}}
This is a margin figure.
{{< /fig >}}

The marginfigure and margintable shortcodes accept an optional parameter offset that adjusts the vertical position of the figure or table. See the “Sidenotes” section above for examples. The specifications are:

{{< marginfigure src="…" caption="…" offset="offset" >}}
{{< margintable caption="…" offset="offset" >}}
…
{{< /margintable >}}

Figure 2 is an example of the fullwidthfigure shortcode and figure 3 is an example of the normal figure shortcode.

The graph of y = sin x
Figure 2: This graph shows y=sin⁡xy = \sin x from about x=[−10,10]x = [-10, 10]. Notice that this figure takes up the full page width.
Figure 3: Hilbert curves of various degrees nn. Notice that this figure only takes up the main textblock width.Hilbert curves of degrees 1 to 5

As with sidenotes and marginnotes, a caption may sometimes require vertical adjustment. The caption now takes a second optional argument that enables you to do this by providing a dimension offset. You may specify the caption in any one of the following forms:

{{< fig src="…" >}}long caption{{< /fig >}}
{{< fig src="…" short="short caption" >}}long caption{{< /fig >}}
{{< fig src="…" offset="offset" >}}long caption{{< /fig >}}
{{< fig src="…" short="short caption" offset="offset" >}}long caption{{< /fig >}}

A positive offset will push the caption down the page. The short caption, if provided, is what appears in the list of figures/tables, otherwise the “long” caption appears there. In LaTeX the arguments short caption and offset must be provided in order; here they are named parameters. As an example, the caption to figure 3 above was given in the form

{{< fig src="hilbertcurves.svg" short="Hilbert curves…" offset="6pt" >}}Hilbert curves…{{< /fig >}}

Table 4 shows a table in the style of the booktabs package. Notice the lack of vertical rules—they serve only to clutter the table’s data.

Table 4: Here are the dimensions of the various margins used in the Tufte-handout class.
MarginLength
Paper width8½ inches
Paper height11 inches
Textblock width6½ inches
Textblock/sidenote gutter⅜ inches
Sidenote width2 inches

Occasionally LaTeX will generate an error message:

Error: Too many unprocessed floats

LaTeX tries to place floats in the best position on the page. Until it’s finished composing the page, however, it won’t know where those positions are. If you have a lot of floats on a page (including sidenotes, margin notes, figures, tables, etc.), LaTeX may run out of “slots” to keep track of them and will generate the above error.

LaTeX initially allocates 18 slots for storing floats. To work around this limitation, the Tufte-LaTeX document classes provide a \morefloats command that will reserve more slots.

The first time \morefloats is called, it allocates an additional 34 slots. The second time \morefloats is called, it allocates another 26 slots.

The \morefloats command may only be used two times. Calling it a third time will generate an error message. (This is because we can’t safely allocate many more floats or LaTeX will run out of memory.)

If, after using the \morefloats command twice, you continue to get the Too many unprocessed floats error, there are a couple things you can do.

The \FloatBarrier command will immediately process all the floats before typesetting more material. Since \FloatBarrier will start a new paragraph, you should place this command at the beginning or end of a paragraph. Its web counterpart is the clearmargin shortcode, which pushes what follows below everything already in the margin.

The \clearpage command will also process the floats before continuing, but instead of starting a new paragraph, it will start a new page. The clearpage shortcode starts a new page when printing.

You can also try moving your floats around a bit: move a figure or table to the next page or reduce the number of sidenotes. (Each sidenote actually uses two slots.)

After the floats have placed, LaTeX will mark those slots as unused so they are available for the next page to be composed.

Captions

You may notice that the captions are sometimes misaligned. Due to the way LaTeX’s float mechanism works, we can’t know for sure where it decided to put a float. Therefore, the Tufte-LaTeX document classes provide commands to override the caption position.

Vertical alignment

To override the vertical alignment, use the \setfloatalignment command inside the float environment, or the captionpos parameter of the figure shortcodes. For example:

\begin{figure}[btp]
  \includegraphics{sinewave}
  \caption{This is an example of a sine wave.}
  \label{fig:sinewave}
  \setfloatalignment{b}% forces caption to be bottom-aligned
\end{figure}

In this theme the same figure is written:

{{< figure src="sinewave.svg" caption="This is an example of a sine wave." label="fig:sinewave" captionpos="bottom" >}}

The syntax of the \setfloatalignment command is:

\setfloatalignment{pos}

where pos can be either b for bottom-aligned captions, or t for top-aligned captions (captionpos="bottom" or "top").

Horizontal alignment

To override the horizontal alignment, use either the \forceversofloat or the \forcerectofloat command inside of the float environment. For example:

\begin{figure}[btp]
  \includegraphics{sinewave}
  \caption{This is an example of a sine wave.}
  \label{fig:sinewave}
  \forceversofloat% forces caption to be set to the left of the float
\end{figure}

The \forceversofloat command causes the algorithm to assume the float has been placed on a verso page—that is, a page on the left side of a two-page spread. Conversely, the \forcerectofloat command causes the algorithm to assume the float has been placed on a recto page—that is, a page on the right side of a two-page spread. A web page has no spreads, so captions always sit in the right margin and these commands have no counterpart in this theme.

Full-width text blocks

In addition to the new float types, there is a fullwidth shortcode that stretches across the main text block and the sidenotes area.

{{< fullwidth >}}
Lorem ipsum dolor sit amet…
{{< /fullwidth >}}

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu neque. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat. Integer sapien est, iaculis in, pretium quis, viverra ac, nunc. Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla, malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla. Donec varius orci eget risus. Duis nibh mi, congue eu, accumsan eleifend, sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum.

Typography

Typefaces

If the Palatino, Helvetica, and Bera Mono typefaces are installed, this style will use them automatically. Otherwise, we’ll fall back on the Computer Modern typefaces.

Letterspacing

This document class includes two new commands and some improvements on existing commands for letterspacing.

When setting strings of ALL CAPS or small caps, the letter­spacing—that is, the spacing between the letters—should be increased slightly.Robert Bringhurst. The Elements of Typography. Hartley & Marks, 3.1 edition, 2005. ISBN 0-88179-205-5 The allcaps shortcode has proper letterspacing for strings of FULL CAPITAL LETTERS, and the smallcaps shortcode has letterspacing for small capital letters. These commands will also automatically convert the case of the text to upper- or lowercase, respectively.

The sc shortcode (LaTeX’s redefined \textsc) also includes letterspacing. The case of its argument is left as is, however. This allows one to use both uppercase and lowercase letters: The Initial Letters Of The Words In This Sentence Are Capitalized.

Document Class Options

The tufte-book class is based on the LaTeX book document class. Therefore, you can pass any of the typical book options. There are a few options that are specific to the tufte-book document class, however. In this theme they are keys of [params.tufte] (or of the tufte: front matter); the table at the end of this section lists them.

The a4paper option will set the paper size to A4 instead of the default US letter size.

The sfsidenotes option will set the sidenotes and title block in a sans serif typeface instead of the default roman.

The twoside option will modify the running heads so that the page number is printed on the outside edge (as opposed to always printing the page number on the right-side edge in oneside mode).

The symmetric option typesets the sidenotes on the outside edge of the page. This is how books are traditionally printed, but is contrary to Tufte’s book design which sets the sidenotes on the right side of the page. This option implicitly sets the twoside option.

The justified option sets all the text fully justified (flush left and right). The default is to set the text ragged right. The body text of Tufte’s books are set ragged right. This prevents needless hyphenation and makes it easier to read the text in the slightly narrower column.

The bidi option loads the bidi package which is used with XeLaTeX to typeset bi-directional text. Since the bidi package needs to be loaded before the sidenotes and cite commands are defined, it can’t be loaded in the document preamble.

The debug option causes the Tufte-LaTeX classes to output debug information to the log file which is useful in troubleshooting bugs. It will also cause the graphics to be replaced by outlines.

The nofonts option prevents the Tufte-LaTeX classes from automatically loading the Palatino and Helvetica typefaces. You should use this option if you wish to load your own fonts. If you’re using XeLaTeX, this option is implied (i.e., the Palatino and Helvetica fonts aren’t loaded if you use XeLaTeX).

The nols option inhibits the letterspacing code. The Tufte-LaTeX classes try to load the appropriate letterspacing package (either pdfTeX’s letterspace package or the soul package). If you’re using XeLaTeX with fontenc, however, you should configure your own letterspacing.

The notitlepage option causes \maketitle to generate a title block instead of a title page. The book class defaults to a title page and the handout class defaults to the title block. There is an analogous titlepage option that forces \maketitle to generate a full title page instead of the title block.

The notoc option suppresses Tufte-LaTeX’s custom table of contents (toc) design. The current toc design only shows unnumbered chapter titles; it doesn’t show sections or subsections. The notoc option will revert to LaTeX’s toc design.

The nohyper option prevents the hyperref package from being loaded. The default is to load the hyperref package and use the \title and \author contents as metadata for the generated pdf.

Class options and their counterparts in this theme (not in sample-book.tex, so it has no number).
Class optiontufte.hugo
a4paper, b5paperprint.paper = "a4" or "b5" (default "letter")
sfsidenotessfsidenotes = true
twoside, onesideprint.runningHeads = true: a book alternates book and chapter titles; a handout prints its title and the page number at the top right of every page but the first (as oneside)
symmetricnot available: a screen has no spreads
justifiedjustified = true; marginals, sidenote.align…
bidithe site language’s direction
debugdebug = true
nofontsetBook = false (a base parameter)
nolsletterspacing = false
notitlepage, titlepagebook.titlepage (default true) in a book; a handout has no full title page: titleBlock = "latex" gives the notitlepage title block
notocno direct counterpart: the contents keep the theme’s design; book.tocDepth = 1 also lists the sections, the closest to LaTeX’s standard toc (book.toc = false leaves the contents out, like omitting \tableofcontents)
nohypernot needed: links are native in HTML