Chapter 3. Basic Formatting Tools

The way information is presented visually can influence, to a large extent, the message as it is understood by the reader. Therefore, it is important that you use the best possible tools available to convey the precise meaning of your words. It must, however, be emphasized that visual presentation forms should aid the reader in understanding the text, and should not distract his or her attention. For this reason, visual consistency and uniform conventions for the visual clues are a must, and the way given structural elements are highlighted should be the same throughout a document. This constraint is most easily implemented by defining a specific command or environment for each document element that has to be treated specially and by grouping these commands and environments in a package file or in the document preamble. By using exclusively these commands, you can be sure of a consistent presentation form.

This chapter explains various ways for highlighting parts of a document. The first part looks at how short text fragments or paragraphs can be made to stand out and describes tools to manipulate such elements.

The second part deals with the different kind of “notes”, such as footnotes, marginal notes, and endnotes, and explains how they can be customized to conform to different styles, if necessary.

Typesetting lists is the subject of the third part. First, the various parameters and commands controlling the standard LaTeX lists, enumerate, itemize, and description, are discussed. Then, the extensions provided by the paralist package and the concept of “headed lists” exemplified by the amsthm package are presented. These will probably satisfy the structure and layout requirements of most readers. If not, then the remainder of this part introduces the generic list environment and explains how to build custom layouts by varying the values of the parameters controlling it.

The fourth part explains how to simulate “verbatim” text. In particular, we have a detailed look at the powerful packages fancyvrb and listings.

The final part presents packages that deal with line numbering, handling of columns, such as parallel text in two columns, or solving the problem of producing multiple columns.

We start by discussing how to define commands that take care of the space after them, then show a way to produce professional-looking marks of omission.

For highlighting text you can customize the font shape, weight, or size (see Section 7.3.1 on page 338). Text can also be underlined, or the spacing between letters can be varied. Ways for performing such operations are offered by the four packages relsize, textcase, ulem, and soul.

The remainder of this section then turns to paragraph-related issues, such as producing large initial letters at the start of a paragraph, modifying paragraph justification, altering the vertical spacing between lines of a paragraph, and introducing rectangular holes into it, that can be filled with small pictures, among other things.

The xspace command saves you from having to type ⊔ or {} after most occurrences of a macro name in text. However, if either of these constructs follows xspace, a space is not added by xspace. This means that it is safe to add xspace to the end of an existing macro without making too many changes in your document. Possible candidates for xspace are commands for abbreviations such as “e.g.,” and “i.e.,”.

Notice the use of the @ command to generate the correct kind of space. If used to the right of a punctuation character, it prevents extra space from being added: the dot will not be regarded as an end-of-sentence symbol. Using it on the left forces LaTeX to interpret the dot as an end-of-sentence symbol.

Sometimes xspace may make a wrong decision and add a space when it is not required. In such cases, follow the macro with {}, which will suppress this space.

C’est une chose... bien difficile.

In German, according to the Duden [44], “Auslassungspunkte” have space on the left and right unless they mark missing letters within a word or a punctuation after them is kept:

Du E... du! Scher dich zum ...!

Elsewhere, such as in British and American typography, the dots are sometimes set with full word spaces between them and rather complex rules determine how to handle other punctuation marks at either end.

LaTeX offers the commands dots and extellipsis to produce closely spaced omission marks. Unfortunately, the standard definition (inherited from plain TeX) produces uneven spacing at the left and right—unsuitable to typeset some of the above examples properly. The extra thin space at the right of the ellipsis is correct in certain situations (e.g., when a punctuation character follows). If the ellipsis is followed by space, however, it looks distinctly odd and is best canceled as shown in the example below (though removing the space in the second instance brings the exclamation mark a bit too close).

This problem is addressed in the package ellipsis written by Peter Heslin, which redefines the dots command to look at the following character to decide whether to add a final separation. An extra space is added if the following character is listed in the command ellipsispunctuation, which defaults to “,.:;!?”. When using some of the language support packages that make certain characters active, this list may have to be redeclared afterwards to enable the package to still recognize the characters.

The spacing between the periods and the one possibly added after the ellipsis can be controlled through the command ellipsisgap. To allow for automatic adjustments depending on the font size use a font-dependent unit like em or a fraction of a fontdimen (see page 428).

For the special case when you need an ellipsis in the middle of a word (or for other reasons want a small space at either side), the package offers the command midwordellipsis. If the package is loaded with the option mla (Modern Language Association style), the ellipsis is automatically bracketed without any extra space after the final period.

If one follows The Chicago Manual of Style [38], then an ellipsis is set with full word spaces between the dots. For this, one can deploy the lips package¹ by Matt Swift. It implements the command lips, which follows the recommendations in this reference book. For example, an ellipsis denoting an omission at the end of a sentence should, according to [38, §10.48–63], consist of four dots with the first dot being the sentence period.² The lips command implements this by interpreting “lips.” like “.lips”, as can be seen in the next example.

¹ lips is actually part of a larger suite of packages. If used on a stand-alone basis, you also have to load the package moredefs by the same author.

² Not that the authors of this book can see any logic in this.

The lips command looks for punctuation characters following it and ensures that in case of ,:;?!)']/ the ellipsis and the punctuation are not separated by a line break. In other cases (e.g., an opening parenthesis), a line break would be possible. The above list is stored in LPNobreakList and can be adjusted if necessary. To force an unbreakable space following lips, follow the command with a tie (~).

When applying the mla option the ellipsis generated will be automatically bracketed and a period after the lips command will not be moved to the front. If necessary, olips will produce the original unbracketed version.

This command must be used immediately before a hyphen or dash (-, --, or ---). The following example shows how to prohibit a line break after the hyphen but allow normal hyphenation in the following word (it suffices to add a zero-width space after the hyphen). For frequent use, it’s advisable to make abbreviations, such as p. As a result “dimension” is broken across the line, while a break after “p-” is prevented (resulting in a overfull box in the example) and “3–9” is moved to the next line.

However, in many situations it is desirable to change the font size relative to the current size. This can be achieved with the relsize package, originally developed by Bernie Cosell and later updated and extended for LaTeX2ε by Donald Arseneau and Matt Swift.

The package provides the declarative command elsize, which takes a number as its argument denoting the number of steps by which to change the size. For example, if the current size is Large then elsize{-2} would change to ormalsize. If the requested number of steps is not available then the smallest (i.e., iny) or largest (i.e., Huge) size command is selected. This means that undoing a relative size change by negating the argument of elsize is not guaranteed to bring you back to the original size—it is better to delimit such changes by a brace group and let LaTeX undo the modification.

The package further defines smaller and larger, which are simply abbreviations for elsize with the arguments -1 and 1, respectively. Convenient variants are extsmaller and extlarger, whose argument is the text to reduce or enlarge in size. These four commands take as an optional argument the number of steps to change if something different from 1 (the default) is needed.

In fact, the above description for elsize is not absolutely accurate: it tries to increase or decrease the size by 20% for each step and selects the LaTeX font size command that is closest to the resulting target size. It then compares the selected size and target size. If they differ by more than the current value of RSpercentTolerance (interpreted as a percentage), the package calls fontsize with the target size as one of the arguments. If this happens it is up to LaTeX’s font selection scheme to find a font matching this request as closely as possible. By default, RSpercentTolerance is an empty macro, which is interpreted as 30 (percent) when the current font shape group is composed of only discrete sizes (see Section 7.10.3), and as 5 when the font shape definition covers ranges of sizes.

