SysIII/usr/src/man/docs/mm_man/s05list

.tr ``
.H 1 LISTS
This section describes
many different kinds of lists:
automatically-numbered and alphabetized lists,
bullet lists,
dash lists,
lists with arbitrary marks,
and lists starting with arbitrary strings,
e.g., with terms or phrases to be defined.
.H 2 "Basic Approach"
In order to avoid repetitive typing of arguments to describe the
appearance of items in a list,
\*(PM
provides a convenient way to specify
lists.
All lists are composed of the following parts:
.BL
.LI
A
.I
list-initialization
.R
macro that controls
the appearance of the list:
line spacing, indentation, marking with special symbols,
and numbering or alphabetizing.
.LI
One or more 
.I
List Item
.R
(\f3.\fPLI) macros, each followed by the actual text 
of the corresponding list item.
.LI
The
.I
List End
.R
(\f3.\fPLE) macro that
terminates the list and restores the previous indentation.
.LE
.P
Lists may be nested up to five levels.
The list-initialization macro saves the previous list status
(indentation, marking style, etc.);
the \f3.\fPLE macro restores it.
.P
With this approach,
the format of a list is specified only once
at the beginning of that list.
In addition, by building on the existing structure,
users may create their own customized sets of list macros with relatively
little effort {5.4, Appendix\ A}.
.H 2 "Sample Nested Lists"
The input for several lists and the corresponding output
are shown below.
The \f3.\fPAL and \f3.\fPDL macro calls {5.3.3} contained therein are examples
of the
.I "list-initialization"
macros.
This example 
will help us to explain the material in the
following sections.
Input text:
.Es 1
\&\f3.\fPAL A
\&\f3.\fPLI
\&This is an alphabetized item.
\&This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
\&\f3.\fPAL
\&\f3.\fPLI
\&This is a numbered item.
\&This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
\&\f3.\fPDL
\&\f3.\fPLI
\&This is a dash item.
\&This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
\&\f3.\fPLI + 1
\&This is a dash item with a \`\^\`plus\'\^\' as prefix.
\&This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
\&\f3.\fPLE
\&\f3.\fPLI
\&This is numbered item 2.
\&\f3.\fPLE
\&\f3.\fPLI
\&This is another alphabetized item, B.
\&This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
\&\f3.\fPLE
\&\f3.\fPP
This paragraph appears at the left margin.
.Ee 1
.DS 0 1
Output:
.AL A
.LI
This is an alphabetized item.
This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
.AL 1
.LI
This is a numbered item.
This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
.DL
.LI
This is a dash item.
This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
.LI + 1
This is a dash item with a ``plus'' as prefix.
This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
.LE
.LI
This is numbered item 2.
.LE
.LI
This is another alphabetized item, B.
This text shows the alignment of the second line of the item.
The quick brown fox jumped over the lazy dog's back.
.LE
.P
This paragraph appears at the left margin.
.DE
.H 2 "Basic List Macros"
Because all lists share the same overall structure
except for the list-initialization macro,
we first discuss the macros common to all lists.
Each list-initialization macro is covered in {5.3.3}.
.H 3 "List Item"
.Es1
\&\f3.\fPLI [mark] [1]
one or more lines of text that make up the list item.
.Ee
.P
The \f3.\fPLI macro is used with all lists.
It normally causes the output of a single
blank line (\*(12) before its item, although this may be suppressed.
If no arguments are given,
it labels its item with the
.I "current mark" ,
which is
specified by the most recent list-initialization macro.
If a single argument is given to \f3.\fPLI, that argument is output
.I "instead of"
the current mark.
If two arguments are given, the first argument becomes a 
.I prefix
to the
current mark,
thus allowing the user to emphasize one or more items in a list.
One unpaddable space is inserted between the prefix and the mark.
For example:
.Es 1
\&\f3.\fPBL 6
\&\f3.\fPLI
\&This is a simple bullet item.
\&\f3.\fPLI +
\&This replaces the bullet with a \`\^\`plus\f3.\fP\'\^\'
\&\f3.\fPLI + 1
\&But this uses \`\^\`plus\'\^\' as prefix to the bullet.
\&\f3.\fPLE
.Ee 1
yields:
.BL 6
.LI
This is a simple bullet item.
.LI +
This replaces the bullet with a ``plus.''
.LI + 1
But this uses ``plus'' as prefix to the bullet.
.LE
.P
.VL 4\"WARNING
.LI "\ \(rh"
.I
The
.R
mark
.I
must not contain ordinary (paddable) spaces,
because alignment of items will be lost if the right margin is justified
.R
{3.3}.
.LE
.P
If the
.I "current mark"
(in the 
.I "current list" )
is a null string,
and the
first
argument of \f3.\fPLI is omitted or null,
the resulting effect is that of a
.I "hanging indent" ,
i.e., the first line of the following text is ``outdented,''
starting at the same place where the
.I mark
would have started {5.3.3.6}.
.H 3 "List End"
\&
.br
.Es1
\&\f3.\fPLE [1]
.Ee
.P
List End restores the state of the
list
back to that existing just before the most recent
list-initialization macro call.
If the optional argument is given,
the \f3.\fPLE outputs a blank line (\*(12).
This option should generally be used
only when the \f3.\fPLE is followed by running text,
but not when followed by a macro that produces blank lines of its own,
such as \f3.\fPP, \f3.\fPH, or \f3.\fPLI.
.P
\&\f3.\fPH and \f3.\fPHU automatically clear all list information,
so one may legally omit the \f3.\fPLE(s)
that would normally occur just before either of these macros.
Such a practice is 
.I not
recommended, however, because errors will
occur if the list text is separated from the heading
at some later time
(e.g., by insertion of text).
.H 3 "List Initialization Macros"
The following are
the various
list-initialization
macros.
They are actually implemented as calls to the more basic
\&\f3.\fPLB macro {5.4}.
.H 4 "Automatically-Numbered or Alphabetized Lists"
\&
.br
.Es1
\&\f3.\fPAL [type] [text-indent] [1]
.Ee
.P
The \f3.\fPAL macro is used to begin sequentially-numbered or
alphabetized lists.
If there are no arguments, the list is numbered,
and text is indented
.I Li ,
initially 6 (5)\*F
.FS
Values that specify indentation must be
.I unscaled
and are treated as ``character positions,''
i.e., as the number of
.I ens.
.FE
spaces from the indent in force when the \f3.\fPAL is called,
thus leaving room for a space,
two digits, a period, and two spaces before the text.
.P
Spacing at the beginning of the list and
between the items can be suppressed by setting
the
.I Ls
(list space) register.
.I Ls
is set to the 
innermost list level for which spacing
.I is
done.
For example:
.Es 1
\&\f3.\fPnr Ls  0
.Ee 1
specifies that
no spacing will occur around
.I any
list items.
The default value for
.I Ls
is 6
(which is the
.I maximum 
list nesting level).
.P
The
.I type
argument may be given to obtain a different type of sequencing,
and its value should indicate the first element in the
sequence desired,
i.e., it must be 1, A, a, I, or i {4.2.2.5}.\*F\ 
.FS
Note that the ``0001'' format is
.I not
permitted.
.FE
If
.I type
is omitted or null, then ``1'' is assumed.
If
.I text-indent
is non-null, it is used as the number of spaces from
the current indent to the text,
i.e., it is used instead of
.I Li
for this list only.
If
.I text-indent
is null,
then the value of 
.I Li
will be used.
.P
If the third argument is given, a blank
line (\*(12) will 
.I not
separate the items in the list.
A blank line (\*(12) will occur before the first item, however.
.H 4 "Bullet List"
\&
.br
.Es1
\&\f3.\fPBL [text-indent] [1]
.Ee
.P
\&\f3.\fPBL begins a bullet list,
in which each item is marked by a bullet (\*(BU) followed by one space.
If
.I text-indent
is non-null, it overrides the default 
indentation\*(EMthe amount of paragraph indentation as given in the register
.I Pi
{4.1}.\*F\ 
.FS
So that, in the default case, the text of bullet and dash lists
lines up with the first line of indented paragraphs.
.FE
.P
If a second argument is specified, no blank lines will separate
the items in the list.
.H 4 "Dash List"
\&
.Es1
\&\f3.\fPDL [text-indent] [1]
.Ee
.P
\&\f3.\fPDL is identical to \f3.\fPBL,
except that a dash is used instead of a bullet.
.H 4 "Marked List"
\&
.Es1
\&\f3.\fPML mark [text-indent] [1]
.Ee
.P
\&\f3.\fPML is much like \f3.\fPBL and \f3.\fPDL, but expects the user to specify an arbitrary
mark, which may consist of more than a single character.
Text is indented
.I text-indent
spaces if the second argument is not null;
otherwise, the text is indented one more space than the width of
.I mark .
If the third argument is specified, no blank lines 
will separate the items in the list.
.VL 4\"WARNING
.LI "\ \(rh"
.I
The
.R
mark
.I
must not contain ordinary (paddable) spaces,
because alignment of items will be lost if the right margin is justified
.R
{3.3}.
.LE
.H 4 "Reference List
\&
.Es1
\&\f3.\fPRL [text-indent] [1]
.Ee
.P
A \f3.\fPRL call begins an automatically-numbered list in
which the numbers are enclosed by
square brackets (\^[\|]\^).
.I Text-indent
may be supplied, as for \f3.\fPAL.
If omitted or null, it is assumed to be 6,
a convenient value for lists numbered up to 99.
If the second argument is specified, no 
blank lines will separate the items in the list.
.H 4 "Variable-Item List"
\&
.Es1
\&\f3.\fPVL text-indent [mark-indent] [1]
.Ee
.P
When a list begins with a \f3.\fPVL, there is effectively no
.I "current mark;"
it is expected that each \f3.\fPLI will provide its own mark.
This form is typically used to display
definitions of terms or phrases.
.I Mark-indent
gives the number of spaces from the current indent to the beginning of the
.I mark, 
and it defaults to 0 if omitted or null.
.I  Text-indent
gives the distance from the current indent to the beginning of the text.
If the third argument is specified, no 
blank lines will separate the items in the list.
Here is an example of \f3.\fPVL usage:
\&
.br
.tr ~~
.Es 1
\&\f3.\fPtr ~
\&\f3.\fPVL 20 2
\&\f3.\fPLI mark~1
\&Here is a description of mark 1\f3;\fP
\&\`\^\`mark 1\'\^\' of the \f3.\fPLI line contains a tilde translated to an unpaddable space in order
\&to avoid extra spaces between
\&\`\^\`mark\'\^\' and \`\^\`1\'\^\' {3.3}.
\&\f3.\fPLI second~mark
\&This is the second mark, also using a tilde translated to an unpaddable space.
\&\f3.\fPLI third~mark~longer~than~indent\f3:\fP
\&This item shows the effect of a long mark\f3;\fP one space separates the mark
\&from the text.
\&\f3.\fPLI ~
\&This item effectively has no mark because the
tilde following the \f3.\fPLI is translated into a space.
\&\f3.\fPLE
.Ee 1
yields:
.tr ~
.VL 20 2
.LI mark~1
Here is a description of mark 1;
``mark 1'' of the .LI line contains a tilde translated to an unpaddable
space in order
\&to avoid extra spaces between
``mark'' and ``1'' {3.3}.
.LI second~mark
This is the second mark, also using a tilde translated to an unpaddable space.
.LI third~mark~longer~than~indent:
This item shows the effect of a long mark; one space separates the mark
from the text.
.LI ~
This item effectively has no mark because the
tilde following the \f3.\fPLI is translated into a space.
.LE
.P
The tilde argument on the last \f3.\fPLI above is required; otherwise a
.I "hanging indent"
would have been produced.
A
.I "hanging indent"
is produced by using \f3.\fPVL
and calling \f3.\fPLI with no arguments or with a null first argument.
For example:
.Es 1
\&\f3.\fPVL 10
\&\f3.\fPLI
Here is some text to show a hanging indent.
The first line of text is at the left margin.
The second is indented 10 spaces.
\&\f3.\fPLE
.Ee 1
yields:
.DS 0 1
.VL 10
.LI
Here is some text to show a hanging indent.
The first line of text is at the left margin.
The second is indented 10 spaces.
.LE
.DE
.tr ~~
.P
.VL 4\"WARNING
.LI "\ \(rh"
.I
The
.R
mark
.I
must not contain ordinary (paddable) spaces,
because alignment of items will be lost if the right margin is justified
.R
{3.3}.
.LE
.H 2 "List-Begin Macro and Customized Lists \*(BU
.Es1
\&\f3.\fPLB text-indent mark-indent pad type [mark] [LI-space] [LB-space]
.Ee
.P
The
list-initialization
macros described above suffice for almost all cases.
However, if necessary, one may
obtain more control over the layout of
lists by using the basic list-begin macro \f3.\fPLB,
which is also used by all the other list-initialization macros.
Its arguments are as follows:
.P
.I Text-indent
gives the number of spaces that the text is to be indented from the
current indent.
Normally, this value is taken from the register
.I Li
for automatic lists
and from the register
.I Pi
for bullet and dash lists.
.P
The combination of
.I mark-indent
and 
.I pad
determines the placement of the mark.
The mark is placed within 
an area (called
.I "mark area" \^)
that starts
.I mark-indent
spaces to the right of the current indent, and ends where the text begins
.if t .ne4
(i.e., 
ends
.I text-indent
spaces to the right of the current indent).\*F\ 
.FS
The
.I mark-indent
argument
is typically 0.
.FE
Within the mark area, the mark is 
.I left-justified
if
.I pad
is 0.
If
.I pad
is greater than 0,
say
.I n ,
then
.I n
blanks are appended to the mark;
the
.I mark-indent
value is ignored.
The resulting string immediately precedes the text.
That is, the
mark is effectively
.I right-justified
.I pad
spaces immediately to the left of the text.
.P 
.I Type
and
.I mark
interact to control the type of marking used.
If
.I type
is 0,
simple marking is performed using the mark character(s) found in the
.I mark
argument.
If
.I type
is greater than 0, automatic numbering or alphabetizing is done,
and
.I mark
is then interpreted as the first item in the sequence to be used for
numbering or alphabetizing,
i.e., it is chosen from the set (1, A, a, I, i) as in {5.3.3.1}.
That is:
.! tbl tbl-5.4.a
.P
Each non-zero value of
.I type
from 1 to 6 selects a different way of displaying the items.
The following table shows the output appearance for
each value of
.I type:
.! tbl tbl-5.4.b
where
.I x
is the generated number or letter.
.VL 4\"WARNING
.LI "\ \(rh"
.I
The
.R
mark
.I
must not contain ordinary (paddable) spaces,
because alignment of items will be lost if the right margin is justified
.R
{3.3}.
.LE
.P
.I LI-space
gives the number of blank lines 
(halves of a vertical space)
that should be output by each \f3.\fPLI
macro in the list.
If omitted,
.I LI-space
defaults to 1;
the value 0 can be used to obtain compact lists.
If
.I LI-space
is greater than 0,
the \f3.\fPLI macro issues a
\&\f3.\fPne
request for two lines
just before printing the mark.
.P
.I LB-space,
the number of blank lines 
(\*(12)
to be output by \f3.\fPLB
itself,
defaults to 0 if omitted.
.P
There are three reasonable combinations of
.I LI-space
and
.I LB-space .
The normal case is to set
.I LI-space
to 1 and
.I LB-space
to 0, yielding one blank line 
.I before
each item in the list;
such a list is usually terminated with a ``\f3.\fPLE\|\ 1''
to end the list with a blank line.
In the second case,
for a more compact list, set
.I LI-space
to 0 and
.I LB-space
to 1, and, again, use ``\f3.\fPLE\|\ 1'' at the end of the list.
The result is a list with one blank line before and after it.
If you set both
.I LI-space
and
.I LB-space
to 0, and use ``\f3.\fPLE'' to end the list,
a list without
.I any
blank lines will result.
.P
Appendix A illustrates how the user can build upon the supplied list
macros to obtain other kinds of lists.