• Create BookmarkCreate Bookmark
• Create Note or TagCreate Note or Tag
• PrintPrint

### 3.3. List structures

Lists are very important LaTeX constructs and are used to build many of LaTeX’s display-like environments. LaTeX’s three standard list environments are discussed in Section 3.3.1, where we also show how they can be customized. Section 3.3.2 starting on page 132 provides an in-depth discussion of the paralist package, which introduces a number of new list structures and offers comprehensive methods to customize them, as well as the standard lists. It is followed by a discussion of “headed lists”, such as theorems and exercises. Finally, Section 3.3.4 on page 144 discusses LaTeX’s general list environment.

#### 3.3.1. Modifying the standard lists

It is relatively easy to customize the three standard LaTeX list environments itemize, enumerate, and description, and the next three sections will look at each of these environments in turn. Changes to the default definitions of these environments can either be made globally by redefining certain list-defining parameters in the document preamble or can be kept local.

##### Customizing the itemize list environment

For a simple unnumbered itemize list, the labels are defined by the commands shown in Table 3.5. To create a list with different-looking labels, you can redefine the label-generating command(s). You can make that change local for one list, as in the example below, or you can make it global by putting the redefinition in the document preamble. The following simple list is a standard itemize list with a marker from the PostScript Zapf Dingbats font (see Section 7.6.4 on page 378) for the first-level label:

Table 3.5. Commands controlling an itemize list environment

3-3-1
##### Customizing the enumerate list environment

LaTeX’s enumerated (numbered) list environment enumerate is characterized by the commands and representation forms shown in Table 3.6 on the next page. The first row shows the names of the counter used for numbering the four possible levels of the list. The second and third rows are the commands giving the representation of the counters and their default definition in the standard LaTeX class files. Rows four, five, and six contain the commands, the default definition, and an example of the actual enumeration string printed by the list.

Table 3.6. Commands controlling an enumerate list environment

A reference to a numbered list element is constructed using the \theenumi, \theenumii, and similar commands, prefixed by the commands \p@enumi, \p@enumii, etc., respectively. The last three rows in Table 3.6 on the following page show these commands, their default definition, and an example of the representation of such references. It is important to consider the definitions of both the representation and reference-building commands to get the references correct.

We can now create several kinds of numbered description lists simply by applying what we have just learned.

Our first example redefines the first- and second-level counters to use capital Roman digits and Latin characters. The visual representation should be the value of the counter followed by a dot, so we can use the default value from Table 3.6 on the next page for \labelenumi.

3-3-2

After these redefinitions we get funny-looking references; to correct this we have to adjust the definition of the prefix command \p@enumii. For example, to get a reference like “I–A” instead of “IA” as in the previous example, we need

because the reference is typeset by executing \p@enumii followed by \theenumii. Note that we need \makeatletter and \makeatother because the command name to redefine contains an @ sign. Instead of this low-level method, consider using \labelformat from the varioref package described in Section 2.4.2.

You can also decorate an enumerate field by adding something to the label field. In the example below, we have chosen for the first-level list elements the paragraph sign (§) as a prefix and a period as a suffix (omitted in references).

3-3-3

You might even want to select different markers for consecutive labels. For instance, in the following example, characters from the PostScript font ZapfDingbats are used. In this case there is no straightforward way to automatically make the \ref commands produce the correct references. Instead of \theenumi simply producing the representation of the enumi counter, we define it to calculate from the counter value which symbol to select. The difficulty here is to create this definition in a way such that it survives the label-generating process. The trick is to add the \protect commands so that \setcounter and \ding are not executed when the label is written to the .aux file, yet to ensure that the current value of the counter is stored therein. The latter goal is achieved by prefixing \value by the (internal) TeX command \the within \setcounter (but not within \ding!); without it the references would all show the same values.1

1 For the TeXnically interested: LaTeX’s \value command, despite its name, does not produce the “value” of a LaTeX counter but only its internal TeX register name. In most circumstances this can be used as the value but unfortunately not inside \edef or \write, where the internal name rather than the “value” will survive. By prefixing the internal register name with the command \the, we get the “value” even in such situations.

3-3-4

The same effect is obtained with the dingautolist environment defined in the pifont package, which is part of the PSNFSS system (see Section 7.6.4 on page 378).