Using a fixed factor of 1.2 for every step may be too limiting in certain cases. For this reason the package additionally offers the more general declarative command elscale{factor} and its variant extscale{factor}{text}, to select the size based on the given factor, such as 1.3 (enlarge by 30%).

There are also two commands, mathsmaller and mathlarger, for use in math mode. LaTeX recognizes only four different math sizes, of which two (displaystyle and extstyle) are nearly identical for most symbols, so the application domain of these commands is somewhat limited. With exscale additionally loaded the situation is slightly improved: the mathlarger command, when used in displaystyle, will then internally switch to a larger text font size and afterwards select the displaystyle corresponding to that size.

These commands will attempt to correctly attach superscripts and subscripts to large operators. For example,

Be aware that the use of these commands inside formulas will hide the true nature of the math atoms inside the argument, so that the spacing in the formula, without further help, might be wrong. As shown in following example, you may have to explicitly use mathrel, mathbin, or mathop to get the correct spacing.

Due to these oddities, the mathlarger and mathsmaller commands should not be trusted blindly, and they will not be useful in every instance.

will result in “ON 2ND AUGUST 2004”. Sometimes this will change more characters than desirable. For example, if the text contains a math formula, then uppercasing this formula is normally a bad idea because it changes its meaning. Similarly, arguments to the commands label, ef, and cite represent semantic information, which, if modified, will result in incorrect or missing references, because LaTeX will look for the wrong labels.

The package textcase by David Carlisle overcomes these defects by providing two alternative commands, MakeTextUppercase and MakeTextLowercase, which recognize math formulas and cross-referencing commands and leave them alone.

Sometimes portions of text should be left unchanged for one reason or another. With NoCaseChange the package provides a generic way to mark such parts. For instance:

If necessary, this method can be used to hide syntactic information, such as

thereby preventing tabular and ll from incorrectly being uppercased.

All this works only as long as the material is on the top level. Anything that is inside a group of braces (other than the argument braces to label, ef, cite, or NoCaseChange) will be uppercased or lowercased regardless of its nature.

In the above case you could avoid this pitfall by taking the formula out of the argument to extbf and moving emph inside the argument to NoCaseChange. In other situations this kind of correction might be impossible. In such a case the (somewhat cumbersome) solution is to hide the problem part inside a private macro and protect it from expansion during the case change; this method works for the standard LaTeX commands as well, as shown in the next example.

Some classes and packages employ MakeUppercase internally—for example, in running headings. If you wish to use MakeTextUppercase instead, you should load the textcase package with the option overload. This option will replace the standard LaTeX commands with the variants defined by the package.

Alternatively, underlining can be explicitly requested using the uline command. In addition, a number of variants are available that are common in editorial markup. These are shown in the next example.

The redefinition of emph can be turned off and on by using ormalem and ULforem. Alternatively, the package can be loaded with the option normalem to suppress this redefinition. Another package option is UWforbf, which replaces extbf and fseries by uwave whenever possible.

The position of the line produced by uline can be set explicitly by specifying a value for the length ULdepth. The default value is font-dependent, denoted by the otherwise senile value maxdimen. Similarly, the thickness of the line can be controlled via ULthickness, which, for some historical reason, needs to be redefined using enewcommand.

TeX is ill equipped when it comes to supporting letterspacing. In theory, the best solution is to use specially designed fonts rather than trying to solve the problem with a macro package. But as this requires the availability of such fonts, it is not an option for most users. Thus, in practice, the use of a macro-based solution is usually easier to work with, even though it means dealing with a number of restrictions. Some information about the font approach can be found in the documentation for the fontinst package [74, 75].

The soul package written by Melchior Franz provides facilities for letterspacing and underlining, but maintains TeX’s ability to automatically hyphenate words, a feature not available in ulem. The package works by parsing the text to be letterspaced or underlined, token by token, which results in a number of peculiarities and restrictions. Thus, users who only wish to underline a few words and do not need automatic hyphenation are probably better off with ulem, which is far less picky about its input.

The use of the five main user commands of soul are shown in the next example. In cases where TeX’s hyphenation algorithm fails to find the appropriate hyphenation points, you can guide it as usual with the - command. If the color package is loaded, hl will work like a text marker, coloring the background using yellow as the default color; otherwise, it will behave like ul and underline its argument.

Normally, the soul package interprets one token after another in the argument of so, st, and so on. However, in case of characters that are represented by more than one token (e.g., accented characters) this might fail with some low-level TeX error messages. Fortunately, the package already knows about all common accent commands, so these are handled correctly. For others, such as those provided by the textcomp package, you can announce them to soul with the help of a soulaccent declaration. The alternative is to surround the tokens by braces.

The soul package already knows that quotation characters, en dash, and em dash consist of several tokens and handles them correctly. In case of other syntactical ligatures, such as the Spanish exclamation mark, you have to help it along with a brace group.

The soul package also knows about math formulas as long as they are surrounded by $ signs (the form (...) is not supported) and it knows about all standard font-changing commands, such as extbf. If you have defined your own font-switching command or use a package that provides additional font commands, you have to register them with soul using soulregister. This declaration expects the font command to be registered as its first argument and the number of arguments (i.e., 0 or 1) for that command to appear as its second argument. Within the soul commands none of the font commands inserts any (necessary) italic correction. If needed, one has to provide it manually using /.

If you look carefully, you will see that the font commands suppress letterspacing directly preceding and following them, such as between “action” and the colon. This can be corrected by adding >, which forces a space.

Text inside a brace group is regarded as a single object during parsing and is therefore not spaced out. This is handy if certain ligatures are to be kept intact inside spaced-out text. However, this method works only if the text inside the brace group contains no hyphenation points. If it does, you will receive the package error message “Reconstruction failed”. To hide such hyphenation points you need to put the text inside an mbox, as shown in the second text line of the next example (TeX would hyphenate this as “Es-cher”—that is, between the “sch” that we try to keep together). You can also use soulomit to achieve this effect, but then your text will work only when the soul package is loaded.

One of the most important restrictions of the above commands is that they cannot be nested; any attempt to nest soul commands will result in low-level TeX errors. If you really need nesting you will have to place the inner material in a box, which means you lose the possibility to break the material at a line ending.

A few other commands are special within the argument of so and friends. Spacing out at certain points can be canceled using < or forced with > as we saw above. As usual with LaTeX a ~ will produce an unbreakable space. The \ command is supported, though only in its basic form—no star, no optional argument. You can also use linebreak to break a line at a certain point, but again the optional argument is not supported. Other LaTeX commands are likely to break the package—some experimentation will tell you what is safe and what produces havoc. The next example shows applications of these odds and ends.

The sodef declaration allows you to define your own letterspacing commands. It can also be used to overwrite the defaults for so.

The letterspacing algorithm works by putting a certain inter-letter space between characters of a word, a certain word space between words, and a certain outer space at the beginning and end of the letterspaced text section. The latter space is added only if it is appropriate at that point. The default values for these spaces are adjusted for typesetting texts in Fraktur fonts but with the help of the sodef declaration it is easy to adjust them for your own needs. The font argument allows you to specify font attributes; in most cases it will be empty. Rather than using explicit dimensions in the other arguments it is advisable to resort to em values, thereby making your definition depend on the current font and its size.

