The epigraph package^{∗}

Peter Wilson Catholic University of America^{†}

          Now at peter.r.wilson@boeing.com

1998/11/29

Abstract

The epigraph package can be used to typeset a relevant quotation or saying as an epigraph, usually just after a sectional heading. Various handles are provided to tweak the apperance.

Contents

1 Introduction 1

2 The epigraph package 2 2.1 The epigraph command . . . . . . . . . . . . . . . . . . . . . . . . 2 2.2 The epigraphs environment . . . . . . . . . . . . . . . . . . . . . 2 2.3 Epigraphs before chapter headings . . . . . . . . . . . . . . . . . . 2 2.4 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 The package code 5 3.1 Epigraphs before a chapter title . . . . . . . . . . . . . . . . . . . . 6

1 Introduction

My soul, seek not the life of immortals; but enjoy to the full the resources that are within your reach

dards and Technology.

Pythian Odes

Pindar ∗This file has version number v1.1, last revised 1998/11/29.

†This work was originally performed as a Guest Researcher at the National Institute of Stan-

Some authors like to add an interesting quotation at either the start or end of a section. The epigraph package provides commands to assist in the typesetting of a single epigraph. Other authors like to add many such quotations and the package provides environments to cater for these as well.

This manual is typeset according to the conventions of the L^{A}TEX docstrip utility which enables the automatic extraction of the L^{A}TEX macro source files [GMS94].

Section 2 describes the usage of the package. Commented source code for the package is in Section 3.

2 The epigraph package

The whole is more than the sum of the parts.

Metaphysica Aristotle

The epigraph package provides commands for typesetting a single epigraph and environments for typesetting a list of epigraphs. Epigraphs can be typeset at either the left, the center or the right of the typeblock.

2.1 The epigraph command

The original inspiration for \epigraph was Doug Schenck’s for the epigraphs in our book [SW94]. That was hard wired for the purpose at hand. The version here provides much more flexibility.

\epigraph The command \epigraph{⟨text⟩}{⟨source⟩} typesets an epigraph using ⟨text⟩ as the main text of the epigraph and ⟨source⟩ being the original author (or book, article, etc.) of the quoted text. By default the epigraph is placed at the right hand side of the textblock, and the ⟨source⟩ is typeset at the bottom right of the ⟨text⟩.

2.2 The epigraphs environment

epigraphs The epigraphs environment typesets a list of epigraphs, and by default places

them at the right hand side of the textblock. \qitem Each epigraph in the list is specified by a \qitem{⟨text⟩}{⟨source⟩} command

(analagous to the \item command in ordinary list environments). By default, the ⟨source⟩ is typeset at the bottom right of the ⟨text⟩.

2.3 Epigraphs before chapter headings

The \epigraph command and the epigraphs environment typeset an epigraph at the point in the text where they are placed. The first thing that a \chapter command does is to start off a new page, so another mechanism is provided for placing an epigraph just before a chapter heading.

\epigraphhead The \epigraphhead[⟨distance⟩]{⟨text⟩} stores ⟨text⟩ for printing at ⟨distance⟩ below the header on a page started by a preceeding \chapter or \chapter* command. ⟨text⟩ can be ordinary text or, more likely, can be either an \epigraph command or an epigraphs environment. By default, the epigraph will be typeset at the righthand margin.

The default value for the optional ⟨distance⟩ argument is set so that an \epigraph consisting of a single line of quotation and a single line denoting the source is aligned with the bottom of the ‘Chapter X’ line produced by the \chapter command. In other cases you will have to experiment with the ⟨distance⟩ value. The value for ⟨distance⟩ can be either a integer or a real number. The units are in terms of the current value for \unitlength. A typical value for ⟨distance⟩ for a single line quotation and source for a \chapter* might be about 70 (points). A positive value of ⟨distance⟩ places the epigraph below the page heading and a negative value will raise it above the page heading.

Here’s some example code:

 \chapter*{Celestial navigation}
 \epigraphhead[70]{\epigraph{Star crossed lovers.}{\textit{The Bard}}}

The \epigraphhead command changes the page style for the page on which it is specified, so there should be no text between the \chapter and the \epigraphhead commands.