##### Customizing the description list environment

With the description environment you can change the \descriptionlabel command that generates the label. In the following example the font for typesetting the labels is changed from boldface (default) to sans serif.

3-3-5

The standard LaTeX class files set the starting point of the label box in a description environment at a distance of \labelsep to the left of the left margin of the enclosing environment. Thus, the \descriptionlabel command in the example above first adds a value of \labelsep to start the label aligned with the left margin (see page 147 for detailed explanations).

#### 3.3.2. paralist—Extended list environments

The paralist package created by Bernd Schandl provides a number of new list environments and offers extensions to LaTeX’s standard ones that make their customization much easier. Standard and new list environments can be nested within each other and the enumeration environments support the \label/\ref mechanism.

##### Enumerations

All standard LaTeX lists are display lists; that is, they leave some space at their top and bottom as well as between each item. Sometimes, however, one wishes to enumerate something within a paragraph without such visual interruption. The inparaenum environment was developed for this purpose. It supports an optional argument that you can use to customize the generated labels, the exact syntax of which is discussed later in this section.

3-3-6

But perhaps this is not precisely what you are looking for. A lot of people like to have display lists but prefer them without much white space surrounding them. In that case compactenum might be your choice, as it typesets the list like enumerate but with all vertical spaces set to 0pt.

3-3-7

Actually, our previous statement was not true—you can customize the vertical spaces used by compactenum. Here are the parameters: \pltopsep is the space above and below the environment, \plpartopsep is the extra space added to the previous space when the environment starts a paragraph on its own, \plitemsep is the space between items, and \plparsep is the space between paragraphs within an item.

A final enumeration alternative is offered with the asparaenum environment, which formats the items as individual paragraphs. That is, their first line is indented by \parindent and following lines are aligned with the left margin.

3-3-8

As seen in the previous examples all enumeration environments support one optional argument that describes how to format the item labels. Within the argument the tokens A, a, I, i, and 1 have a special meaning: they are replaced by the enumeration counter displayed in style \Alph, \alph, \Roman, \roman, or \arabic, respectively. All other characters retain their normal meanings. Thus, the argument [(a)] will result in labels like (a), (b), (c), and so on, while [\S i:] will produce §i:, §ii:, §iii:, and so on.

You have to be a bit careful if your label contains text strings, such as labels like Example 1, Example 2, ... In this case you have to hide the “a” inside a brace group—that is, use an argument like [{Example} 1]. Otherwise, you will get strange results, as shown in the next example.

3-3-9

Fortunately, the package usually detects such incorrect input and will issue a warning message. A consequence of hiding special characters by surrounding them with braces is that an argument like [\textbf{a)}] will not work either, because the “a” will not be considered as special any more. A workaround for this case is to use something that does not require braces, such as \bfseries.

As can be seen above, referencing a \label will produce only the counter value in the chosen representation but not any frills added in the optional argument. This is the case for all enumeration environments.

It is not possible with this syntax to specify that a label should show the outer as well as the inner enumeration counter, because the special characters always refer to the current enumeration counter. There is one exception: if you load the package with the option pointedenum or with the option pointlessenum, you will get labels like those shown in the next example.

3-3-10

The difference between the two options is the presence or absence of the trailing period. As an alternative to the options you can use the commands \pointedenum and \pointlessenum. They enable you to define your own environments that format labels in this way while other list environments show labels in different formats. If you need more complicated labels, such as those involving several enumeration counters from different levels, then you have to construct them manually using the methods described in Section 3.3.1 on page 129.

The optional argument syntax for specifying the typesetting of enumeration labels was first implemented in the enumerate package by David Carlisle, who extended the standard enumerate environment to support such an optional argument. With paralist the optional argument is supported for all enumeration environments, including the standard enumerate environment (for which it is an upward-compatible extension).

If an optional argument is used on any of the enumeration environments, then by default the left margin will be made only as wide as necessary to hold the labels. More exactly, the indentation is adjusted to the width of the label as it would be if the counter value is currently seven. This produces a fairly wide number (vii) if the numbering style is “Roman” and does not matter otherwise. This behavior is shown in the next example. For some documents this might be the right behavior, but if you prefer a more uniform indentation use the option neverdecrease, which will ensure that the left margin is always at least as wide as the default setting.