While so or any new command defined via sodef simply retrieves and executes its stored definition, the caps command works somewhat differently. It examines the current font and tries to find it (or a close match) in an internal database. It then uses the letterspacing values stored there. You can extend this database using the capsdef declaration by providing values for individual fonts or groups of fonts. In this way you can fine-tune the letterspacing—for example, for text in headings. It is even possible to keep several such databases and change them on the fly within a document.

Apart from the first argument, which is totally different, the other arguments to capsdef are identical to those of sodef. The first argument, match spec, defines the font (or fonts) to which the current declaration applies.

Its syntax is encoding, family, series, shape, and size separated by slashes using the naming conventions of NFSS. Empty values match anything, so //// matches any font, /ptm///10 matches all Times fonts in 10 points, and OT1/cmr/m/n/ matches Computer Modern (cmr) medium series (m) normal shape (n) encoded in OT1 in any size. It is also possible to specify size ranges. For example, 5-14 means 5pt ≤ size < 14pt and 14- matches all sizes equal or greater 14pt. Refer to the tables in Chapter 7 for details on the NFSS font naming conventions.

As with sodef, in most declarations the font argument will be empty. On some occasions it may make sense to use scshape in this place, such as to change the font shape to small caps before applying letterspacing.

Because caps uses the first matching entry in its database, the order of capsdef declarations is important. Later declarations are examined first so that it is possible to overwrite or extend existing declarations.

The previous example also contained an interesting combination of caps and MakeUppercase: the command allcaps changes its argument to uppercase and then uses caps to letterspace the result.

Customized letterspacing for different occasions

With capsreset the database is restored to its initial state containing only a generic default. You can then add new entries using capsdef. The current state of the caps database can be stored away under a name by using capssave. You can later retrieve this state by recalling it with capsselect. If you use the capsdefault option when loading the package, then all uses of caps that have no matching declaration are flagged by underlining the text.

Customizing underlining

The position and the height of the line produced by the ul command can be customized using either setul or setuldepth. The command setul takes two dimensions as arguments: the position of the line in relation to the baseline and the height of the line. Alternatively, setuldepth can be used to specify that the line should be positioned below the text provided as an argument. Finally, esetul will restore the default package settings.

Both ul and st use a black rule by default. If you additionally load the color package, you can use colored rules instead and, if desired, modify the highlighting color as demonstrated below:

The base command provided by the package is url, which is offered in two syntax variants: the text argument either can be surrounded by braces (in which case the text must not contain unbalanced braces) or, like verb, can be delimited by using an arbitrary character on both sides that is not used inside text. (The syntax box above uses ! and = but these are really only examples.) In that second form one can have unbalanced braces in the argument.

The path command is the same except that it always uses typewriter fonts ( tfamily), while url can be customized as we will see below. The argument to both commands is typeset pretty much verbatim. For example, url{~} produces a tilde. Spaces are ignored by default, as can be seen in the following example.

Line breaks can happen at certain symbols (by default, not between letters or hyphens) and in no case can the commands add a hyphen at the break point. Whenever the text contains either of the symbols % or #, or ends with , it cannot be used in the argument to another command without producing errors (just like the verb command). Another case that does not work properly inside the argument of another command is the use of two ^ characters in succession. However, the situation is worse in that case because one might not even get an error but simply incorrect output¹ as the next example shows.

¹ It depends on the letter that is following. An uppercase F instead of the lowercase f would produce an error.

Even if the text does not contain any critical symbols, it is always forbidden to use such a command inside a moving argument—for instance, the argument of a section. If used there, you will get the error message

followed by many strange errors. Even the use of protect will not help in that case. So what can be done if one needs to cite a path name or a URL in such a place? If you are prepared to be careful and only use “safe” characters inside text, then you can enable the commands for use in moving arguments by specifying the option allowmove when loading the package. But this does not help if you actually need a character like “#”. In that case the solution is to record the information first using urldef and then reuse it later.

The declaration urldef defines a new command cmd to contain the url-cmd (which might be url, path, or a newly defined command—see below) and the text in a way such that they can be used in any place, including a moving argument. The url-cmd is not executed at this point, which means that style changes can still affect the typesetting (see Example 3-1-33 on the facing page). Technically, what happens is that the catcodes of characters in text are frozen during the declaration, so that they cannot be misinterpreted in places like arguments.

We have already mentioned style changes. For this task the url package offers the urlstyle command, which takes one mandatory argument: a named style. Predefined styles are rm, sf, tt, and same. The first three select the font family of that name, while the same style uses the current font and changes only the line breaking.

The url command uses whatever style is currently in force (the default is tt, i.e., typewriter), while path internally always switches to the tt style. In the following example we typeset a URL saved in lproject several times using different styles. The particular example may look slightly horrifying, but imagine how it would have looked if the URL had not been allowed to split at all in this narrow measure.

If you studied the previous example closely you will have noticed that the option hyphens was used. This option allows breaking at explicit hyphens, something normally disabled for url-like commands. Without this option breaks would have been allowed only at the periods, after the colon, or after “//”.

Spaces in the argument

As mentioned earlier spaces inside text are ignored by default. If this is not desired one can use the option obeyspaces. However, this option may introduce spurious spaces if the url command is used inside the argument of another command and text contains any “” character. In that case urldef solves the problem. Line breaks at spaces are not allowed unless you also use the option spaces.

The package automatically detects which font encoding is currently in use. In case of T1 encoded fonts it will make use of the additional glyphs available in this encoding, which improves the overall result.

Appending material at left or right

The package offers two hooks, UrlLeft and UrlRight, that by default do nothing but can be redefined to typeset material at the left or right of text. The material is typeset in the same fashion as the text. For example, spaces are ignored unless one uses ⊔ or specifies obeyspaces as an option. If the commands are redefined at the top level, they act on every url-like command. See Example 3-1-34 on the next page for a possibility to restrict their scope.

Defining URL-like commands

It is sometimes helpful to define your own commands that work similarly to url or path but use their own fonts, and so on. The command DeclareUrlCommand can be used to define a new url-like command or to modify an existing one. It takes two arguments: the command to define or change and the style-information (e.g., urlstyle).

In the next example, we define email to typeset e-mail addresses in rm style, prepending the string “e-mail:” via UrlLeft. The example clearly shows that the scope for this redefinition is limited to the email command. If you look closely, you can see that a space inside UrlLeft (as in the top-level definition) has no effect, while ⊔ produces the desired result.

The url package offers a number of other hooks that influence line breaking, among them UrlBreaks, UrlBigBreaks, and UrlNoBreaks. These hooks can be redefined in the style-information argument of DeclareUrlCommand to set up new or special conventions. For details consult the package documentation, which can be found at the end of the file url.sty.

The main command EURO converts an amount in from-currency into to-currency or, if this optional argument is missing, into euros. The arguments from-currency and to-currency are denoted in ISO currency codes, as listed in Table 3.1 on the facing page. When inputting the amount a dot must separate the integer value from any fractional part, even if the formatted number uses a different convention.

With the default settings the amount is displayed in the from-currency with the converted value in the to-currency shown in parentheses.

The package options

