lbl/src/lbl.1

.\" (C) C.D.F. Miller, Heriot-Watt University, March 1984
.\"
.Dd $Mdocdate$
.Dt LBL 1
.Os
.Sh NAME
.Nm lbl
.Nd preprocess symbolic labels for troff(1) text
.Sh SYNOPSIS
.Nm lbl
.Op Fl d Ar delim
.Op Fl m Ar macro
.Op Fl l
.Op Fl s
.Op Ar
.Sh DESCRIPTION
.Nm
is a preprocessor for
.Xr troff 1
which constructs serial numbers automatically for tables, equations,
sections, etc., and allows them to be referred to by symbolic names.
It avoids the need for a user to keep track of such numberings, and
to alter all cross-references whenever a labelled
object is introduced or deleted.
.Pp
As many independent sequences of labels as required can be maintained;
each sequence is given a symbolic name, known as the
.Em label-type .
Within each label-type, objects are referred to by symbolic names known
as
.Em labels ;
the same label may be used in several different label-types without problems.
Names for labels and label-types may be arbitrary sequences of alphanumeric
characters.
In addition, the special label-name ``*'' may be used as an anonymous label,
used to increment a level counter without generating a label (e.g. to keep
table numbers in step with the corresponding section numbers).
.Pp
.Nm
reads as input the concatenation of all specified
.Ar file
arguments (interpreting ``-'' to mean the standard input);
if no
.Ar file
argument is given,
.Nm
reads the standard input.
The input consists of arbitrary text (normally input for
.Xr troff 1 ,
.Xr eqn 1 ,
and the rest of that family) interspersed with
.Em label-definitions
and
.Em label-references ,
together with a few other sorts of definition described below.
.Pp
.Ss Label Definitions
A label-definition
defines the value of a symbolic label.
All such definitions are introduced by a line beginning with
a special
.Em troff
macro; the default macro is
.Ic .L=
but this can be overridden in the command line.
The label-definition macro is followed by a label-type, a numeric level,
and a label-name;
a value is given to the label by incrementing the current count for
the label-type at the given level (similar to the generation of
numbered headings by such macros as
.Ic .NH
in the
.Xr groff_ms 7
package,
.Ic .H
in
.Xr groff_mm 7
and
.Ic .sh
in
.Xr groff_me 7 ).
Unless otherwise specified, the first count generated at a given level will
be 1; when a count is incremented, all deeper counts are reset to 0.
.Pp
There are several other uses of the definition-macro:
.Bl -tag -width Ds
.It .L= delimiter off
inhibits all subsequent translation of label-references;
.It .L= delimiter \fIchar\fR
resets the delimiter introducing label-references to
.Em char
(see below);
.It .L= format \fIlabel-type pattern\fR
resets the printing format for a label reference (see below);
.It .L= last \fIlabel-type count ...\fR
resets the counts for
.Em label-type
as though the last label generated
had had the specified counts for its successive levels (missing counts
all being taken as 0).
All counts must be arabic numerals, regardless of the print format being
used for the label-type.
.El
.Pp
All label-definition, etc., lines are copied unchanged to the output.
.Ss Label References
A label-reference is introduced and terminated by a
.Em delimiter
character (default ``@'');
the opening delimiter is followed by a label-type and a label-name;
the entire reference is replaced by the value of the specified label,
printed according to the format specified for the label-type (see below).
.Ss Print Formats
A print format consists of a literal string containing escape-sequences
for which successive values of the level counts of a label are substituted.
The format is copied only as far as the escape sequence for the last level
of the label being printed, and it is an error for there to be too few
escape sequences.
The sequences are
.Bl -tag -width Ds
.It %1
print in arabic numerals, no non-significant leading zeros;
.It %0
print as for ``%1'', but subtracting 1 so that counts start from 0 rather than
1.
.It %i
print in lower-case roman numerals;
.It \&%I
print in upper-case roman;
.It %a
print as a lower-case letter (starting at ``a'');
.It \&%A
print as an upper-case letter.
``%'' followed by any other character prints as that character.
.El
.Pp
The default format is to print all levels in arabic, separated by periods
(i.e. "%1.%1.%1.%1\ ...").
.Ss Command Line Options
.Bl -tag -width Ds
.It -d\fIdelim\fR
.Em delim
is a single character to be used in place of ``@''
as the label-reference delimiter.
.It -m\fImacro\fR
.Em macro
is a 2-character macro-name to be used in place of ``.L='' as the
label-definition macro.
.It -l
causes a listing of all label-definitions to be written to the standard
error stream.
.It -s
suppresses all output except error messages and the listing generated by
the \fI-l\fR option, which is automatically turned on.
.El
.Sh EXAMPLE
Input
.Bd -literal -offset indent -compact
\&.L= sec 1 intro
\&.L= format sec %A.%1.%1.%1.%1
\&.L= last table 3 1
This is Section @sec intro@; it is followed by Section
@sec next@ which contains Section @sec subsection@.
\&.L= table 2 only.
The only table used is Table @table only@.
\&.L= sec 1 next
\&.L= sec 2 subsection
.Ed
Output
.Bd -literal -offset indent -compact
\&.L= sec 1 intro
\&.L= format sec %A.%1.%1.%1.%1
\&.L= last table 3 1
This is Section A; it is followed by Section
B which contains Section B.1.
\&.L= table 2 only.
The only table used is Table 3.2.
\&.L= sec 1 next
\&.L= sec 2 subsection
.Ed
.Sh BUGS
With the
.Fl s
option, errors such as reference to an undefined label, which can only
be detected on a second scan of the input, are not reported.
.Sh FILES
.Pa /tmp/lbl*
- temporary storage
.Sh SEE ALSO
.Xr troff 1 ,
.Xr nroff 1 ,
.Xr eqn 1 ,
.Xr refer 1 ,
.Xr tbl 1