# Formatting information ## A beginner's introduction to typesetting with LA TEX ### Chapter 7 — Textual tools ### Peter Flynn #### Silmaril Consultants Textual Therapy Division v. 3.6 (March 2005)
This edition of Formatting Information was prompted by the generous help I have received from TEX users too numerous to mention individually. Shortly after TUGboat published the November 2003 edition, I was reminded by a spate of email of the fragility of documentation for a system like LA TEX which is constantly under development. There have been revisions to packages; issues of new distributions, new tools, and new interfaces; new books and other new documents; corrections to my own errors; suggestions for rewording; and in one or two cases mild abuse for having omitted package X which the author felt to be indispensable to users. ¶ I am grateful as always to the people who sent me corrections and suggestions for improvement. Please keep them coming: only this way can this book reflect what people want to learn. The same limitation still applies, however: no mathematics, as there are already a dozen or more excellent books on the market — as well as other online documents — dealing with mathematical typesetting in TEX and LA TEX in finer and better detail than I am capable of. ¶ The structure remains the same, but I have revised and rephrased a lot of material, especially in the earlier chapters where a new user cannot be expected yet to have acquired any depth of knowledge. Many of the screenshots have been updated, and most of the examples and code fragments have been retested. ¶ As I was finishing this edition, I was asked to review an article for The PracTEX Journal, which grew out of the Practical TEX Conference in 2004. The author specifically took the writers of documentation to task for failing to explain things more clearly, and as I read more, I found myself agreeing, and resolving to clear up some specific problems areas as far as possible. It is very difficult for people who write technical documentation to remember how they struggled to learn what has now become a familiar system. So much of what we do is second nature, and a lot of it actually has nothing to do with the software, but more with the way in which we view and approach information, and the general level of knowledge of computing. If I have obscured something by making unreasonable assumptions about your knowledge, please let me know so that I can correct it. Peter Flynn is author of The HTML Handbook and Understanding SGML and XML Tools, and editor of The XML FAQ. | This document is Copyright © 1999–2005 by Silmaril Consultants under the terms of what is now the GNU Free Documentation License (copyleft). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled The GNU Free Documentation License. You are allowed to distribute, reproduce, and modify it without fee or further requirement for consent subject to the conditions in section D.5. The author has asserted his right to be identified as the author of this document. If you make useful modifications you are asked to inform the author so that the master copy can be updated. See the full text of the License in Appendix D.

CHAPTER
7
| # Textual tools

Every text-handling system needs to support a repertoire of tools for doing things with text. LA TEX implements many dozens, of which a small selection of the most frequently used is given here:

- offset quotations (sometimes called ‘block quotes’);

- footnotes and end-notes;

- marginal notes;

- cross-references, both normal ones and bibliographic citations;

- indexes and glossaries;

- typesetting in multiple columns.

## 7.1 Quotations

Direct speech and short quotes within a sentence ‘like this’ are done with simple quotation marks as described in section 2.6. Sometimes, however, you may want longer quotations set as a separate paragraph. Typically these are indented from the surrounding text. LA TEX has two environments for doing this.

Such quotations are often set in a smaller size of type, although this is not the default, hence the use of the `\small` command in the second example. The inclusion of the bibliographic citation at the end is optional: here it is done with a non-standard command `\citequote` which I invented for this example (there is more about how to do things like this in Chapter 9).

> The quote environment

>   is for up to a line of text each per (short) quotation, with the whole thing indented from the previous paragraph but with no additional indentation on each quote;

>   >     \begin{quote}
>   >     Do, Ronny, Do. \textit{Nancy Reagan}

>   >     Da Do Ron Ron. \textit{The Crystals}
>   >     \end{quote}

>   > Do, Ronny, Do. Nancy Reagan

>   > Da Do Ron Ron. The Crystals

> The quotation environment

>   is for longer passages (a paragraph or more) of a single quotation, where not only is the block of text indented, but each paragraph of it also has its own extra indentation on the first line.

>   >     \begin{quotation}\small
>   >     At the turn of the century William Davy,
>   >     a Devonshire parson, finding errors in
>   >     the first edition of his \titleof{davy},
>   >     asked for a new edition to be printed.
>   >     His publisher refused and Davy purchased
>   >     a press, type, and paper. He harnessed
>   >     his gardener to the press and apprenticed
>   >     his housemaid to the typesetting. After
>   >     twelve years' work, a new edition
>   >     of fourteen sets of twenty-six volumes
>   >     was issued---which surely indicates that,
>   >     when typomania is coupled with religious
>   >     fervour, anything up to a miracle may be
>   >     achieved.\citequote[p.76]{ryder}
>   >     \end{quotation}