The package offers a number of options to influence the general style of the output (unless overwritten by the more detailed formatting declarations discussed below). With eco the ISO codes precede the value and no customized symbols are used; with dots a period is inserted between every three-digit group (the default is to use a small space).

By default, integer amounts are printed as such, without adding a decimal separator and a (zero) fractional part. If the table option is specified this behavior is globally changed and either a—(option emdash, also the default), a – (option endash), or the right number of zeros (option zeros) is used.

The more detailed output customizations, which we discuss below, can be placed anywhere in the document. It is, however, advisable to keep them together in the preamble, or even to put them into the file euro.cfg, which is consulted upon loading the package.

The monetary symbols typeset can be adjusted with a EUROSYM declaration; as defaults the package uses the ISO codes for most currencies. The example below changes the presentation for lira and euro using the currency symbols from the textcomp package. It also uses dots to help with huge lira amounts.

The package is well prepared for new countries to join the euro-zone. In fact, it is well prepared to deal with conversions from and to any currency as long as the conversion rate to the euro is known. To add a new currency use the EUROADD declaration, which takes three arguments: the ISO currency code, the symbol or text to display for the currency, and the conversion rate to the euro. The next example makes the British pound available. Note the abbreviation GBP, which makes the input a bit easier.

The conversion rates for the national currencies of the euro-zone countries are fixed (and predefined by the package). With other currencies the rates may change hourly, so you have to be prepared for frequent updates.

The package allows you to tailor the presentation via EUROFORMAT declarations, either to provide new defaults or to adjust the typesetting of individual currencies. The first argument specifies which part of the formatting should be adjusted, and the second argument describes the formatting.

The main format specifies how the source and target currencies are to be arranged using the reserved keywords in and out to refer to the source and target currencies, respectively. In the example below the first line implements a format close to the default, the second line displays the result of the conversion, and the third line does not show the conversion at all (although it happens behind the scenes). The latter is useful if you want to make use of the currency formatting features of the package without being interested in any conversion.

The in and out formats specify how the source and target currencies should be formatted using the reserved keywords val (monetary amount), iso (currency code), and sym (currency symbol if defined; ISO code otherwise).

Perhaps more interesting are the possibilities to influence the formatting of monetary amounts, for which the package offers five declarations to be used in the second argument to EUROFORMAT. The ound declaration specifies where to round the monetary amount: positive values round to the integer digits and negative values to the fractional digits. For example, ound{-3} means show and round to three fractional digits. The form declaration takes three arguments: the integer group separator (default ,), the decimal separator (default a comma), and the fractional group separator (default ,).

The first argument can be either all to define the default number formatting or an ISO currency code to modify the formatting for a single currency.

The minus declaration formats negative values by executing its first argument before the number and its second argument after it (default minus{$-$}{}). The number itself is typeset unsigned, so that a minus sign has to be supplied by the declaration. The plus declaration is the analogue for dealing with positive numbers (default plus{}{}).

The zero declaration takes three arguments to describe what to do if everything is zero, the integer part is zero, or the fractional part is zero. In the first and third arguments, the decimal separator has to be entered as well, so it should correspond to the default or the value given in the form command.

The package lettrine written by Daniel Flipo lets you create such initials by providing the command lettrine. In its simplest form it takes two arguments: the letter to become an initial and the follow-up text to be typeset in a special font, by default in scshape.

The font used for the initial is, by default, a larger size of the current text font. Alternatively, you can specify a special font family by redefining the command LettrineFontHook using standard NFSS commands. Similarly, the font used for the text in the second argument can be modified by changing LettrineTextFont.

Because the lettrine command calculates the initial size to fit a certain number of lines, you need scalable fonts to obtain the best results. As the examples in this book are typeset in Adobe Times and Helvetica by default, we have no problems here. Later examples use Palatino, which is also a scalable Type 1 font. But if you use a bitmapped font, such as Computer Modern, you might have to use special .fd files (see Chapter 7, pages 419ff) to achieve acceptable results.

Many books on typography give recommendations about how to best set large initials with respect to surrounding text. For highest quality it is often necessary to manually adjust the placement depending on the shape of the initial. For example, it is often suggested that letters with a projecting left stem should overhang into the margin. The lettrine command caters to this need by supporting an optional argument in which you can specify adjustments in the form of a comma-separated list of key/value pairs.

The size of the initial is calculated by default to have a height of two text lines (stored in DefaultLines); with the keyword lines you can change this value to a different number of lines. There is an exception: if you specify lines=1 the initial is still made two lines high, but instead of being dropped is placed onto the baseline of the first text line.

If you want a dropped initial that also extends above the first line of text, then use the keyword loversize. A value of .2 would enlarge the initial by 20%. The default value for this keyword is stored in DefaultLoversize. This keyword is also useful in conjunction with lraise (default 0 in DefaultLraise). In case of an initial with a large descender such as a “Q” you may have to raise the initial to avoid it overprinting following lines. In that case loversize can be used to reduce the height so as to align the initial properly.

With the keyword lhang you specify how much the initial extends into the margin. The value is specified as a fraction—that is, between 0 and 1. Its document default is stored in DefaultLhang.

The distance between the initial and the following text in the first line is controlled by the command DefaultFindent (default 0pt) and can be overwritten using the keyword findent. The indentation of following lines is by default 0.5em (stored in DefaultNindent) but can be changed through the keyword nindent. If you want to specify a sloped indentation you can use the keyword slope, which applies from the third line onward. Again the default value can be changed via the command DefaultSlope, though it seems questionable that you would ever want anything different than 0pt since a slope is normally only used for letters like “A” or “V”.

The example above clearly demonstrates that the size calculation for the initial does not take accents into account, which is normally the desired behavior. It is nevertheless possible to manually adjust the size using loversize.

To attach material to the left of the initial, such as some opening quote, you can use the keyword ante. It is the only keyword for which no command exists to set the default.

By modifying the default settings you can easily adapt the package to typeset initials the way you like. This can be done either in the preamble or in a file with the name lettrine.cfg, which is loaded if found.

The downside of the global optimizing approach of TeX, which you will encounter sooner or later, is that making small changes, like correcting a typo near the end of a paragraph, can have drastic and surprising effects, as it might affect the line breaking of the whole paragraph. It is possible, and not even unlikely, that, for example, the removal of a word might actually result in making a paragraph one line longer. This behavior can be very annoying if you are near the end of finishing an important project (like the second edition of this book) and a correction wreaks havoc on your already manually adjusted page breaks. In such a situation it is best to place linebreak or pagebreak commands into strategic places to force TeX to choose a solution that it would normally consider inferior. To be able to later get rid of such manual corrections you can easily define your own commands, such as

rather than using the standard LaTeX commands directly. This helps you to distinguish the layout adjustments for a particular version from other usages of the original commands—a method successfully used in the preparation of this book.

Careful with TeX’s idea about infinitely bad