3-3-11

On the other hand, you can always force that kind of adjustment, even for environments without an optional argument, by specifying the option alwaysadjust.

3-3-12

Finally, with the option neveradjust the standard indentation is used in all cases. Thus, labels that are too wide will extend into the left margin.

3-3-13
##### Itemizations

For itemized lists the paralist package offers the environments compactitem, which is a compact version of the standard itemize environment; asparaitem which formats the items as paragraphs; and inparaitem, which produces an inline itemization. The last environment was added mainly for symmetry reasons. All three environments accept an optional argument, that specifies the label to be used for each item.

3-3-14

The three label justification options neverdecrease, alwaysadjust, and neveradjust are also valid for the itemized lists, as can be seen in the previous example. When the paralist package is loaded, LaTeX’s itemize environment is extended to also support that type of optional argument.

##### Descriptions

For descriptions the paralist package introduces three additional environments: compactdesc, which is like the standard LaTeX description environment but with all vertical spaces reduced to zero (or whatever you specify as a customization); asparadesc, which formats each item as a paragraph; and inparadesc, which allows description lists within running text.

Because description-type environments specify each label at the \item command, these environments have no need for an optional argument.

3-3-15

Besides providing these useful new environments the paralist package lets you customize the default settings of enumerated and itemized lists.

You can specify the default labels for different levels of itemized lists with the help of the \setdefaultitem declaration. It takes four arguments (as four levels of nesting are possible). In each argument you specify the desired label (just as you do with the optional argument on the environment itself) or, if you are satisfied with the default for the given level, you specify an empty argument.

3-3-16

The changed defaults apply to all subsequent itemized environments. Normally, such a declaration is placed into the preamble, but you can also use it to change the defaults mid-document. In particular, you can define environments that contain a \setdefaultitem declaration which would then apply only to that particular environment—and to lists nested within its body.

You will probably not be surprised to learn that a similar declaration exists for enumerations. By using \setdefaultenum you can control the default look and feel of such environments. Again, there are four arguments corresponding to the four levels. In each you either specify your label definition (using the syntax explained earlier) or you leave it empty to indicate that the default for this level should be used.

3-3-17

There is also the possibility of adjusting the indentation for the various list levels using the declaration \setdefaultleftmargin. However, this command has six arguments (there are a total of six list levels in the standard LaTeX classes), each of which takes either a dimension denoting the increase of the indention at that level or an empty argument indicating to use the current value as specified by the class or elsewhere. Another difference from the previous declarations is that in this case we are talking about the absolute list levels and not about relative levels related to either enumerations or itemizations (which can be mixed). Compare the next example with the previous one to see the difference.

3-3-18

By default, enumeration and itemized lists set their labels flush right. This behavior can be changed with the help of the option flushleft.

As described earlier, the label of the standard description list can be adjusted by modifying \descriptionlabel, which is also responsible for formatting the label in a compactdesc environment. With inparadesc and asparadesc, however, a different command, \paradescriptionlabel, is used for this purpose. As these environments handle their labels in slightly different ways, they do not need adjustments involving \labelsep (see page 147). Thus, its default definition is simply:

Finally, the paralist package supports the use of a configuration file named paralist.cfg, which by default is loaded if it exists. You can prevent this by specifying the option nocfg.

The term “headed lists” describes typographic structures that, like other lists such as quotations, form a discrete part of a section or chapter and whose start and finish, at least, must be clearly distinguished. This is typically done by adjusting the vertical space at the start or adding a rule, and in this case also by including some kind of heading, similar to a sectioning head. The end may also be distinguished by a rule or other symbol, maybe within the last paragraph, and by extra vertical space.

Another property that distinguishes such lists is that they are often numbered, using either an independent system or in conjunction with the sectional numbering.

Perhaps one of the more fruitful sources of such “headed lists” is found in the so-called “theorem-like” environments. These had their origins in mathematical papers and books but are equally applicable to a wide range of expository material, as examples and exercises may take this form whether or not they contain mathematical material.

Because their historical origins lie in the mathematical world, we choose to describe the amsthm package [7] by Michael Downes from the American Mathematical Society (AMS) as a representative of this kind of extension.1 This package provides an enhanced version of standard LaTeX’s \newtheorem declaration for specifying theorem-like environments (headed lists).

