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