The interword spacing in a justified paragraph (the white space between individual words) is controlled by several TeX parameters—the most important ones are olerance and emergencystretch. By setting them suitably for your document you can prevent most or all of the “Overfull box” messages without any manual line breaks. The olerance command is a means for setting how much the interword space in a paragraph is allowed to diverge from its optimum value.¹ This command is a TeX (not LaTeX) counter and therefore it has an uncommon assignment syntax—for example, olerance=500. Lower values make TeX try harder to stay near the optimum; higher values allow for loose typesetting. The default value is often 200. When TeX is unable to stay in the given tolerance you will find overfull boxes in your output (i.e., lines sticking out into the margin like this). Enlarging the value of olerance means that TeX will also consider poorer but still acceptable line breaks, instead of turning the problem over to you for manual intervention. Sensible values are between 50 and 9999. Do not use 10000 or higher, as it allows TeX to produce arbitrarily bad lines (like this one). If you really need fully automated line breaking, it is better to set the length parameter emergencystretch to a positive value. If TeX cannot break a paragraph without producing overfull boxes (due to the setting of olerance) and emergencystretch is positive, it will add this length as stretchable space to every line, thereby accepting line-breaking solutions that have been rejected before. You may get some underfull box messages because all the lines are now set in a loose measure, but this result will still look better than a single horrible line in the middle of an otherwise perfectly typeset paragraph.

¹ The optimum is font defined; see Section 7.10.3 on page 428.

LaTeX has two predefined commands influencing the above parameters: fussy, which is the default, and sloppy, which allows for relatively bad lines. The sloppy command is automatically applied by LaTeX in some situations (e.g., when typesetting marginpar arguments or p columns in a tabular environment) where perfect line breaking is seldom possible due to the narrow measure.

The main type of unjustified text is the one in which lines are set flush left but are unjustified at the right. For this arrangement LaTeX offers the environment flushleft. It typesets all text in its scope “flush left” by adding very stretchable white space at the right of each line; that is, it sets the internal parameter ightskip to 0pt plus 1fil. This setting often produces very ragged-looking paragraphs as it makes all lines equally good independent of the amount of text they contain. In addition, hyphenation is essentially disabled because a hyphen adds to the “badness” of a line and, as there is nothing to counteract it, TeX’s paragraph-breaking algorithm will normally choose line breaks that avoid them.

In summary, LaTeX’s flushleft environment is not particularly well suited to continuous unjustified text, which should vary at the right-hand boundary only to a certain extent and where appropriate should use hyphenation (see the next section for alternatives). Nevertheless, it can be useful to place individual objects, like a graphic, flush left to the margin, especially since this environment adds space above and below itself in the same way as list environments do.

Another important restriction is the fact that the settings chosen by this environment have no universal effect, because some environments (e.g., minipage or tabular) and commands (e.g., parbox, footnote, and caption) restore the alignment of paragraphs to full justification. That is, they set the ightskip length parameter to 0pt and thus cancel the stretchable space at the right line endings. A way to automatically deal with this problem is provided by the package ragged2e (see next section).

Other ways of typesetting paragraphs are flush right and centered, with the flushright and center environments, respectively. In these cases the line breaks are usually indicated with the \ command, whereas for ragged-right text (the flushleft environment discussed above) you can let LaTeX do the line breaking itself (if you are happy with the resulting quality).

The three environments discussed in this section work by changing declarations that control how TeX typesets paragraphs. These declarations are also available as LaTeX commands, as shown in the following table of correspondence:

The commands neither start a new paragraph nor add vertical space, unlike the corresponding environments. Hence, the commands can be used inside other environments and inside a parbox, in particular, to control the alignment in p columns of an array or tabular environment. Note, however, that if they are used in the last column of a tabular or array environment, the \ is no longer available to denote the end of a row. Instead, the command abularnewline can be used for this purpose (see also Section 5.2.1).

By default, the package does not modify the standard LaTeX commands and environments discussed in the previous section, but instead defines its own using the same names except that some letters are uppercased.¹ The new environments and commands are given in the following correspondence table:

¹ This is actually against standard naming conventions. In most packages mixed-case commands indicate interface commands to be used by designers in class files or in the preamble, but not commands to be used inside documents.

They differ from their counterparts of the previous section not only in the fact that they try to produce less ragged output, but also in their attempt to provide additional flexibility by easily letting you change most of their typesetting aspects.

Overloading the original commands

As typing the mixed-case commands and environments is somewhat tedious, you can overload the original commands and environments, such as aggedright, with the new definitions by supplying the newcommands option when loading the package.

The package offers a large number of parameters to define the exact behavior of the new commands and environments (see Table 3.2 on the next page). For RaggedRight or FlushLeft the white space added at the right of each line can be specified as RaggedRightRightskip, the one at the left can be specified as RaggedRightLeftskip, the paragraph indentation to use is available as RaggedRightParindent, and even the space added to fill the last line is available as RaggedRightParfillskip. Similarly, the settings for Centering and RaggedLeft can be altered; just replace RaggedRight in the parameter names with either Centering or RaggedLeft.

Unjustified setting as the default

To set a whole document unjustified, specify document as an option to the ragged2e package. For the purpose of justifying individual paragraphs the package offers the command justifying and the environment justify. Both can be customized using the length parameters JustifyingParindent and JustifyingParfillskip.

Thus, to produce a document with a moderate amount of raggedness and paragraphs indented by 12pt, you could use a setting like the one in the following example (compare it to Example 3-1-48 on page 104).

Unjustified settings in narrow columns

In places with narrow measures (e.g., marginpars, parboxes, minipage environments, or p-columns of tabular environments), the justified setting usually produces inferior results. With the option raggedrightboxes, paragraphs in such places are automatically typeset using RaggedRight. If necessary, justifying can be used to force a justified paragraph in individual cases.

The default values

The use of em values in the defaults (see Table 3.2) means that special care is needed when loading the package, as the em is turned into a real dimension at this point! The package should therefore be loaded after the body font and size have been established—for example, after font packages have been loaded.

Instead of using the defaults listed in Table 3.2, one can instruct the package to mimic the original LaTeX definitions by loading it with the option originalparameters and then changing the parameter values as desired.

¹ In contrast the obsolete LaTeX 2.09 solution enewcommandaselinestretch{1.5} requires a following font size changing command (e.g., small, Large) to make the new value take effect.

The package setspace (by Geoffrey Tobin and others) provides commands and environments for typesetting with variable spacing (primarily double and one-and-a-half). Three commands—singlespacing, onehalfspacing, and doublespacing—are available for use in the preamble to set the overall spacing for the document. Alternatively, a different spacing value can be defined by placing a setstretch command in the preamble. It takes the desired spacing factor as a mandatory argument. In the absence of any of the above commands, the default setting is single spacing.

To change the spacing inside a document three specific environments—singlespace, onehalfspace, and doublespace—are provided. They set the spacing to single, one-and-a-half, and double spacing, respectively. These environments cannot be nested.

For any other spacing values the generic environment spacing should be used. Its mandatory parameter is the value of aselinestretch for the text enclosed by the environment.

In the above example the coefficient “2.0” produces a larger leading than the “double spacing” (doublespace environment) required for some publications. With the spacing environment the leading is effectively increased twice—once by aselineskip (which LaTeX already sets to about 20% above the font size) and a second time by setting aselinestretch. “Double spacing” means that the vertical distance between baselines is about twice as large as the font size.

Since aselinestretch refers to the ratio between the desired distance and the aselineskip, the values of aselinestretch for different document base font sizes (and at two different optical spacings) can be calculated and are presented in Table 3.3.

If you look at the above example you will notice that the second paragraph is not properly indented. You can fix this defect by requesting an explicit indentation using parindent, if necessary.

