LBL

NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
BUGS
FILES
SEE ALSO

NAME

lbl − preprocess symbolic labels for troff(1) text

SYNOPSIS

lbl [ -ddelim ] [ -mmacro ] [ -l ] [ -s ] [ file ... ]

DESCRIPTION

Lbl is a preprocessor for 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.

As many independent sequences of labels as required can be maintained; each sequence is given a symbolic name, known as the label-type . Within each label-type, objects are referred to by symbolic names known as 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).

Lbl reads as input the concatenation of all specified file arguments (interpreting ‘‘-’’ to mean the standard input); if no file argument is given, lbl reads the standard input. The input consists of arbitrary text (normally input for troff (1), eqn (1), and the rest of that family) interspersed with label-definitions and label-references , together with a few other sorts of definition described below.

Label Definitions: a label-definition defines the value of a symbolic label. All such definitions are introduced by a line beginning with a special troff macro; the default macro is .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 .NH in the ms (6) package, .H in mm and .sh in me ). 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.

There are several other uses of the definition-macro:

.L= delimiter off

inhibits all subsequent translation of label-references;

.L= delimiter char

resets the delimiter introducing label-references to char (see below);

.L= format label-type pattern

resets the printing format for a label reference (see below);

.L= last label-type count ...

resets the counts for 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.

All label-definition, etc., lines are copied unchanged to the output.

Label References: a label-reference is introduced and terminated by a 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).

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

%1

print in arabic numerals, no non-significant leading zeros;

%0

print as for ‘‘%1’’, but subtracting 1 so that counts start from 0 rather than 1.

%i

print in lower-case roman numerals;

%I

print in upper-case roman;

%a

print as a lower-case letter (starting at ‘‘a’’);

%A

print as an upper-case letter. ‘‘%’’ followed by any other character prints as that character.

The default format is to print all levels in arabic, separated by periods (i.e. "%1.%1.%1.%1 ...").

Command Line Options:

-ddelim

delim is a single character to be used in place of ‘‘@’’ as the label-reference delimiter.

-mmacro

macro is a 2-character macro-name to be used in place of ‘‘.L=’’ as the label-definition macro.

-l

causes a listing of all label-definitions to be written to the standard error stream.

-s

suppresses all output except error messages and the listing generated by the -l option, which is automatically turned on.

EXAMPLE

Input
  .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

Output
  .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

BUGS

With the -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.

FILES

/tmp/lbl* - temporary storage

SEE ALSO

troff(1), nroff(1), eqn(1), refer(1), tbl(1)