The ⟨text⟩ argument is put into a minipage of width \epigraphwidth (see below). If you use something other than \epigraph or epigraphs for the ⟨text⟩ argument, you may have to so some positioning of the text yourself so that it is properly located in the minipage. For example

 \chapter{Short}
 \renewcommand{\epigraphflush}{center}
 \epigraphhead{\centerline{Short quote}}

(The \epigraphflush command is described below).

2.4 General

Example is the school of mankind, and they will learn at no other.

Letters on a Regicide Peace Edmund Burke

The commands described in this section apply to both the \epigraph command and the epigraphs environment. But first of all, note that an epigraph immediately after a heading will cause the first paragraph of the following text to be indented. If you want the initial paragraph to have no indentation, then start it with the \noindent command.

\epigraphwidth The epigraphs are typeset in a box of width \epigraphwidth. The de-

\textflush fault value for this can be changed using the \setlength command. Typically, epigraphs are typset in a measure much less than the width of the textblock. In order to avoid bad line breaks, the ⟨text⟩ is normally typeset raggedright. The \textflush command controls the ⟨text⟩ tyesetting style, and it can be redefined from its default value of flushleft (which produces raggedright). The sensible values are center for centered text or flushright for raggedleft text.

\epigraphflush As noted, the default position of epigraphs is at the right hand side of the textblock. The positioning is controlled by \epigraphflush whose default value is flushright. This can be changed to flushleft for positioning at the left hand side or to center for positioning at the center of the textblock.

\sourceflush The \sourceflush command controls the position of the ⟨source⟩. The default

value is flushright. It can be changed like the other ...flush commands.

For example, to have epigraphs centered with the ⟨source⟩ at the left, add the following to your document (after loading the epigraph package):

 \renewcommand{\epigraphflush}{center}
 \renewcommand{\sourceflush}{flushleft}

\epigraphsize Epigraphs are often typeset in a smaller font than the main text. The \epigraphsize command sets the font size to be used. If you don’t like the default value, change it by redefining the command, for example:

    \renewcommand{\epigraphsize}{\footnotesize}

\epigraphrule By default, a rule is drawn between the ⟨text⟩ and ⟨source⟩, with the rule thickness being given by the value of \epigraphrule. The value can be changed by using the L^{A}TEX \setlength command. A value of 0pt will eliminate the rule. Personally, I dislike the rule in the list environments.

\beforeepigraphskip The two ...skip commands specify the amount of vertical space inserted \afterepigraphskip before and after typeset epigraphs. Again, these can be changed by \setlength.

It is desireable that the sum of their values should be an integer multiple of the

\baselineskip.

Note that you can use normal L^{A}TEX commands in the ⟨text⟩ and ⟨source⟩ arguments. You may wish to use different fonts for the ⟨text⟩ (say roman) and the ⟨source⟩ (say italic).

The epigraph at the start of this section can be specified as:

 \epigraph{Example is the school of mankind,
           and they will learn at no other.}%
  {\textit{Letters on a Regicide Peace}\\ \textsc{Edmund Burke}}

3 The package code

And now for something completely different.

Monty Python

Announce the name and version of the package, which requires L^{A}TEX 2ε.

1 ⟨∗usc⟩

 2 \NeedsTeXFormat{LaTeX2e}
 3 \ProvidesPackage{epigraph}[1998/11/29 v1.1 typesetting epigraphs]
\beforeepigraphskip \afterepigraphskip \epigraphwidth \epigraphrule The several length commands, which can be changed by the user with \setlength.
 4 \newlength{\beforeepigraphskip}
 5 \setlength{\beforeepigraphskip}{.5\baselineskip}
 6 \newlength{\afterepigraphskip}
 7 \setlength{\afterepigraphskip}{.5\baselineskip}
 8 \newlength{\epigraphwidth}
 9 \setlength{\epigraphwidth}{.4\textwidth}
10 \newlength{\epigraphrule}
11 \setlength{\epigraphrule}{.4\p@}

\epigraphsize The size of the font to be used.

12 \newcommand{\epigraphsize}{\small}

\epigraphflush \textflush \sourceflush The three commands to position epigraphs in the textblock and to position the components of the epigraph.

13 \newcommand{\epigraphflush}{flushright}
14 \newcommand{\textflush}{flushleft}
15 \newcommand{\sourceflush}{flushright}

\@epirule The internal command to draw a rule between text and source.

16 \newcommand{\@epirule}{\rule[.5ex]{\epigraphwidth}{\epigraphrule}}

