# CERN Accelerating science

This website is no longer maintained. Its content may be obsolete. Please visit http://home.cern/ for current CERN information.

Next: Text Processing and Up: Customizing LaTeX lists Previous: Modifying LaTeX Lists

Lists are generated by the generic environment list:

begin}default_labeldecls
item_list
end}

The parameter default_label is the text to be used as a label when an \item command is issued without an optional argument. The parameter decls sets up the different geometrical parameters of the list environment (see Fig. ). That figure also shows the default values for those parameters. The parameters can all be redefined with the help of the \setlength or \addtolength commands.

: The structure of a general list

Several LaTeX environments are defined with the help of list (for example quote, quotation, center, flushleft, and flushright). Note that these environments have only one item, and the \Lcs{item[]} command is specified in the environment definition.

As an example, we can consider the quote environment whose definition gives it 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.

\newenvironment{Quote}% Definition of Quote
{\begin{list}{}{%
\setlength{\rightmargin}{\leftmargin}}
\item[]\ignorespaces}
{\unskip''\end{list}}
\ldots\ text before.
\begin{Quote}
Some quoted text, more quoted text.
Some quoted text, more quoted text.
\end{Quote}
Text following \ldots


... text before.

 quoted text, more quoted text. Some quoted text, more quoted text. ''
Text following ...

General lists are often used for documenting computer commands or program functions. For instance, in the following examples entry and its variants are used. In each case the name of the topic being described is entered as the parameter of the \item command.

In the list below, the \makelabel command and the two geometrical parameters (\labelwidth and \leftmargin) are redefined..

\newcommand{\entrylabel}[1]{%
\mbox{\textsf{#1:}}\hfil}
\newenvironment{entry}%
{\begin{list}{}{%
\renewcommand{\makelabel}{\entrylabel}%
\setlength{\labelwidth}{35pt}%
\setlength{\leftmargin}%
{\labelwidth+\labelsep}}}%
{\end{list}}

\begin{entry}
\item[Description]
Returns from a function.  If issued at
top-level, the interpreter simply terminates,
just as if end of input had been reached.
\item[Errors]   None.
\item[Return values]\mbox{}\\
Any arguments in effect
are passed back to the caller.
\end{entry}


{ <:<915>>
Description
Returns from a function. If issued at top-level, the interpreter simply terminates, just as if end of input had been reached.
Errors
None.
Return values

Any arguments in effect are passed back to the caller.

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. Standard LaTeX lets the text of the term continue into the text of the description part. This is normally not desired, and to improve the visual appearance of the list we have started the description part on the next line. A new line was forced by putting an empty box on the same line, followed by \bs\bs' 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. One method for accomplishing this is to change 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 put inside the definition of the Ventry 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.

\newenvironment{Ventry}[1]%
{\begin{list}{}{%
\renewcommand{\makelabel}[1]{%
\textsf{##1:}\hfil}%
\settowidth{\labelwidth}{\textsf{#1:}}%
\setlength{\leftmargin}{%
\labelwidth+\labelsep}}}%
{\end{list}}


Description
Returns from a function. If issued at top-level, the interpreter simply terminates, just as if end of input had been reached.
Errors
None.
Return values
Any arguments in effect are passed back to the caller.

However, 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. If it 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 UNIX manuals.

\newlength{\Mylen}
\newcommand{\Lentrylabel}[1]{%
\settowidth{\Mylen}{\textsf{#1:}}%
\ifthenelse{\lengthtest{\Mylen > \labelwidth}}%
{\parbox[b]{\labelwidth}%        term > labelwidth
{\makebox[0pt][l]{\textsf{#1:}}\\ }}%
{\textsf{#1:}}%                  term < labelwidth
\hfil\relax}
\newenvironment{Lentry}
{\renewcommand{\entrylabel}{\Lentrylabel}%
\begin{entry}}
{\end{entry}}

\begin{Lentry}
\item[Description]
Returns from a function.  If issued at top-level, the interpreter
simply terminates, just as if end of input had been reached.
\item[Errors]   None.
\item[Return values] Any arguments in effect are passed back to the caller.
\end{Lentry}


As the last line in this example shows, the Lentry environment is defined in terms of the entry environment. The label generating command \entrylabel is now replaced by the \Lentrylabel command. The latter first sets the length variable \Mylen equal to the width of the label. It then compares that length with \labelwidth. If the label is smaller 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 (forcing a new line) so that the description term starts one line lower.

{<:<940>>{ > <:
<: <941>>

{ <:<915>>
Description
Returns from a function. If issued at top-level, the interpreter simply terminates, just as if end of input had been reached.
Errors
None.
Return values
Any arguments in effect are passed back to the caller.

Yet another possibility is to allow multiline labels. We, once more, use the entry environment as a basis, but this time the command \Mentrylabel replaces the \entrylabel command. The idea here is that wide 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 \Lcs{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 aligned and left adjusted into a box that is itself placed inside a box with a depth of 1 em and no height. In this way, LaTeX does not realize that the material extends below the first line.

\newcommand{\Mentrylabel}[1]%
{\raisebox{0pt}[1em][0pt]{%
\makebox[\labelwidth][l]%
{\parbox[t]{\labelwidth}{%
\hspace{0pt}\textsf{#1:}}}}}
\newenvironment{Mentry}%
{\renewcommand{\entrylabel}{%
\Mentrylabel}\begin{entry}}%
{\end{entry}}
\begin{Mentry}
\item[Description]
Returns from a function.  If issued at
top-level, the interpreter simply terminates,
just as if end of input had been reached.
\item[Errors]   None.
\item[Return\\ values] Any arguments in effect
are passed back to the caller.
\end{Mentry}


{<:<958>>{0pt[1em][0pt] <:<959>>

{ <:<915>>
Description
Returns from a function. If issued at top-level, the interpreter simply terminates, just as if end of input had been reached.
Errors
None.
Return
values
Any arguments in effect are passed back to the caller.

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 declared to consist of the word NOTES in small caps, followed by the value of the notes counter using its representation as an arabic number followed by a dot.

\newcounter{notes}
\newenvironment{Notes}
{\begin{list}{{\textsc{Note}}
\arabic{notes}. }{\usecounter{notes}%
\setlength{\labelsep}{0pt}%
\setlength{\leftmargin}{0pt}%
\setlength{\labelwidth}{0pt}%
\setlength{\listparindent}{0pt}}}%
{\end{list}}

\begin{Notes}
\item This is the text of the first note item.
Some more text for the first note item.
\item This is the text of the second note item.
Some more text for the second note item.
\end{Notes}
`

• This is the text of the first note item. Some more text for the first note item.
• This is the text of the second note item. Some more text for the second note item.

Next: Text Processing and Up: Customizing LaTeX lists Previous: Modifying LaTeX Lists

Janne Saarela
Tue May 16 13:43:26 METDST 1995