Centering a window as in the previous example works only if the remaining text width on either side is still suitably wide (where “suitably” means larger than one inch). Otherwise, the package will simply fill it with white space.

The package also provides two variant environments, figwindow and tabwindow. They can format the explanatory text as a caption, by adding a caption number. You should, however, be careful when mixing such “nonfloating” floats with standard figure or table environments, because the latter might get deferred and this way mess up the numbering of floats.

The next example shows such an embedded figure—a map of Great Britain placed inside a paragraph. Unfortunately, the caption formatting is more or less hard-wired into the package; if you want to change it, you have to modify an internal command named @makewincaption.

We start by discussing the possibilities offered through standard LaTeX’s footnote commands and explain how (far) they can be customized. For two-column documents, a special layout for footnotes is provided by the ftnright package, which moves all footnotes to the bottom of the right column. This is followed by a presentation of the footmisc package, which overcomes most of the limitations of the standard commands and offers a wealth of additional features. The manyfoot package (which can be combined with footmisc) extends the footnote support for disciplines like linguistics by providing several independent footnote commands.

Support for endnotes is provided through the package endnotes, which allows for mixing footnotes and endnotes and can also be used to provide chapter notes, as required by some publishers. The section concludes with a discussion of marginal notes, which are already provided by standard LaTeX.

Peculiarities inside a minipage

Footnotes produced with the footnote command inside a minipage environment use the mpfootnote counter and are typeset at the bottom of the parbox produced by the minipage. However, if you use the footnotemark command in a minipage, it will produce a footnote mark in the same style and sequence as the main text footnotes—that is, stepping the footnote counter and using the hefootnote command for the representation. This behavior allows you to produce a footnote inside your minipage that is typeset in sequence with the main text footnotes at the bottom of the page: you place a footnotemark inside the minipage and the corresponding footnotetext after it.

As the previous example shows, if you need to reference a minipage footnote several times, you cannot use footnotemark because it refers to footnotes typeset at the bottom of the page. You can, however, load the package footmisc and then use mpfootnotemark in place of footnotemark. Just like footnotemark, the mpfootnotemark command first increments its counter and then displays its value. Thus, to refer to the previous value you typically have to decrement it first, as shown in the next example.

LaTeX does not allow you to use a footnote inside another footnote command, as is common in some disciplines. You can, however, use the footnotemark command inside the first footnote and then put the text of the footnote’s footnote as the argument of a footnotetext command. For other special footnote requirements consider using the manyfoot package (described below).

What if you want to reference a given footnote? You can use LaTeX’s normal label and ef mechanism, although you may want to define your own command to typeset the reference in a special way. For instance:

Standard LaTeX does not allow you to construct footnotes inside tabular material. Section 5.8 describes several ways of tackling that problem.

¹ An interesting and complete discussion of this subject appeared in the French TeX Users’ Group magazine Cahiers GUTenberg [10, 133].

LaTeX offers several parameters to customize footnotes. They are shown schematically in Figure 3.1 on the next page and are described below:

footnotesize The font size used inside footnotes (see also Table 7.1 on page 342).

footnotesep The height of a strut placed at the beginning of every footnote. If it is greater than the aselineskip used for footnotesize, then additional vertical space will be inserted above each footnote. See Appendix A.2.3 for more information about struts.

skipfootins A low-level TeX length parameter that defines the space between the main text and the start of the footnotes. You can change its value with the setlength or addtolength command by putting skipfootins into the first argument:

footnoterule A macro to draw the rule separating footnotes from the main text that is executed right after the vertical space of skipfootins. It should take zero vertical space; that is, it should use a negative skip to compensate for any positive space it occupies. The default definition is equivalent to the following:

Note that TeX’s hrule command and not LaTeX’s ule command is used. Because the latter starts a paragraph, it would be difficult to calculate the spaces needed to achieve a net effect of zero height. For this reason producing a fancier “rule” is perhaps best done by using a zero-sized picture environment to position the rule object without actually adding vertical space.

In the report and book classes, footnotes are numbered inside chapters; in article, footnotes are numbered sequentially throughout the document. You can change the latter default by using the @addtoreset command (see Appendix A.1.4). However, do not try to number your footnotes within pages with the help of this mechanism. LaTeX is looking ahead while producing the final pages, so your footnotes would most certainly be numbered incorrectly. To number footnotes on a per-page basis, use the footmisc or perpage package (described below).

The command @makefnmark is normally used to generate the footnote mark. One would expect this command to take one argument (the current footnote number), but in fact it takes none. Instead, it uses the command @thefnmark to indirectly refer to that number. The reason is that depending on the position (inside or outside of a minipage) a different counter needs to be accessed. The definition, which by default produces a superscript mark, looks roughly as follows:

The footnote command executes @makefntext inside a parbox, with a width of columnwidth. The default version looks something like:

This will place the footnote mark right aligned into a box of width 1.8em directly followed by the footnote text. Note that it reuses the @makefnmark macro, so any change to it will, by default, modify the display of the mark in both places. If you want the text set flush left with the number placed into the margin, then you could use the redefinition shown in the next example. Here we do not use @makefnmark to format the mark, but rather access the number via @thefnmark. As a result, the mark is placed onto the baseline instead of being raised. Thus, the marks in the text and at the bottom are formatted differently.

The main idea for the ftnright package is to assemble the footnotes of all columns on a page and place them all together at the bottom of the right column. The layout produced allows for enough space between footnotes and text and, in addition, sets the footnotes in smaller type.¹ Furthermore, the footnote markers are placed at the baseline instead of raising them as superscripts.²

¹ Some journals use the same size for footnotes and text, which sometimes makes it difficult to distinguish footnotes from the main text.

² Of course, this is done only for the mark preceding the footnote text and not the one used within the main text, where a raised number or symbol set in smaller type will help to keep the flow of thoughts uninterrupted.

This package can be used together with most other class files for LaTeX. Of course, the ftnright package will take effect only with a document using a two-column layout specified with the twocolumn option on the documentclass command. In most cases, it is best to use ftnright as the very last package to make sure that its settings are not overwritten by other options.

The interface for footmisc is quite simple: nearly everything is customized by specifying options when the package is loaded, though in some cases further control is possible via parameters.

In the article class, footnotes are numbered sequentially throughout the document; in report and book, footnotes are numbered inside chapters. Sometimes, however, it is more appropriate to number footnotes on a per-page basis. This can be achieved by loading footmisc with the option perpage. The package footnpag (by Joachim Schrod) provides the same feature with a somewhat different implementation as a stand-alone package. A generalized implementation for resetting counters on a per-page basis is provided by the package perpage (see Section 3.2.5 on page 120). Since TeX’s page-building mechanism is asynchronous, it is always necessary to process the document at least twice to get the numbering correct. Fortunately, the package warns you via “Rerun to get cross-references right” if the footnote numbers are incorrect. The package stores information between runs in the .aux file, so after a lot of editing this information is sometimes not even close to reality. In such a case deleting the .aux file helps the package to find the correct numbering faster.¹

¹ In fact, during the preparation of this chapter we managed to confuse footmisc (by changing the extheight in an example) so much that it was unable to find the correct numbering thereafter and kept asking for a rerun forever. Removing the .aux file resolved the problem.

Counter too large errors

