lbl/doc/lbl.ms

.\" (C) C.D.F. Miller, Heriot-Watt University, March 1984
.\"
.\" This file should be formatted by
.\"	lbl lbl | nroff -ms
.L= delimiter #
.ND
.TL
LBL - Symbolic Labels in Text Documents
.NH 1
Introduction
.L= sec 1 intro
.PP
.I lbl
is a pre-processor for
.I troff
and
.I nroff
which allows Sections, Figures, Tables, etc., to be referred to by
symbolic names rather than by absolute number.
It will handle forward references as well as backward ones.
.PP
Uses of a label in the text are indicated by a delimiter character (default '@',
but resettable), followed by a
.I type
name (e.g. "TABLE", "EQN", etc.), followed by the label itself
(e.g. "Profits-1983").
Each such occurrence is replaced by a reference number; the default
style of numbering is a sequence of period-separated arabic numbers
(e.g. 2.4.1) but this is resettable.
Finally, another delimiter is required to close the reference
(cf. the use of delimiters in
.I eqn
for in-line equations).
.LP
Examples:
.DS
For full details refer to Table @TABLE Profits-1983@.
As we saw in Chapter @chap intro@, ...
Figure @fig wing-profile@ shows the airflow patterns ...
.DE
.PP
Labels may be defined at any point in the text.
The definition looks like a
.I troff
macro, and the definition line is retained in the original text.
By default, the macro used is ".L=", but this can be reset.
The macro takes 3 arguments: a type-name, a level-number, and
a label-name.
.PP
The type-name corresponds to that used to signal a label occurrence in
the text.
There is no restriction on the choice of name; any sequence of
non-blank characters may be used.
Upper- and lower-case letters
.I are
distinguished.
.PP
The level-number corresponds to the header-level numbers used
by the .NH macro in
.I ms ,
the .sh macro in
.I me ,
etc.
The index at the given level is incremented by 1, and all higher indexes
set to 0.
Initially, all indexes are set to 0 by default, but other starting values
may be chosen.
There is an implementation-defined restriction on the number
of levels of index (currently 20);
it is not anticipated that this will lead to problems.
.PP
The label may be any sequence of non-blank characters;
the same label may be used in more than one type.
Furthermore, the special label-name ``*'' can be used to increment the
appropriate level-counter without defining a label at all;
this is useful, for example, when all tables, figures, etc., in a section
take their initial index from the section number: two ways of doing this
would be:
.DS L
a.
    .L= section 1 this-section
    .L= last table 0
    .L= last figure 0
    ...
    ... refer to table @section this-section@.@table profits@ ...
    ... see figure @section this-section@.@figure structure@ ...
    ...
    .L= table 1 profits
    ...
    .L= figure 1 structure
    ...

(see section #sec directives# for the use of
``.L=\ last\ ...'')

b.
    .L= section 1 this-section
    .L= table 1 *
    .L= figure 1 *
    ...
    ... refer to table @table profits@ ...
    ... see figure @figure structure@ ...
    ...
    .L= table 2 profits
    ...
    .L= figure 2 structure
    ...
