Annotation of src/usr.bin/nl/nl.1, Revision 1.3
1.3 ! jca 1: .\" $OpenBSD: nl.1,v 1.2 2013/09/08 20:23:34 jmc Exp $
! 2: .\" $NetBSD: nl.1,v 1.14 2013/09/09 09:02:25 wiz Exp $
1.1 jca 3: .\"
4: .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
5: .\" All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to The NetBSD Foundation
8: .\" by Klaus Klein.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29: .\" POSSIBILITY OF SUCH DAMAGE.
30: .\"
1.2 jmc 31: .Dd $Mdocdate: September 8 2013 $
1.1 jca 32: .Dt NL 1
33: .Os
34: .Sh NAME
35: .Nm nl
36: .Nd line numbering filter
37: .Sh SYNOPSIS
38: .Nm
39: .Op Fl p
40: .Op Fl b Ar type
41: .Op Fl d Ar delim
42: .Op Fl f Ar type
43: .Op Fl h Ar type
44: .Op Fl i Ar incr
45: .Op Fl l Ar num
46: .Op Fl n Ar format
47: .Op Fl s Ar sep
48: .Op Fl v Ar startnum
49: .Op Fl w Ar width
50: .Op Ar file
51: .Sh DESCRIPTION
52: The
53: .Nm
54: utility reads lines from the named
1.3 ! jca 55: .Ar file
! 56: or the standard input if the
! 57: .Ar file
! 58: argument is omitted,
1.2 jmc 59: applies a configurable line numbering filter operation,
60: and writes the result to the standard output.
1.1 jca 61: .Pp
62: The
63: .Nm
64: utility treats the text it reads in terms of logical pages.
65: Unless specified otherwise, line numbering is reset at the start of each
66: logical page.
67: A logical page consists of a header, a body and a footer section; empty
68: sections are valid.
69: Different line numbering options are independently available for header,
70: body and footer sections.
71: .Pp
72: The starts of logical page sections are signaled by input lines containing
73: nothing but one of the following sequences of delimiter characters:
1.2 jmc 74: .Bl -column "\e:\e:\e: " "header " -offset indent
75: .It Em "Line" Ta Em "Start of"
1.1 jca 76: .It \e:\e:\e: header
77: .It \e:\e: body
78: .It \e: footer
79: .El
80: .Pp
81: If the input does not contain any logical page section signaling directives,
82: the text being read is assumed to consist of a single logical page body.
83: .Pp
84: The following options are available:
85: .Bl -tag -width indent
86: .It Fl b Ar type
87: Specify the logical page body lines to be numbered.
88: Recognized
89: .Ar type
90: arguments are:
91: .Bl -tag -width pstringXX
92: .It a
93: Number all lines.
94: .It t
95: Number only non-empty lines.
96: .It n
97: No line numbering.
98: .It p Ns Ar expr
99: Number only those lines that contain the basic regular expression specified
100: by
101: .Ar expr .
102: .El
103: .Pp
104: The default
105: .Ar type
106: for logical page body lines is t.
107: .It Fl d Ar delim
108: Specify the delimiter characters used to indicate the start of a logical
109: page section in the input file.
110: At most two characters may be specified; if only one character is specified,
111: the first character is replaced and the second character remains unchanged.
112: The default
113: .Ar delim
114: characters are ``\e:''.
115: .It Fl f Ar type
116: Specify the same as
117: .Fl b Ar type
118: except for logical page footer lines.
119: The default
120: .Ar type
121: for logical page footer lines is n.
122: .It Fl h Ar type
123: Specify the same as
124: .Fl b Ar type
125: except for logical page header lines.
126: The default
127: .Ar type
128: for logical page header lines is n.
129: .It Fl i Ar incr
130: Specify the increment value used to number logical page lines.
131: The default
132: .Ar incr
133: value is 1.
134: .It Fl l Ar num
135: If numbering of all lines is specified for the current logical section
136: using the corresponding
137: .Fl b
138: a,
139: .Fl f
140: a
141: or
142: .Fl h
143: a
144: option,
145: specify the number of adjacent blank lines to be considered as one.
146: For example,
147: .Fl l
148: 2 results in only the second adjacent blank line being numbered.
149: The default
150: .Ar num
151: value is 1.
152: .It Fl n Ar format
153: Specify the line numbering output format.
154: Recognized
155: .Ar format
156: arguments are:
1.2 jmc 157: .Pp
158: .Bl -tag -width lnXX -compact -offset indent
1.1 jca 159: .It ln
160: Left justified.
161: .It rn
162: Right justified, leading zeros suppressed.
163: .It rz
164: Right justified, leading zeros kept.
165: .El
166: .Pp
167: The default
168: .Ar format
169: is rn.
170: .It Fl p
171: Specify that line numbering should not be restarted at logical page delimiters.
172: .It Fl s Ar sep
173: Specify the characters used in separating the line number and the corresponding
174: text line.
175: The default
176: .Ar sep
177: setting is a single tab character.
178: .It Fl v Ar startnum
179: Specify the initial value used to number logical page lines; see also the
180: description of the
181: .Fl p
182: option.
183: The default
184: .Ar startnum
185: value is 1.
186: .It Fl w Ar width
187: Specify the number of characters to be occupied by the line number;
1.2 jmc 188: if the
1.1 jca 189: .Ar width
190: is insufficient to hold the line number, it will be truncated to its
191: .Ar width
192: least significant digits.
193: The default
194: .Ar width
195: is 6.
196: .El
197: .Sh EXIT STATUS
198: .Ex -std
199: .Sh SEE ALSO
200: .Xr pr 1
201: .Sh STANDARDS
202: The
203: .Nm
1.3 ! jca 204: utility conforms to
! 205: .St -xpg4.2
! 206: with the exception of not supporting the intermingling of the
! 207: .Ar file
! 208: operand with the options, which the standard considers an obsolescent feature
! 209: to be removed from a further issue.
1.1 jca 210: .Sh HISTORY
211: The
212: .Nm
213: utility first appeared in
214: .At V.2 .
215: It was added to the
216: .Ox 5.4
217: release.