For this special occasion our example shows two pages side by side, so you can observe the effects of the perpage option. The example also shows the effect of another option: symbol will use footnote symbols instead of numbers. As only a limited number of such symbols are available, you can use this option only if there are few footnotes in total or if footnote numbers restart on each page. There are six different footnote symbols and, by duplicating some, standard LaTeX supports nine footnotes. By triplicating some of them, footmisc supports up to 16 footnotes (per page or in total). If this number is exceeded you will get a LaTeX error message.

In particular with the perpage option, this behavior can be a nuisance because the error could be spurious, happening only while the package is still trying to determine which footnotes belong on which page. To avoid this problem, you can use the variant option symbol*, which also produces footnote symbols but numbers footnotes for which there are no symbols left with Arabic numerals. In that case you will get a warning at the end of the run that some footnotes were out of range and detailed information is placed in the transcript file.

If the symbol or symbol* option is selected, a default sequence of footnote symbols defined by Leslie Lamport is used. Other authorities suggest different sequences, so footmisc offers three other sequences to chose from using the declaration setfnsymbol (see Table 3.4).

In addition, you can define your own sequence using the DefineFNsymbols declaration in the preamble. It takes two mandatory arguments: the name to access the list later via setfnsymbol and the symbol-list. From this list symbols are taken one after another (with spaces ignored). If a symbol is built from more than one glyph, it has to be surrounded by braces. If the starred form of the declaration is used, LaTeX issues an error message if it runs out of symbols. Without it, you will get Arabic numerals and a warning at the end of the LaTeX run.

Due to an unfortunate design choice, footnote symbols (as well as some other text symbols) were originally added to the math fonts of TeX, rather than to the text fonts, with the result that they did not change when the text font was modified. In LaTeX this flaw was partly corrected by adding these symbols to the text symbol encoding (TS1; see Section 7.5.4). However, for compatibility reasons the footnote symbols are still taken by default from the math fonts, even though this choice is not appropriate if one has changed the text font from Computer Modern to some other typeface. By using the optional type argument with the value text, you can tell footmisc that your list consists of text symbols. Note that all predefined symbol lists consist of math symbols and may need redeclaring if used with fonts other than Computer Modern.

If you have many short footnotes then their default placement at the bottom of the page, stacked on top of each other, is perhaps not completely satisfactory. A typical example would be critical editions, which contain many short footnotes.¹ The layout of the footnotes can be changed using the para option, which formats them into a single paragraph. If this option is chosen then footnotes never split across pages. The code for this option is based on work by Chris Rowley and Dominik Wujastyk (available as the package fnpara), which in turn was inspired by an example in The TeXbook by Donald Knuth.

¹ See, for example, the ledmac package [171] for the kinds of footnotes and endnotes that are common in critical editions. This package is a reimplementation of the EDMAC system [112] for LaTeX and was recently made available by Peter Wilson. See also the bigfoot package by David Kastrup.

Another way to deal with footnotes is given by the option side. In this case footnotes are placed into the margin, if possible on the same line where they are referenced. What happens internally is that special marginpar commands are used to place the footnote text, so everything said in Section 3.2.8 about the marginpar commands is applicable. This option cannot be used together with the para option, described earlier, but can be combined with most others.

The option flushmargin used in the previous example makes the footnote text start at the left margin with the footnote marker protruding into the margin; by default, the footnote text is indented. For obvious reasons this option is incompatible with the para option. A variant form is called marginal. If this option is used then the marker sticks even farther into the margin, as shown in the example below.

Instead of using one of the above options, the position of the footnote marker can be directly controlled using the parameter footnotemargin. If set to a negative value the marker is positioned in the margin. A value of 0pt is equivalent to using the option flushmargin. A positive value means that the footnote text is indented by this amount and the marker is placed flush right in the space produced by the indentation.

By default, the footnote text is justified but this does not always give satisfactory results, especially with the options para and side. In case of the para option nothing can be done, but for other layouts you can switch to ragged-right typesetting by using the option ragged. The next example does not specify flushmargin, so we get an indentation of width footnotemargin—compare this to Example 3-2-10 on the preceding page.

The two options norule and splitrule (courtesy of Donald Arseneau) modify the rule normally placed between text and footnotes. If norule is specified, then the separation rule will be suppressed. As compensation the value of skipfootins is slightly enlarged. If a footnote does not fit onto the current page it will be split and continued on the next page, unless the para option is used (as it does not support split footnotes). By default, the rule separating normal and split footnotes from preceding text is the same. If you specify the option splitrule, however, it becomes customizable: the rule above split footnotes will run across the whole column while the one above normal footnotes will retain the default definition given by footnoterule. More precisely, this option will introduce the commands mpfootnoterule (for use in minipages), pagefootnoterule (for use on regular pages), and splitfootnoterule (for use on pages starting with a split footnote). By modifying their definitions, similar to the example given earlier for the footnoterule command, you can customize the layout according to your needs.

In classes such as article or report in which aggedbottom is in effect, so that columns are allowed to be of different heights, the footnotes are attached at a distance of skipfootins from the column text. If you prefer them aligned at the bottom, so that any excess space is put between the text and the footnotes, specify the option bottom. In classes for which flushbottom is in force, such as book, this option does nothing.

In some documents, e.g., literary analysis, several footnotes may appear at a single point. Unfortunately, LaTeX’s standard footnote commands are not able to handle this situation correctly: the footnote markers are simply clustered together so that you cannot tell whether you are to look for the footnotes 1 and 2, or for the footnote with the number 12.

This problem will be resolved by specifying the option multiple, which ensures that footnotes in a sequence will display their markers separated by commas. The separator can be changed to something else, such as a small space, by changing the command multfootsep.

The footmisc package deals with one other potential problem: if you put a footnote into a sectional unit, then it might appear in the table of contents or the running header, causing havoc. Of course, you could prevent this dilemma (manually) by using the optional argument of the heading command; alternatively, you could specify the option stable, which prevents footnotes from appearing in such places.

The declaration MakePerPage defines counter to be reset on every page, optionally requesting that its initial starting value be start (default 1). For demonstration we repeat Example 3-2-7 on page 116 but start each footnote marker sequence with the second symbol (i.e., “†” instead of “*”).

The package synchronizes the numbering via the .aux file of the document, thus requiring at least two runs to get the numbering correct. In addition, you may get spurious “Counter too large” error messages on the first run if fnsymbol or alph is used for numbering (see the discussion of the symbol* option for the footmisc package on page 116).

Among LaTeX’s standard counters probably only footnote can be sensibly modified in this way. Nevertheless, one can easily imagine applications that provide, say, numbered marginal notes, which could be defined as follows:

We step the new counter mnote outside the marginpar so that it is executed only once;¹ we also need to limit the scope of the current redefinition of label (through efstepcounter) so we put braces around the whole definition. Notes on left-hand pages should be right aligned, so we use the optional argument of marginpar to provide different formatting for this case.

¹ If placed in both arguments of marginpar it would be executed twice. It would work if placed in the optional argument only, but then we would make use of an implementation detail (that the optional argument is evaluated first) that may change.

Another application for the package is given in Example 3-2-24 on page 125, where several independent footnote streams are all numbered on a per-page basis.

¹ A more comprehensive package, bigfoot, is currently being developed by David Kastrup.