1 When the amsthm package is used with a non-AMS document class and with the amsmath package, amsthm must be loaded after amsmath. The AMS document classes incorporate both packages.

As in standard LaTeX, environments declared in this way take an optional argument in which extra text, known as “notes”, can be added to the head of the environment. See the example below for an illustration.

The \newtheorem declaration has two mandatory arguments. The first is the environment name that the author would like to use for this element. The second is the heading text.

If \newtheorem* is used instead of \newtheorem, no automatic numbers will be generated for the environments. This form of the command can be useful if you have only one lemma or exercise and do not want it to be numbered; it is also used to produce a special named variant of one of the common theorem types.

3-3-19

In addition to the two mandatory arguments, \newtheorem has two mutually exclusive optional arguments. They affect the sequencing and hierarchy of the numbering.

By default, each kind of theorem-like environment is numbered independently. Thus, if you have lemmas, theorems, and some examples interspersed, they will be numbered something like this: Example 1, Lemma 1, Lemma 2, Theorem 1, Example 2, Lemma 3, Theorem 2. If, for example, you want the lemmas and theorems to share the same numbering sequence—Example 1, Lemma 1, Lemma 2, Theorem 3, Example 2, Lemma 4, Theorem 5—then you should indicate the desired relationship as follows:

The optional use-counter argument (value thm) in the second statement means that the lem environment should share the thm numbering sequence instead of having its own independent sequence.

To have a theorem environment numbered subordinately within a sectional unit—for example, to get exercises numbered Exercise 2.1, Exercise 2.2, and so on, in Section 2—put the name of the parent counter in square brackets in the final position:

With the optional argument [section], the exa counter will be reset to 0 whenever the parent counter section is incremented.

##### Defining the style of headed lists

The specification part of the amsthm package supports the notion of a current theorem style, which determines the formatting that will be set up by a collection of \newtheorem commands.1

1 This was first introduced in the now-superseded theorem package by Frank Mittelbach.

The three theorem styles provided by the package are plain, definition, and remark; they specify different typographical treatments that give the environments a visual emphasis corresponding to their relative importance. The details of this typographical treatment may vary depending on the document class, but typically the plain style produces italic body text and the other two styles produce Roman body text.

To create new theorem-like environments in these styles, divide your \newtheorem declarations into groups and preface each group with the appropriate \theoremstyle. If no \theoremstyle command is given, the style used will be plain. Some examples follow:

3-3-20

Note that the fairly obvious choice of “def” for the name of a “Definition” environment does not work, because it conflicts with the existing low-level TeX command \def.

Number swapping

A fairly common style variation for theorem heads is to have the theorem number on the left, at the beginning of the heading, instead of on the right. As this variation is usually applied across the board regardless of individual \theoremstyle changes, swapping numbers is done by placing a \swapnumbers declaration at the beginning of the list of \newtheorem statements that should be affected.

More extensive customization capabilities are provided by the package through the \newtheoremstyle declaration and through a mechanism for using package options to load custom theorem style definitions.

To set up a new style of “theorem-like” headed list, use this declaration with the nine mandatory arguments described below. For many of these arguments, if they are left empty, a default is used as listed here.

name The name used to refer to the new style.

space-above The vertical space above the headed list, a rubber length (default \topsep).

space-below The vertical space below the headed list, a rubber length (default \topsep).

body-style A declaration of the font and other aspects of the style to use for the text in the body of the list (default \normalfont).

indent The extra indentation of the first line of the list, a non-rubber length (default is no extra indent).

head-style A declaration of the font and other aspects of the style to use for the text in the head of the list (default \normalfont).

head-after-punct The text (typically punctuation) to be inserted after the head text, including any note text.

head-after-space The horizontal space to be inserted after the head text and “punctuation”, a rubber length. It cannot be completely empty. As two very special cases it can contain either a single space character to indicate that just a normal interword space is required or, more surprisingly, just the command \newline to indicate that a new line should be started for the body of the list.

head-full-spec A non-empty value for this argument enables a complete specification of the setting of the head itself to be supplied; an empty value means that the layout of the “plain” theorem style is used. See below for further details.