>   > > At the turn of the century William Davy, a Devonshire parson, finding errors in the first edition of his A System of Divinity, asked for a new edition to be printed. His publisher refused and Davy purchased a press, type, and paper. He harnessed his gardener to the press and apprenticed his housemaid to the typesetting. After twelve years' work, a new edition of fourteen sets of twenty-six volumes was issued---which surely indicates that, when typomania is coupled with religious fervour, anything up to a miracle may be achieved.

>   > > John Ryder (1976), Printing for Pleasure, p.76

## 7.2 Footnotes and end-notes

The command `\footnote`, followed by the text of the footnote in curly braces, will produce an auto-numbered footnote with a raised small number where you put the command, and the numbered text automatically printed at the foot of the page.1 The number is reset to 1 at the start of each chapter (but you can override that and make them run continuously throughout the document, or even restart at 1 on each page or section).

LA TEX automatically creates room for the footnote, and automatically reformats it if you change your document in such a way that the point of attachment and the footnote would move to the next (or preceding) page.

Because of the way LA TEX reads the whole footnote before doing anything with it, you can't use `\verb` (section 6.6.1) alone in footnotes: either precede it with `\protect` or use [abuse?] the `\url` command instead, which you should be using for Web and email addresses in any case).

Footnotes inside minipages (see section 6.7) produce lettered notes instead of numbered ones, and they get printed at the bottom of the minipage, not the bottom of the physical page (but this too can be changed).

There is a package to hold over your footnotes and make them print at the end of the chapter instead (endnote) or at the end of the whole document, and there is a package to print many short footnotes in a single footnoted paragraph so they take up less space (fnpara). It is also possible to have several separate series of footnotes active simultaneously, which is useful in critical editions or commentaries: a numbered series may be used to refer to an original author's notes; a lettered series can be used for notes by a commentator or authority; and a third series is available for your own notes. It is also possible to format footnotes within footnotes.

If your footnotes are few and far between, you may want to use footnote symbols instead of numbers. You can do this by redefining the output of the footnote counter to be the `\fnsymbol` command:

>     \renewcommand{\thefootnote{\fnsymbol{footnote}}

There are also ways to refer more than once to the same footnote, and to defer the positioning of the footnote if it occurs in a float like a Table or Figure, where it might otherwise need to move to a different page.

1. Like this.

## 7.3 Marginal notes

You can add marginal notes to your text↞ instead of (or as well as) footnotes. You need to make sure that you have a wide-enough margin, of course: use the geometry package (see section 5.1.1) to allocate enough space, otherwise the notes will be too cramped. There are several packages to help with formatting marginal notes, but the simplest way is to define it yourself. Add this new command to your preamble: | Like this.

>     \newcommand{\marginal}[1]{%
>           \leavevmode\marginpar{\tiny\raggedright#1\par}}

Then you can use `\marginal{Some text}`↞ Be careful, however, because marginal notes are aligned with the line where the command starts, so a very long one followed too closely by another will cause LA TEX to try and adjust the position so they don't overlap. | Some text where you need it.

We're jumping ahead a bit here, as we haven't covered how to define your own commands yet. I won't even try to explain it here, although the attentive reader can probably deduce some of it by inspection. See Chapter 9 for more information about making up your own commands.

## 7.4 Cross-references

This is one of the most powerful features of LA TEX. You can label any point in a document with a name you make up, and then refer to it by that name from anywhere else in the document, and LA TEX will always work out the cross-reference number for you, no matter how much you edit the text or move it around.

A similar method is used to cite documents in a bibliography or list of references, and there are packages to sort and format these in the correct manner for different journals.

### 7.4.1 Normal cross-references

You label a place in your document by using the command `\label` followed by a short name you make up, in curly braces:2 we've already seen this done for labelling Figures and Tables.

>     \section{New Research}
>     \label{newstuff}

You can then refer to this point from anywhere in the same document with the command `\ref` followed by the name you used, e.g.

>     In \S~\ref{newstuff} there is a list of recent
>     projects.

> In § 7.4.1 there is a list of recent projects.

(The `\S` command produces a section sign (§) and the `\P` command produces a paragraph sign (¶).)

If the label is in normal text, the reference will provide the current chapter or section number or both (depending on the current document class).3 If the label was inside a Table or Figure, the reference provides the Table number or Figure number prefixed by the chapter number. A label in an enumerated list will provide a reference to the item number. If there is no apparent structure to this part of the document, the reference will be null. Labels must be unique (that is, each value must occur only once as a label within a single document), but you can have as many references to them as you like.

Note the use of the unbreakable space (`~`) between the `\ref` and the word before it. This prints a space but prevents the line ever breaking at that point, should it fall close to the end of a line.

The command `\pageref` followed by any of your label values will provide the page number where the label occurred, regardless of the document structure. This makes it possible to refer to something by page number as well as its `\ref` number, which is useful to readers in very long documents.

Unresolved references are printed as two question marks, and also cause a warning message at the end of the log file. There's never any harm in having `\label`s you don't refer to, but using `\ref` when you don't have a matching `\label` is an error.

2. This section is labelled ‘`normalxref`’, for example.
3. Thus I can refer here to `\ref{normalxref}` and get the value section 7.4.1.

### 7.4.2 Bibliographic references

The mechanism used for references to reading lists and bibliographies is almost identical to that used for normal cross-references. Although it is possible to type the details of each citation manually, there is a companion program to LA TEX called BIBTEX, which manages bibliographic references automatically. This reduces the time needed to maintain and format them, and dramatically improves accuracy. Using BIBTEX means you only ever have to type the bibliographic details of a work once. You can then cite it in any document you write, and it will get formatted automatically to the style you specify.

#### 7.4.2.1 Citing references

BIBTEX works exactly the same way as other bibliographic databases: you keep details of every document you want to refer to in a separate file, using BIBTEX's own format (see example below). Many writers make a habit of adding the details of every book and article they read, so that when they write a document, these entries are always available for reference. You give each entry a short label, just like you do with normal cross-references (see section 7.4.1), and it is this label you use to refer to in your own documents when you cite the work using the `\cite` command:

>     ...as has clearly been shown by Fothergill~\cite{fg}.

By default, this creates a cross-reference number in square brackets [1] which is a common style in the Natural Sciences (see section 7.4.2.5 for details of how to change this). There are dozens of alternative citation formats in extra packages, including the popular author/year format:

>     ...as has clearly been shown
>     by~\citeauthoryear{fg}.

> ...as has clearly been shown by Fothergill (1929).

Note that in this case you don't type the author's name because it is automatically extracted by BIBTEX. There are lots of variants on this technique in many packages, allowing you to phrase your sentences with references in as natural a way as possible, and rely on BIBTEX to insert the right data. (If you examine the source of this document you'll find I use some homebrew commands like `\authorof` and `\titleof` which I use for a similar purpose.)

To print the bibliographic listing (usually called ‘References’ in articles and ‘Bibliography’ in books and reports), add these two lines towards the end of your document, or wherever you want it printed, substituting the name of your own BIBTEX file and the name of your chosen bibliography style:

>     \bibliographystyle{ieeetr}
>     \bibliography{mybib}

- The `\bibliography` command is followed by the filename of your BIBTEX file without the `.bib` extension.

- The `\bibliographystyle` command is followed by the name of any of LA TEX's supported bibliography styles, of which there are many dozens available from CTAN.4

The styles plain and alpha are two common generic styles used for drafts. The example above uses Transactions of the Institute of Electrical and Electronics Engineers (IEEETR).

4. The style shown in the example here provides formatting according to the specifications for Transactions of the IEEE (revised).

#### 7.4.2.2 Running bibtex

When you run the bibtex program, the details of every document you have cited will be extracted from your database, formatted according to the style you specify, and stored in a temporary bibliographic (`.bbl`) file with a label corresponding to the one you used in your citation, ready for LA TEX to use. This is entirely automatic: all you do is cite your references in your LA TEX document using the labels you gave the entries in your BIBTEX file, and run the bibtex program.

After processing your file with LA TEX, run BIBTEX on it by clicking on the BIBTEX toolbar icon (if your editor has one), or use the TeX→BibTeX File menu entry, or type the command `bibtex` followed by the name of your document (without the `.tex` extension). When you run LA TEX again it will use the `.bbl` file which BIBTEX created, and subsequent runs of LA TEX will format the correct citation numbers (or author/year, or whatever format you are using).

>     $ latex mybook
>     $ bibtex mybook
>     $ latex mybook
>     $ latex mybook

Because of this three-stage process, you always get a warning message about an ‘unresolved reference’ the first time you add a new reference to a previously uncited work. This will disappear after subsequent runs of bibtex and LA TEX.

In practice, authors tend to run LA TEX from time to time during writing anyway, so they can preview the document. Just run BIBTEX after adding a new `\cite` command, and subsequent runs of LA TEX will incrementally incorporate all references without you having to worry about it. You only need to follow the full formal sequence (LA TEX, BIBTEX, LA TEX, LA TEX) when you have finished writing and want to ensure that all references have been resolved.

#### 7.4.2.3 BIBTEX format

The format for the BIBTEX file is specified in the BIBTEX documentation (see section 5.1.2 for how to find and print it). You create a file with a name ending in `.bib`, and add your entries, for example:

>     @book{fg,
>        title        = {{An Innkeeper's Diary}},
>        author       = {John Fothergill},
>        edition      = {3rd},
>        publisher    = {Penguin},
>        year         = 1929,
>        address      = {London}
>     }

There is a prescribed set of fields for each of a dozen or so types of document: book, article (in a journal), article (in a collection), chapter (in a book), thesis, report, paper (in a Proceedings), etc. Each entry identifies the document type after the ‘`@`’ sign, followed by the entry label that you make up, and then each field (in any order), using the format:

>     keyword = {value},

Most TEX-sensitive editors have a BIBTEX mode which understands these entries. Emacs automatically uses its `bibtex-mode` whenever you open a filename ending in `.bib`. When editing BIBTEX databases, the rules are simple:

- Omit the comma after the last field in the entry (only — eg after `{London}` in the example).

- Titles may have their case changed in some styles: to prevent this, enclose the title in double curly braces as in the example.

- Values which are purely numeric (e.g. years) may omit the curly braces.

- Fields can occur in any order but the format must otherwise be strictly observed.

- Fields which are not used do not have to be included (so if your editor automatically inserts them as blank or prefixed by `OPT` [optional], you can safely delete them as unused lines).

To help with this, there are several interfaces to creating and maintaining BIBTEX files, such as tkbibtex (see Figure 7.1), or pybliographic.

Figure 7.1: tkBIBTEX, one of several graphical interfaces to BIBTEX databases

#### 7.4.2.4 Changing the layout

To change the title printed over the reference listing, just change the value of `\refname` (articles) or `\bibname` (books and reports) by adding a line like this in your preamble:

>     \renewcommand{\bibname}{Reading List}

The formatting specifications (BIBTEX styles) are based on standard settings for journals and books from dozens of publishers: you just pick the one you want by name. The `texmf/bib/bst` subdirectory of your installation contains the ones installed by default, and you can search on CTAN for others (look for `.bst` files). Many of them are named after university press styles (e.g. harvard, oxford) or the publisher or journal which specified them (e.g. elsevier, kluwer, etc.).

Some of them have an accompanying package (`.sty`) file which you need to include with the normal `\usepackage` command in your preamble. In this case the format may be distributed as `.dtx` and `.ins` files and will need installing in the same way as any other package (see section 5.2). Always read the documentation, because most of the formats are very specific to the journal they were designed for, and may have fairly absolute requirements.

> If you are writing for a specific publisher, you should remember that the rules or formats are laid down by the typographic designer of that journal or publisher: you cannot arbitrarily change the format just because you don't happen to like it: it's not your choice!

It is also possible to write your own BIBTEX (`.bst`) style files, although it uses a language of its own which really needs a computer science background to understand. However, this is rendered unnecessary in most cases: there is an extensive program (actually written in LA TEX) called makebst, which makes `.bst` files by asking you a (long) series of questions about exactly how you want your citations formatted. Just type `latex makebst` in a command window, but give it a dummy run first, because some of the questions are very detailed, so you need to have thought through how you want your citations to appear before you start.

#### 7.4.2.5 Other modes of citation

The method of citing a work by numeric reference is common in the Natural Sciences but is not used in Law or the Humanities. In these fields, citations are usually done with short references (author/short-title/year) in a numbered footnote. Sometimes they are actually called ‘footnotes’ to the exclusion of ordinary footnotes, although they are really citations which happen by convention to be displayed as footnotes: an important distinction rarely appreciated by authors until they come to need a normal footnote.

For these fields, the bibliography at the back of the document is printed unnumbered in alphabetic order of author, or perhaps chronologically if the time-frame is very large. This unnumbered format is why it is conventionally called ‘References’ rather than ‘Bibliography’: a sufficient working citation has already been provided in the footnote, and the list at the back is for reference purposes only; whereas in the Natural Sciences, the citation is just a number, or possibly an author and year only, so the full listing is called a Bibliography.

The jurabib package (originally intended for German law articles but now extended to other fields in the Humanities, and to other languages) has extensive features for doing this style of citation and is strongly recommended.

4. The style shown in the example here provides formatting according to the specifications for Transactions of the IEEE (revised).

## 7.5 Indexes and glossaries

LA TEX has a powerful, automated indexing facility which uses the standard makeindex program. To use indexing, use the package makeidx and include the `\makeindex` command in your preamble:

>     \usepackage{makeidx}
>     \makeindex

When you want to index something, using the command `\index` followed by the entry in curly braces, as you want it to appear in the index, using one of the following formats:

> Plain entry

>   Typing `\index{beer}` will create an entry for ‘beer’ with the current page number.

> Subindex entry

>   For an entry with a subentry use an exclamation mark to separate them: `\index{beer!lite}`. Subsubentries like `\index{beer!lite!American}` work to another level deep.

> Cross-references

>   ‘See’ entries are done with the vertical bar (one of the rare times it does not get interpreted as a math character): `\index{Microbrew|see{beer}}`

> Font changes

>   To change the style of an entry, use the @-sign followed by a font change command:

>   >     \index{beer!Rogue!Chocolate
>   >            Stout@\textit{Chocolate Stout}}

>   This example indexes ‘Chocolate Stout’ and italicises it at the same time. Any of the standard `\text...` font-change commands work here: see the table in section 8.2.3 for details.

>   You can also change the font of the index number on its own, as for first-usage references, by using the vertical bar in a similar way to the ‘see’ entries above, but substituting a font-change command name (without a backslash) such as `textbf` for bold-face text (see the index):

>   >     \index{beer!Rogue!Chocolate Stout|textbf}

> Out of sequence

>   The same method can be used as for font changes, but using the alternate index word instead of the font command name, so `\index{Oregon Brewing Company@Rogue}` will add an entry for ‘Rogue’ in the ‘O’ section of the index, as if it was spelled ‘Oregon Brewing Company’.

When the document has been processed through LA TEX it will have created a `.idx` file, which you run through the makeindex program by typing (for example):

>     makeindex mythesis

Some editors may have a button or menu entry for this. The program will look for the `.idx` file and output a `.ind` file. This gets used by the command `\printindex` which you put at the end of your document, where you want the index printed. The default index format is two columns.

Glossaries are done in a similar manner using the command `\makeglossary` in the preamble and the command `\glossary` in the same way as `\index`. There are some subtle differences in the way glossaries are handled: both the books by Lamport (1994) and by Mittelbach et al (2004) duck the issue, but there is some documentation on `glotex` on CTAN.

## 7.6 Multiple columns

Use the multicol package: the environment is called multicols (note the plural form) and it takes the number of columns as a separate argument in curly braces:

>     \usepackage{multicol}
>     ...
>     \begin{multicols}{3}
>     ...
>     \end{multicols}

LA TEX has built-in support for two-column typesetting via the `twocolumn` option in the standard Document Class Declarations, but it is relatively inflexible in that you cannot change from full-width to double-column and back again on the same page, and the final page does not balance the column heights. However, it does feature special figure* and table* environments which typeset full-width figures and tables across a double-column setting.

The more extensive solution is the multicol package, which will set up to 10 columns, and allows the number of columns to be changed or reset to one in mid-page, so that full-width graphics can still be used. It also balances the height of the final page so that all columns are the same height — if possible: it's not always achievable — and you can control the width of the gutter by setting the `\columnsep` length to a new dimension.

Multi-column work needs some skill in typographic layout, though: the narrowness of the columns makes typesetting less likely to fit smoothly because it's hard to hyphenate and justify well when there is little space to manœuvre in.