\@epitext The internal command to typeset the ⟨text⟩. Put it into a minipage of the right size and typeset per \textflush.

17 \newcommand{\@epitext}[1]{%
18 \begin{minipage}{\epigraphwidth}\begin{\textflush} #1\\

Draw a rule if it will be visible, otherwise add some extra vertical space.

19  \ifdim\epigraphrule>\z@ \@epirule \else \vspace*{1ex} \fi
20 \end{\textflush}\end{minipage}}

\@episource The internal command for typesetting the ⟨source⟩, which is put into a minipage and typeset according to \sourceflush.

21 \newcommand{\@episource}[1]{%
22 \begin{minipage}{\epigraphwidth}\begin{\sourceflush} #1\end{\sourceflush}
23 \end{minipage}}

\epigraph Having got the preliminaries out of the way, here’s the user command for a single epigraph. This is set in a minipage to prevent breaking across a page. Position it

according to \epigraphflush.
24 \newcommand{\epigraph}[2]{\vspace{\beforeepigraphskip}
25 {\epigraphsize\begin{\epigraphflush}\begin{minipage}{\epigraphwidth}
26  \@epitext{#1}\\ \@episource{#2}
27  \end{minipage}\end{\epigraphflush}
28  \vspace{\afterepigraphskip}}}

\qitem \qitemlabel \qitem is the epigraph list version of \item. Set everything inside a minipage.

29 \newcommand{\qitem}[2]{{\raggedright\item \begin{minipage}{\epigraphwidth}
30 \@epitext{#1}\\ \@episource{#2}
31 \end{minipage}}}

\qitemlabel is needed for a list as well. It is not going to typeset anything.

32 \newcommand{\qitemlabel}[1]{\hfill}

epigraphs Now for the epigraph list. This is defined in terms of a list environment.

33 \newenvironment{epigraphs}{%

Do the vertical space, set the font size, position according to \epigraphflush, and put everyting into a minipage.

34 \vspace{\beforeepigraphskip}\begin{\epigraphflush}
35 \epigraphsize
36 \begin{minipage}{\epigraphwidth}
37 \list{}%

Make the list just fit the minipage (i.e., no indents).

38  {\itemindent\z@ \labelwidth\z@ \labelsep\z@
39  \leftmargin\z@ \rightmargin\z@
40  \let\makelabel\qitemlabel}}%
41 {\endlist\end{minipage}\end{\epigraphflush}
42 \vspace{\afterepigraphskip}}

3.1 Epigraphs before a chapter title

Placing an epigraph before a chapter title uses the scheme outlined by Piet van Oostrum [vO96]. This is to put a zero sized picture into the page header.

\if@epirhs \if@epicenter Two booleans for testing whether an epigraph is to be at the RH margin, centered, or at the LH margin. The default is RH margin.

43 \newif\if@epirhs     \@epirhstrue
44 \newif\if@epicenter  \@epicentertrue

\@epipos This routine sets the \if@epi... booleans according to the value of \epigraphflush.

If \epigraphflush is neither center nor flushleft then it defaults to flushright.

We have to use this to be upward compatible with \epigraphflush being set by

the user with \renewcommand.
45 \newcommand{\@epipos}{

46 \long\def\@ept{flushleft}
47 \ifx\epigraphflush\@ept
48  \@epirhsfalse \@epicenterfalse
49 \else
50  \long\def\@ept{center}
51  \ifx\epigraphflush\@ept
52  \@epirhsfalse \@epicentertrue
53  \else
54  \@epirhstrue  \@epicenterfalse
55  \fi
56 \fi}

\epigraphhead \epigraphhead[⟨distance⟩]{⟨text⟩} puts ⟨text⟩ at ⟨distance⟩ (a number, not a length) below the header at the page position specified by \epigraphflush.

57 \newcommand{\epigraphhead}[2][95]{%

We have to use \def instead of the normal L^{A}TEX definition commands as we will keep on (re)defining things. For reasons that are not fully clear to me L^{A}TEX doesn’t seem to like me using a \savebox for storing the epigraph text, so I’ll use a command instead.

58 \def\@epitemp{\begin{minipage}{\epigraphwidth}#2\end{minipage}}

Define an epigraph page style.

59 \def\ps@epigraph{\let\@mkboth\@gobbletwo

There are three possible definitions for \@oddhead depending on the value of \epigraphflush. We call \@epipos to decide which one to do.

60  \@epipos
61  \if@epirhs
62  \def\@oddhead{\hfil\begin{picture}(0,0)
63  \put(0,-#1){\makebox(0,0)[r]{\@epitemp}}
64  \end{picture}}
65  \else
66  \if@epicenter
67  \def\@oddhead{\hfil\begin{picture}(0,0)
68  \put(0,-#1){\makebox(0,0)[b]{\@epitemp}}
69  \end{picture}\hfil}
70  \else
71  \def\@oddhead{\begin{picture}(0,0)
72  \put(0,-#1){\makebox(0,0)[l]{\@epitemp}}
73  \end{picture}\hfil}
74  \fi
75  \fi
76  \let\@evenhead\@oddhead
77  \def\@oddfoot{\reset@font\hfil\thepage\hfil}
78  \let\@evenfoot\@oddfoot}

Make epigraph be the page style for this page.

79 \thispagestyle{epigraph}}

The end of this package.

80 ⟨/usc⟩

References

[GMS94] Michel Goossens, Frank Mittelbach, and Alexander Samarin. The LaTeX Companion. Addison-Wesley Publishing Company, 1994.

[vO96] Piet van Oostrum Page layout in L^{A}TEX, June 1996. (Available from

        CTAN as file fancyhdr.tex).

[SW94] Douglas Schenck and Peter Wilson. Information Modeling the EX-PRESS Way. Oxford University Press, 1994 (ISBN 0-19-508714-3).

Index

Numbers written in italic refer to the page where the corresponding entry is described, the ones underlined to the code line of the definition, the rest to the code lines where the entry is used.

Symbols

\@epicenterfalse 48, 54
\@epicentertrue . 44, 52

\@epipos . . . . . . . \underline{45}, 60

\@epirhsfalse . . . 48, 52
\@epirhstrue . . . . 43, 54

\@epirule . . . . . . \underline{16}, 19

\@episource . . \underline{21}, 26, 30

\@epitemp 58, 63, 68, 72 \@epitext … \underline{17}, 26, 30 \@ept …. 46, 47, 50, 51

\@evenfoot . . . . . . . 78
\@evenhead . . . . . . . 76

\@oddfoot . . . . . . 77, 78 \@oddhead 62, 67, 71, 76

A

\afterepigraphskip .

. . . . . . \underline{4}, 4, 28, 42

B

\baselineskip . . . . 5, 7
\beforeepigraphskip

. . . . . . \underline{4}, 4, 24, 34

E

environments:

   epigraphs . . . . . 2, \underline{6}

\epigraph . . . . . . . 2, \underline{24}

                          \epigraphflush . . . .

…. 3, \underline{13}, 25, 27, 34, 41, 47, 51

                          \epigraphhead . . . . 2, \underline{57}
                          \epigraphrule \underline{4}, 4, 16, 19
                          epigraphs (environ-

ment) . . . . . 2, \underline{33}

                          \epigraphsize . . . . .

. . . . . 4, \underline{12}, 25, 35

                          \epigraphwidth . . . .

. . 3, \underline{4}, 16, 18, 22, 25, 29, 36, 58

I

                          \if@epicenter . . . \underline{43}, 66
                          \if@epirhs . . . . . \underline{43}, 61

\item . . . . . . . . . . . . 29

                          \itemindent . . . . . . . 38

L \labelsep . . . . . . . . 38

                          \labelwidth . . . . . . . 38
                          \leftmargin . . . . . . . 39

M \makebox …. 63, 68, 72

                                                   \makelabel . . . . . . . 40

N \newif . . . . . . . . . 43, 44

P

                                                   \ProvidesPackage . . . 3
                                                   \ps@epigraph . . . . . . 59

\put . . . . . . . . 63, 68, 72

Q \qitem . . . . . . . . . . 2, \underline{29}

                                                   \qitemlabel . . . . . \underline{29}, 40

R \rule . . . . . . . . . . . . 16

S \small . . . . . . . . . . . 12

                                                   \sourceflush . . 4, \underline{13}, 22

T

                                                   \textflush 3, \underline{13}, 18, 20
                                                   \textwidth . . . . . . . . 9

\thepage . . . . . . . . . 77

                                                   \thispagestyle . . . . 79