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