Annotation of src/usr.bin/nl/nl.1, Revision 1.7
1.7 ! jmc 1: .\" $OpenBSD: nl.1,v 1.6 2014/03/16 17:49:09 tedu Exp $
1.3 jca 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.7 ! jmc 31: .Dd $Mdocdate: March 16 2014 $
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.5 jca 55: .Ar file ,
1.2 jmc 56: applies a configurable line numbering filter operation,
57: and writes the result to the standard output.
1.5 jca 58: If
59: .Ar file
60: is a single dash
61: .Pq Sq \&-
62: or absent,
63: .Nm
64: reads from the standard input.
1.1 jca 65: .Pp
66: The
67: .Nm
68: utility treats the text it reads in terms of logical pages.
69: Unless specified otherwise, line numbering is reset at the start of each
70: logical page.
71: A logical page consists of a header, a body and a footer section; empty
72: sections are valid.
73: Different line numbering options are independently available for header,
74: body and footer sections.
75: .Pp
76: The starts of logical page sections are signaled by input lines containing
77: nothing but one of the following sequences of delimiter characters:
1.2 jmc 78: .Bl -column "\e:\e:\e: " "header " -offset indent
79: .It Em "Line" Ta Em "Start of"
1.1 jca 80: .It \e:\e:\e: header
81: .It \e:\e: body
82: .It \e: footer
83: .El
84: .Pp
85: If the input does not contain any logical page section signaling directives,
86: the text being read is assumed to consist of a single logical page body.
87: .Pp
88: The following options are available:
89: .Bl -tag -width indent
90: .It Fl b Ar type
91: Specify the logical page body lines to be numbered.
92: Recognized
93: .Ar type
94: arguments are:
95: .Bl -tag -width pstringXX
96: .It a
97: Number all lines.
98: .It t
99: Number only non-empty lines.
100: .It n
101: No line numbering.
102: .It p Ns Ar expr
103: Number only those lines that contain the basic regular expression specified
104: by
105: .Ar expr .
106: .El
107: .Pp
108: The default
109: .Ar type
110: for logical page body lines is t.
111: .It Fl d Ar delim
112: Specify the delimiter characters used to indicate the start of a logical
113: page section in the input file.
114: At most two characters may be specified; if only one character is specified,
115: the first character is replaced and the second character remains unchanged.
116: The default
117: .Ar delim
118: characters are ``\e:''.
119: .It Fl f Ar type
120: Specify the same as
121: .Fl b Ar type
122: except for logical page footer lines.
123: The default
124: .Ar type
125: for logical page footer lines is n.
126: .It Fl h Ar type
127: Specify the same as
128: .Fl b Ar type
129: except for logical page header lines.
130: The default
131: .Ar type
132: for logical page header lines is n.
133: .It Fl i Ar incr
134: Specify the increment value used to number logical page lines.
135: The default
136: .Ar incr
137: value is 1.
138: .It Fl l Ar num
139: If numbering of all lines is specified for the current logical section
140: using the corresponding
141: .Fl b
142: a,
143: .Fl f
144: a
145: or
146: .Fl h
147: a
148: option,
149: specify the number of adjacent blank lines to be considered as one.
150: For example,
151: .Fl l
152: 2 results in only the second adjacent blank line being numbered.
153: The default
154: .Ar num
155: value is 1.
156: .It Fl n Ar format
157: Specify the line numbering output format.
158: Recognized
159: .Ar format
160: arguments are:
1.2 jmc 161: .Pp
162: .Bl -tag -width lnXX -compact -offset indent
1.1 jca 163: .It ln
164: Left justified.
165: .It rn
166: Right justified, leading zeros suppressed.
167: .It rz
168: Right justified, leading zeros kept.
169: .El
170: .Pp
171: The default
172: .Ar format
173: is rn.
174: .It Fl p
175: Specify that line numbering should not be restarted at logical page delimiters.
176: .It Fl s Ar sep
177: Specify the characters used in separating the line number and the corresponding
178: text line.
179: The default
180: .Ar sep
181: setting is a single tab character.
182: .It Fl v Ar startnum
183: Specify the initial value used to number logical page lines; see also the
184: description of the
185: .Fl p
186: option.
187: The default
188: .Ar startnum
189: value is 1.
190: .It Fl w Ar width
191: Specify the number of characters to be occupied by the line number;
1.2 jmc 192: if the
1.1 jca 193: .Ar width
194: is insufficient to hold the line number, it will be truncated to its
195: .Ar width
196: least significant digits.
197: The default
198: .Ar width
199: is 6.
200: .El
201: .Sh EXIT STATUS
202: .Ex -std
203: .Sh SEE ALSO
204: .Xr pr 1
205: .Sh STANDARDS
206: The
207: .Nm
1.4 jmc 208: utility is compliant with the
1.7 ! jmc 209: X/Open System Interfaces option of the
! 210: .St -p1003.1-2008
1.4 jmc 211: specification.
1.1 jca 212: .Sh HISTORY
213: The
214: .Nm
215: utility first appeared in
216: .At V.2 .
217: It was added to the
1.6 tedu 218: .Ox 5.5
1.1 jca 219: release.