Check-in [9007d5e6a1]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Convert man markup to mdoc; formatting not perfect yet
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:9007d5e6a10d6f9a9e2e733c15b9b037ec73f96f
User & Date: darrenbane 2014-02-07 22:53:37
Context
2014-02-12
23:27
Fix build on clean FreeBSD machine. Still problem with installing. check-in: 700f942023 user: dbane tags: trunk
2014-02-07
22:53
Convert man markup to mdoc; formatting not perfect yet check-in: 9007d5e6a1 user: darrenbane tags: trunk
16:28
Forgot to include own modules header file check-in: 63f34fd1ce user: darrenbane tags: trunk
Changes

Changes to doc/lbl.1.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

91
92
93
94
95
96
97
98
99
100
101


102
103
104
105
106
107

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

126
127

128
129
130

131
132

133
134

135
136

137
138
139


140
141
142
143

144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

160
161

162
163
164
165
166
167
168
169
170

171

172
173
174
175
176
177
178
179
180

181
182
183

184
185
186

187
188
189





.\" (C) C.D.F. Miller, Heriot-Watt University, March 1984
.\"
.TH LBL 1 Local
.ad
.fi
.SH NAME
lbl \- preprocess symbolic labels for troff(1) text
.SH SYNOPSIS
.B lbl
[
.B -d\c
delim
] [
.B -m\c
macro
] [
.B -l
] [
.B -s
] [ file ... ]
.SH DESCRIPTION
.I Lbl
is a preprocessor for
.I 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
.I label-type .
Within each label-type, objects are referred to by symbolic names known
as
.I 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
.I Lbl
reads as input the concatenation of all specified
.I file
arguments (interpreting ``-'' to mean the standard input);
if no
.I file
argument is given,
.I lbl
reads the standard input.
The input consists of arbitrary text (normally input for
.I troff (1),
.I eqn (1),
and the rest of that family) interspersed with
.I label-definitions
and
.I label-references ,
together with a few other sorts of definition described below.
.PP
\fILabel Definitions:\fR
a label-definition
defines the value of a symbolic label.
All such definitions are introduced by a line beginning with
a special
.I troff
macro; the default macro is
.B \&.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
.B \&.NH
in the
.I ms (6)
package,
.B \&.H
in
.I mm
and
.B \&.sh
in
.I 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.
.PP
There are several other uses of the definition-macro:

.IP "\&.L= delimiter off"
.br
inhibits all subsequent translation of label-references;
.IP "\&.L= delimiter \fIchar\fR"
.br
resets the delimiter introducing label-references to
.I char
(see below);
.IP "\&.L= format \fIlabel-type pattern\fR"
resets the printing format for a label reference (see below);
.IP "\&.L= last \fIlabel-type count ...\fR"


resets the counts for \fIlabel-type\fR 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.
.LP

All label-definition, etc., lines are copied unchanged to the output.
.PP
\fILabel References\fR:
a label-reference is introduced and terminated by a
.I 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).
.PP
\fIPrint Formats\fR:
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
.IP %1

print in arabic numerals, no non-significant leading zeros;
.IP %0

print as for ``%1'', but subtracting 1 so that counts start from 0 rather than
1.
.IP %i

print in lower-case roman numerals;
.IP %I

print in upper-case roman;
.IP %a

print as a lower-case letter (starting at ``a'');
.IP %A

print as an upper-case letter.
``%'' followed by any other character prints as that character.
.LP


The default format is to print all levels in arabic, separated by periods
(i.e. "%1.%1.%1.%1\ ...").
.PP
\fICommand Line Options\fR:

.IP -d\fIdelim\fR
.br
.I delim
is a single character to be used in place of ``@''
as the label-reference delimiter.
.IP -m\fImacro\fR
.br
.I macro
is a 2-character macro-name to be used in place of ``.L='' as the
label-definition macro.
.IP -l
causes a listing of all label-definitions to be written to the standard
error stream.
.IP -s
suppresses all output except error messages and the listing generated by
the \fI-l\fR option, which is automatically turned on.

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

.SH BUGS
With the
.I -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

/tmp/lbl* - temporary storage
.SH "SEE ALSO"
troff(1), nroff(1), eqn(1), refer(1), tbl(1)







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<
<
<
<
<





|


|


|






|
|

|


|

|


|
|

|

|

|
|
|



|

|






|

|

|

|

|

|


|

>
|
<

|
<

|

|

|
>
>
|




|
>

<
|
|
|




<
|
|





|
>

<
>


<
>

<
>

<
>

<
>


<
>
>


<
|
>
|
<
|


|
<
|


|


|


>
|
|
>
|
|
|
|
|
|
|
|
|
>
|
>
|
|
|
|
|
|
|
|
|
>
|

<
>


|
>
|
|
<
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19





20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

88
89

90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

106
107
108
109
110
111
112

113
114
115
116
117
118
119
120
121
122

123
124
125

126
127

128
129

130
131

132
133
134

135
136
137
138

139
140
141

142
143
144
145

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182

183
184
185
186
187
188
189

190
191
192
193
194
.\" (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