2 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
3 .\" All rights reserved.
5 .\" This code is derived from software contributed to The NetBSD Foundation
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
34 .Nd line numbering filter
72 utility reads lines from the named
74 applies a configurable line numbering filter operation,
75 and writes the result to the standard output.
82 reads from the standard input.
86 utility treats the text it reads in terms of logical pages.
87 Unless specified otherwise, line numbering is reset at the start of each
89 A logical page consists of a header, a body and a footer
90 section; empty sections are valid.
91 Different line numbering options are
92 independently available for header, body and footer sections.
94 The starts of logical page sections are signalled by input lines containing
95 nothing but one of the following sequences of delimiter characters:
96 .Bl -column "\e:\e:\e:" "Start of" -offset indent
98 .It "\e:\e:\e: header"
103 If the input does not contain any logical page section signalling directives,
104 the text being read is assumed to consist of a single logical page body.
106 The following options are available:
107 .Bl -tag -width ".Fl v Ar startnum"
109 Specify the logical page body lines to be numbered.
113 .Bl -tag -width indent
117 Number only non-empty lines.
121 Number only those lines that contain the basic regular expression specified
128 for logical page body lines is
131 Specify the delimiter characters used to indicate the start of a logical
132 page section in the input file.
133 At most two characters may be specified;
134 if only one character is specified, the first character is replaced and the
135 second character remains unchanged.
143 except for logical page footer lines.
146 for logical page footer lines is
151 except for logical page header lines.
154 for logical page header lines is
157 Specify the increment value used to number logical page lines.
162 If numbering of all lines is specified for the current logical section
163 using the corresponding
169 specify the number of adjacent blank lines to be considered as one.
172 2 results in only the second adjacent blank line being numbered.
177 Specify the line numbering output format.
181 .Bl -tag -width indent -compact
185 Right justified, leading zeros suppressed.
187 Right justified, leading zeros kept.
195 Specify that line numbering should not be restarted at logical page delimiters.
197 Specify the characters used in separating the line number and the corresponding
201 setting is a single tab character.
203 Specify the initial value used to number logical page lines; see also the
211 Specify the number of characters to be occupied by the line number;
214 is insufficient to hold the line number, it will be truncated to its
216 least significant digits.
223 .Ev LANG , LC_ALL , LC_CTYPE
226 environment variables affect the execution of
233 Number all non-blank lines:
234 .Bd -literal -offset indent
235 $ echo -e "This is\\n\\n\\na simple text" | nl
242 Number all lines including blank ones, with right justified line numbers with
243 leading zeroes, starting at 2, with increment of 2 and a custom multi-character
245 .Bd -literal -offset indent
246 $ echo -e "This\\nis\\nan\\n\\n\\nexample" | nl -ba -n rz -i2 -s "->" -v2
255 Number lines matching regular expression for an
257 .No followed by either
261 .Bd -literal -offset indent
262 $ echo -e "This is\\na simple text\\nwith multiple\\nlines" | nl -bp'i[mn]'
279 utility first appeared in
282 Input lines are limited to
284 (2048) bytes in length.