Any extra set-up code for the whole environment is best put into the body-style argument, although care needs to be taken over how it will interact with what is set up automatically. Anything that applies only to the head can be put in head-style.

In the example below we define a break theorem style, which starts a new line after the heading. The heading text is set in bold sans serif, followed by a colon and outdented into the margin by 12pt. Since the book examples are typeset in a very small measure, we added \raggedright1 to the body-style argument.

1 The example does not work if ragged2e is loaded (as of 2005), so \RaggedRight cannot be used.

3-3-21

The head-full-spec argument, if non-empty, becomes the definition part of an internal command that is used to typeset the (up to) three bits of information contained in the head of a theorem-like environment: its number (if any), its name, and any extra notes supplied by the author when using the environment. Thus, it should contain references to three arguments that will then be replaced as follows:

#1 The fixed text that is to be used in the head (for example, “Exercises”), It comes from the \newtheorem used to declare an environment.

#2 A representation of the number of the element, if it should be numbered. It is conventionally left empty if the environment should not be numbered.

#3 The text for the optional note, from the environment’s optional argument.

Assuming all three parts are present, the contents of the head-full-spec argument could look as follows:

Although you are free to make such a declaration, it is normally best not to use these arguments directly as this might lead to unwanted extra spaces if, for example, the environment is unnumbered.

To account for this extra complexity, the package offers three additional commands, each of which takes one argument: \thmname, \thmnumber, and \thmnote. These three commands are redefined at each use of the environment so as to process their arguments in the correct way. The default for each of them is simply to “typeset the argument”. Nevertheless, if, for example, the particular occurrence is unnumbered, then \thmnumber gets redefined to do no typesetting. Thus, a better definition for the head-full-spec argument would be

which corresponds to the set-up used by the default plain style. Note the spaces within the last two arguments: they provide the interword spaces needed to separate the parts of the typeset head but, because they are inside the arguments, they are present only if that part of the head is typeset.

In the following example we provide a “Theorem” variation in which the whole theorem heading has to be supplied as an optional note, such as for citing theorems from other sources.

3-3-22
##### Proofs and the QED symbol

Of more specifically mathematical interest, the package defines a proof environment that automatically adds a “QED symbol” at the end. This environment produces the heading “Proof” with appropriate spacing and punctuation.1

1 The proof environment is primarily intended for short proofs, no more than a page or two in length. Longer proofs are usually better done as a separate \section or \subsection in your document.

An optional argument of the proof environment allows you to substitute a different name for the standard “Proof”. If you want the proof heading to be, for example, “Proof of the Main Theorem”, then put this in your document:

A “QED symbol” (default ) is automatically appended at the end of a proof environment. To substitute a different end-of-proof symbol, use \renewcommand to redefine the command \qedsymbol. For a long proof done as a subsection or section, you can obtain the symbol and the usual amount of preceding space by using the command \qed where you want the symbol to appear.

Automatic placement of the QED symbol can be problematic if the last part of a proof environment is, for example, tabular or a displayed equation or list. In that case put a \qedhere command at the somewhat earlier place where the QED symbol should appear; it will then be suppressed from appearing at the logical end of the proof environment. If \qedhere produces an error message in an equation, try using \mbox{\qedhere} instead.

3-3-23

#### 3.3.4. Making your own lists

Most lists in LaTeX, including those we have seen previously, are internally built using the generic list environment. It has the following syntax:

The argument default-label is the text to be used as a label when an \item command is found without an optional argument. The second argument, decls, can be used to modify the different geometrical parameters of the list environment, which are shown schematically in Figure 3.3 on the next page.

3-3-24

Figure 3.3. Parameters used by the list environment

The default values of these parameters typically depend on the type size and the level of the list. Those being vertically oriented are rubber lengths, meaning that they can stretch or shrink. They are set by the list environment as follows: upon entering the environment the internal command \@list level is executed, where level is the list nesting level represented as a Roman numeral (e.g., \@listi for the first level, \@listii for the second, \@listiii for the third, and so on). Each of these commands, defined by the document class, holds appropriate settings for the given level. Typically, the class contains separate definitions for each major document size available via options. For example, if you select the option 11pt, one of its actions is to change the list defaults. In the standard classes this is done by loading the file size11.clo, which contains the definitions for the 11pt document size.