.DE
It is largely a matter of taste which technique is used;
the former is more long-winded, but avoids the need to remember to
keep the tables and figures in step every time the section is
updated.
Yet a third possibility (similar to the first) would be:
.DS L
c.
    .L= section 1 this-section
    .ds Sc "@section this-section@
    .L= last table 0
    ...
    ... refer to table \*(Sc.@table profits@
    etc.
.DE
making use of the string-definition facility within
.I nroff .
.PP
It is important to be aware that all processing on labels is done
before
.I troff
processes the text; attempts to build label-references by
using macros or
.I troff
strings registers will almost certainly not work as expected.
.NH 1
Command Line Options
.L= sec 1 options
.PP
Options to
.I lbl
are set in the command line, which has the form
.DS
lbl [ -d\fIdelim\fR ] [ -m\fImacro\fR ] [ -l ] [ -s ]
.DE
.IP -d
.I \fIdelim\fR
is the character used to delimit in-line occurrences of label
references (default ``@'');
.IP -m
.I macro
is the 2-character name of
a
.I troff
macro which introduces label definitions, etc. (default ``L='');
.IP -l
causes a listing of label-definitions to be written to the standard
error stream.
Each label-type is listed, together with its print format, followed by
a line for each label of that type, showing label-name, file and line
where it is defined, and value;
.IP -s
causes the generation of the
.I troff
input file to be suppressed;
setting
.I -s 
automatically also sets
.I -l .
.NH 1
Control directives
.L= sec 1 directives
.PP
In addition to defining labels, the \fB.L=\fR macro (or its substitute)
can be used for several other purposes.
These are all indicated by commands of the form
.DS
\&.L= \fIcommand\fR \fIargument\fR ...
.DE
where the \fIcommand\fRs are reserved words which may not be used as
type-names.
These commands allow control over the initialisation of label values,
the print format of labels, and thelabel reference delimiter.
.IP "\&.L= delimiter off"
.br
turns off interpretation of the delimiter character altogether;
subsequent text is copied literally until another \fIdelimiter\fR
command is encountered;
.IP "\&.L= delimiter \fIcharacter\fR"
.br
resets the delimiter in subsequent text to the given character;
.IP "\&.L= format \fItypename\fR \fIstring\fR"
.br
sets the print format for labels of the given type - see section
#sec formats#;
.IP "\&.L= last \fItypename\fR \fIcount1\fR \fIcount2\fR ..."
.br
resets the counters for \fItypename\fR as though the last label
generated had been \fIcount1.count2...\fR (with all omitted counts
taken as 0).
.NH 2
Print formats
.L= sec 2 formats
.PP
The default print format for a label is as a sequence of period-separated
arabic numerals.
However, it is also possible to specify alphabetic or roman labels,
or a mixture, and to have separators other than a period.
This is governed by the format given in a ``.LE\ format'' command.
.PP
Such a format contains escape sequences (flagged by a ``%'' character)
and literal text.
The text is copied until an escape sequence is encountered; such a
sequence is replaced by the index for the next level of the label
value, printed in one of the following formats:
.IP %1
Arabic numerals (without non-significant leading zeros);
.IP %0
As %1, but offset by 1 so that the first value printed will be 0 rather
than 1;
.IP %a
Lower-case alphabetics, starting at ``a''; ``z'' is followed by ``aa'',
etc.;
.IP %A
Upper-case alphabetics;
.IP %i
Lower-case roman numerals (with some odd choices for large numbers,
consistent with the roman numerals printed by
.I troff ).
.IP %I
Upper-case roman numerals.
.LP
A ``%'' followed by any other character (in particular another ``%'') prints
as that character.
.NH 1
Limits
.L= sec 1 limits
.PP
.I Lbl
imposes no limit on the size of text to be processed, but (like
.I refer )
needs to act on a text as a whole, rather than processing individual
files.
The limit on the number of levels of header is unlikely to prove a problem.
The number of labels which may be used is limited only by the amount
of memory available to a process; even on a small machine it is
possible to handle a few hundred label definitions.
.NH 1
Further Examples
.L= sec 1 examples
.PP
The copying of the definition macros makes it possible to use them
as
.I troff
macros, as in the following example:
.DS
\&.de L=
\&.ie '\e\e$1'sec' .NH \e\e$2
\&.el .ie '\e\e$1'table' .if !'\e\e$3'*' \e{
\&.DS C
\&Table '\e\e$3' about here
\&.DE
\&\e}
\&.el .if '\e\e$1'fig' .if !'\e\e$3'*' \e{
\&.DS C
\&Figure '\e\e$3' about here
\&.DE
\&\e}
\&..
\&.nr LL 5i
\&.ND
\&.TL
\&Example of LBL
\&.L= sec 1 intro
\&Introduction
\&.L= table 1 *
\&.PP
\&We begin with a small table (Table @table opening@).
\&.L= table 2 opening
\&and consider things in more detail in Section
\&@sec cont@.
\&.L= sec 1 cont
\&Continuation
\&.L= table 1 *
\&.PP
\&In this continuation we refer back to Section
\&@sec intro@, which contained
\&Table @table opening@, and present more detailed
\&information in Table
\&@table detail@.
\&.L= table 2 detail
\&.L= sec 2 subcont
\&Sub-continuation
\&.PP
\&In which we further refine things, as shown in
\&Table @table mega-detail@ below.
\&.L= table 2 mega-detail
.DE
In the above, the ``.L=\ sec'' macros automatically generate the
numbered headings by expanding to the \fIms\fR ``.NH'' macros,
while the ``table'' definitions cause the insertion of figures
such as
.DS C
Table 'detail' about here
.DE
The above example thus produces the following:
.DS
                  Example of LBL





\fI1.  Introduction\fR

     We begin with a small table (Table 1.1).


            Table 'opening' about here

 and consider things in more detail in Section 2.

\fI2.  Continuation\fR

     In this continuation we refer back to Section
1,  which  contained  Table  1.1, and present more
detailed information in Table 2.1.


            Table 'detail' about here



\fI2.1.  Sub-continuation\fR

     In which we further refine things,  as  shown
in Table 2.2 below.


          Table 'mega-detail' about here
.DE
.PP
The alphabetic formats may be useful for such things as appendices,
e.g.
.DS
\&.L= format appendix %A
\&.L= appendix 1 trade-marks
\&.SH
\&Appendix @appendix trade-marks@:
\&List of Registered Trade Marks
\&.LP
\&(For the addresses of the proprietors see
\&@appendix props@).
\&  ...
\&.L= appendix 1 props
.DE
which will generate
.DS
\fIAppendix A: List of Registered Trade Marks\fR

(For the addresses of the proprietors see appendix B).
.DE