This declaration can be used to introduce a new footnote level. In its simplest form you merely specify a suffix such as “B”. This allocates a new counter footnote 〈suffix〉 that is used to automatically number the footnotes on the new level. The default is to use Arabic numerals; by providing the optional argument enum-style, some other counter style (e.g., roman or alph) can be selected.

The optional fn-style argument defines the general footnote style for the new level; the default is plain. If the package was loaded with the para or para* option, then para can also be selected as the footnote style.

The declaration will then automatically define six commands for you. The first three are described here:

footnote 〈suffix〉 [number]{text} Same as footnote but for the new level. Steps the footnote 〈suffix〉 counter unless the optional number argument is given. Generates footnote markers and puts text at the bottom of the page.

footnotemark 〈suffix〉 [number] Same as footnotemark but for the new level. Steps the corresponding counter (if no optional argument is used) and prints a footnote marker corresponding to its value.

footnotetext 〈suffix〉 [number]{text} Same as footnotetext but for the new level. Puts text at the bottom of the page using the current value of footnote 〈suffix〉 or the optional argument to generate a footnote marker in front of it.

In all three cases the style of the markers depends on the chosen enum-style.

The remaining three commands defined by DeclareNewFootnote for use in the document are Footnote 〈suffix〉, Footnotemark 〈suffix〉, and Footnotetext 〈suffix〉 (i.e., same names as above but starting with an upper-case F). The important difference to the previous set is the following: instead of the optional number argument, they require a mandatory marker argument allowing you to specify arbitrary markers if desired. Some examples are given below.

The layout of the footnotes can be influenced by loading the footmisc package in addition to manyfoot, except that the para option of footmisc cannot be used. In the next example we use the standard footnote layout for top-level footnotes and the run-in layout (option para) for the second level. Thus, if all footnote levels should produce run-in footnotes, the solution is to avoid top-level footnotes completely (e.g., footnote) and provide all necessary levels through manyfoot. Note how footmisc’s multiple option properly acts on all footnotes.

In the following example the top-level footnotes are moved into the margin by loading footmisc with a different set of options. This time manyfoot is loaded with the option para*, which differs from the para option used previously in that it suppresses any indentation for the run-in footnote block. In addition, the second-level notes are now numbered with Roman numerals. For comparison the example typesets the same input text as Example 3-2-19 but it uses a different measure, as we have to show marginal notes now.

The use of run-in footnotes, with either the para or the para* option, is likely to produce one particular problem: very long footnotes near a page break will not be split. To resolve this problem the manyfoot package offers a (semi)manual solution: at the point where you wish to split your note you place a SplitNote command and end the footnote. You then place the remaining text of the footnote one paragraph farther down in the document in a Footnotetext 〈suffix〉 using an empty marker argument.

If both parts of the footnote fall onto the same page after reformatting the document, the footnote parts get correctly reassembled, as we prove in the next example, which uses the same example text but a different measure. However, if the reformatting requires breaking the footnote in a different place, then further manual intervention is unavoidable. Thus, such work is best left until the last stage of production.

The vertical separation between a footnote block and the previous one is specified by skipfootins 〈suffix〉. By default, it is equal to skipfootins (i.e., the separation between main text and footnotes). Initially the extra blocks are only separated by such spaces, but if the option ruled is included a footnoterule is used as well. In fact, arbitrary material can be placed in that position by redefining the command extrafootnoterule—the only requirement being that the typeset result from that command does not take up any additional vertical space (see the discussion of footnoterule on page 112 for further details). It is even possible to use different rules for different blocks of footnotes; consult the package documentation for details.

Number the footnotes per page

The previous example deployed two additional enum-styles, Alph and fnsymbol. However, as only a few footnote symbols are available in both styles, that choice is most likely not a good one, unless we ensure that these footnote streams are numbered on a per-page basis. The perpage option of footmisc will not help here, as it applies to only the top-level footnotes. We can achieve the desired effect either by using MakePerPage from the perpage package on the counters footnoteB and footnoteC (as done below), or by using the perpage option of manyfoot (which calls on the perpage package to do the job, which will number all new footnote levels defined on a per-page basis). Note that the top-level footnotes are still numbered sequentially the way the example was set up.

The package endnotes (by John Lavagnino) provides its own endnote command, thus allowing footnotes and endnotes to coexist.

The document-level syntax is modeled after the footnote commands if you replace foot with end—for example, endnote produces an endnote, endnotemark produces just the mark, and endnotetext produces just the text. The counter used to hold the current endnote number is called endnote and is stepped whenever endnote or endnotemark without an optional argument is used.

All endnotes are stored in an external file with the extension .ent and are made available when you issue the command heendnotes.

This process is different from the way the table of contents is built; the end-notes are written directly to the file, so that you will see only those endnotes which are defined earlier in the document. The advantage of this approach is that you can have several calls to heendnotes, for example, at the end of each chapter. To additionally restart the numbering you have to set the endnote counter to zero after calling heendnotes.

The heading produced by heendnotes can be controlled in several ways. The text can be changed by modifying otesname (default is the string Notes). If that is not enough you can redefine enoteheading, which is supposed to produce the sectioning command in front of the notes.

The layout for endnote numbers is controlled through heendnote, which is the standard way LaTeX handles counter formatting. The format of the mark is produced from makeenmark with heenmark, holding the formatted number for the current mark.

The font size for the list of endnotes is controlled through enotesize, which defaults to footnotesize. Also, by modifying enoteformat you can change the display of the individual endnotes within their list. This command is supposed to set up the paragraph parameters for the endnotes and to typeset the note number stored in heenmark. In the example we start with no indentation for the first paragraph and with the number placed into the margin.

This placement strategy can be reversed (except for two-column formatting) using eversemarginpar, which acts on all marginal notes from there on. You can return to the default behavior with ormalmarginpar.

There are a few important things to understand when using marginal notes. First, the marginpar command does not start a paragraph. Thus, if it is used before the first word of a paragraph, the vertical alignment will not match the beginning of the paragraph. Second, the first word of its argument is not automatically hyphenated. Thus, for a narrow margin and long words (as in German), you may have to precede the first word by a hspace{0pt} command to allow hyphenation of that word. These two potential problems can be eased by defining a command like marginlabel, which starts with an empty box mbox{}, typesets a marginal note ragged right, and adds a hspace{0pt} in front of the argument.

Of course, the above definition can no longer produce different texts depending on the chosen margin. With a little more finesse this problem could be solved, using, for example, the ifthenelse constructs from the ifthen package.

Incorrectly placed marginpars

The LaTeX kernel tries hard (without producing too much processing overhead) to ensure that the contents of marginpar commands always show up in the correct margin and in most circumstances will make the right decisions. In some cases, however, it will fail. If you are unlucky enough to stumble across one of them, a one-off solution is to add an explicit pagebreak to stop the page generation from looking too far ahead. Of course, this has the disadvantage that the correction means visual formatting and has to be undone if the document changes. A better solution is to load the package mparhack written by Tom Sgouros and Stefan Ulrich. Once this package is loaded all marginpar positions are tracked (internally using a label mechanism and writing the information to the .aux file). You may then get a warning “Marginpars may have changed. Rerun to get them right”, indicating that the positions have changed in comparison to the previous LaTeX run and that a further run is necessary to stabilize the document.

As explained in Table 4.2 on page 196, there are three length parameters to customize the style of marginal notes: marginparwidth, marginparsep, and marginparpush.