In addition, most classes contain redefinitions of \@listi (i.e., first-level list defaults) within the size-changing commands \normalsize, \small, and \footnotesize, the assumption being that one might have lists within “small” or “footnote-sized” text. However, since this is a somewhat incomplete set-up, strange effects are possible if you

• Use nested lists in such small sizes (the nested lists get the standard defaults intended for \normalsize),

• Jump from \small or \footnotesize directly to a large size, such as \huge (a first-level list now inherits the defaults from the small size, since in this set-up \huge does not reset the list defaults).

With a more complex set-up these defects could be mended. However, since the simpler set-up works well in most practical circumstances, most classes provide only this restricted support.

Global changes are difficult

Because of this size- and nesting-dependent set-up for the list parameters, it is not possible to change any of them globally in the preamble of your document. For global changes you have to provide redefinitions for the various \@list.. commands discussed above or select a different document class.

Page breaking around lists

Page breaking around and within a list structure is controlled by three TeX counters: \@beginparpenalty (for breaking before the list), \@itempenalty (for breaking before an item within the list), and \@endparpenalty (for breaking the page after a list). By default, all three are set to a slightly negative value, meaning that it is permissible (and even preferable) to break a page in these places compared to other break points. However, this outcome may not be appropriate. You may prefer to discourage or even prevent page breaks directly before a list. To achieve this, assign a high value to \@beginparpenalty (10000 or more prohibits the break in all circumstances), for example:

TeX counters need this unusual assignment form and since all three contain an @ sign in their name, you have to surround them with \makeatletter and \makeatother if the assignment is done in the preamble.

Many environments are implemented as lists

It is important to realize that such a setting is global to all environments based on the generic list environment (unless it is made in the decls argument) and that several LaTeX environments are defined with the help of this environment (for example, quote, quotation, center, flushleft, and flushright). These environments are “lists” with a single item, and the \item[] command is specified in the environment definition. The main reason for them to be internally defined as lists is that they then share the vertical spacing with other display objects and thus help achieve a uniform layout.

As an example, we can consider the quote environment, whose definition gives the same left and right margins. The simple variant Quote, shown below, is identical to quote apart from the double quote symbols added around the text. Note the special precautions, which must be taken to eliminate undesirable white space in front of (\ignorespaces) and following (\unskip) the text. We also placed the quote characters into boxes of zero width to make the quotes hang into the margin. (This trick is worth remembering: if you have a zero-width box and align the contents with the right edge, they will stick out to the left.)

3-3-25

In the remainder of this section we will construct a number of different “description” lists, thereby explaining the various possibilities offered by the generic list environment. We start by looking at the default definition of the description environment as it can be found in LaTeX’s standard classes such as article or report.1

1 If you look into article.cls or report.cls you will find a slightly optimized coding that uses, for example, low-level assignments instead of \setlength. However, conceptually, the definitions are identical.

To understand the reasoning behind this definition recall Figure 3.3 on page 145, which explains the relationship between the various list parameters. The parameter settings start by setting \labelwidth to zero, which means that we do not reserve any space for the label. Thus, if the label is being typeset, it will move the text of the first line to the right to get the space it needs. Then the \itemindent parameter is set to the negation of \leftmargin. As a result, the starting point for the first text line is moved to the enclosing margin but all turnover lines are still indented by \leftmargin. The last declaration makes \makelabel identical to the command \descriptionlabel. The command \makelabel is called by the list environment whenever it has to format an item label. It takes one argument (the label) and is supposed to produce a typeset version of that argument. So the final task to finish the definition of the description environment is to provide a suitable definition for \descriptionlabel. This indirection is useful because it allows us to change the label formatting without modifying the rest of the environment definition.

How should \descriptionlabel be defined? It has to provide the formatting for the label. With the standard description environment this label is supposed to be typeset in boldface. But recall that the label is separated from the following text by a space of width \labelsep. Due to the parameter settings given above this text starts at the outer margin. Thus, without correction our label would end up starting in the margin (by the width of \labelsep). To prevent this outcome the standard definition for the \descriptionlabel command has the following curious definition, in that it first moves to the right and then typesets the label:

To remove this dependency, one would need to change the setting of \itemindent to already take the \labelsep into account, which in itself would not be difficult. You may call this behavior an historical artifact, but many documents rely on this somewhat obscure feature. Thus, it is difficult to change the setting in the LaTeX kernel without breaking those documents.

With the parameter settings of the standard description environment, in case of short labels the text of the first line starts earlier than the text of remaining lines. If we always want a minimal indentation we can try a definition similar to the one in the following example, where we set \labelwidth to 40pt and \leftmargin to \labelwidth plus \labelsep. This means that \makelabel has to concern itself only with formatting the label. However, given that we now have a positive nominal label width, we need to define what should happen if the label is small. By using \hfil we specify where extra white space should be inserted.

3-3-26

This example shows a typical problem with description-like lists when the text in the label (term) is wider than the width of the label. Our definition lets the text of the term continue into the text of the description part. This is often not desired, and to improve the visual appearance of the list we have started one of the description parts on the next line. A new line was forced by putting an empty box on the same line, followed by the ‘\\’ command.

In the remaining part of this section various possibilities for controlling the width and mutual positioning of the term and description parts will be investigated. The first method changes the width of the label. The environment is declared with an argument specifying the desired width of the label field (normally chosen to be the widest term entry). Note the redefinition of the \makelabel command where you specify how the label will be typeset. As this redefinition is placed inside the definition1 of the altDescription environment, the argument placeholder character # must be escaped to ## to signal LaTeX that you are referring to the argument of the \makelabel command, and not to the argument of the outer environment. In such a case, \labelwidth is set to the width of the environment’s argument after it is processed by \makelabel. This way formatting directives for the label that might change its width are taken into account.

1 This is done for illustration purposes. Usually the solution involving an external name is preferable, as with \Descriptionlabel in Example 3-3-26 on the preceding page.

3-3-27

A similar environment (but using an optional argument) is shown in Example A-1-9 on page 850. However, having several lists with varying widths for the label field on the same page might look typographically unacceptable. Evaluating the width of the term is another possibility that avoids this problem. If the width is wider than \labelwidth, an additional empty box is appended with the effect that the description part starts on a new line. This matches the conventional method for displaying options in UN*X manuals.

To illustrate this method we reuse the Description environment defined in Example 3-3-26 but provide a different definition for the \Descriptionlabel command as follows:

3-3-28

The definition of \Descriptionlabel sets the length variable \Mylen equal to the width of the label. It then compares that length with \labelwidth. If the label is not wider than \labelwidth, then it is typeset on the same line as the description term. Otherwise, it is typeset in a zero-width box with the material sticking out to the right as far as needed. It is placed into a bottom-aligned \parbox followed by a forced line break so that the description term starts one line lower. This somewhat complicated maneuver is necessary because \makelabel, and thus \Descriptionlabel, are executed in a strictly horizontal context in which vertical spaces or \\ commands have no effect.

Yet another possibility is to allow multiple-line labels.

3-3-29

In the previous example, we once again used the Description environment as a basis, with yet another redefinition of the \Descriptionlabel command. The idea here is that large labels may be split over several lines. Certain precautions have to be taken to allow hyphenation of the first word in a paragraph, and therefore the \hspace{0pt} command is introduced in the definition. The material gets typeset inside a paragraph box of the correct width \labelwidth, which is then top and left aligned into a box that is itself placed inside a box with a height of 1 ex and no depth. In this way, LaTeX does not realize that the material extends below the first line.

The final example deals with the definition of enumeration lists. An environment with an automatically incremented counter can be created by including a \usecounter command in the declaration of the list environment. This function is demonstrated with the Notes environment, which produces a sequence of notes. In this case, the first parameter of the list environment is used to provide the automatically generated text for the term part.

After declaring the notes counter, the default label of the Notes environment is defined to consist of the word NOTE in small caps, followed by the value of the notes counter, using as its representation an Arabic numeral followed by a dot. Next \labelsep is set to a relatively large value and \itemindent, \leftmargin, and \labelwidth are adjusted in a way such that the label nevertheless starts out at the left margin. Finally, the already-mentioned \usecounter declaration ensures that the notes counter is incremented for each \item command.

3-3-30
• Create BookmarkCreate Bookmark
• Create Note or TagCreate Note or Tag
• PrintPrint