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.4 2008/05/02 02:05:07 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.Bl -column "\e:\e:\e:" "Start of" -offset indent 100.It Em "Line" Ta Em "Start of" 101.It "\e:\e:\e:" Ta "header" 102.It "\e:\e:" Ta "body" 103.It "\e:" Ta "footer" 104.El 105.Pp 106If the input does not contain any logical page section signalling directives, 107the text being read is assumed to consist of a single logical page body. 108.Pp 109The following options are available: 110.Bl -tag -width ".Fl v Ar startnum" 111.It Fl b Ar type 112Specify the logical page body lines to be numbered. 113Recognized 114.Ar type 115arguments are: 116.Bl -tag -width indent 117.It Cm a 118Number all lines. 119.It Cm t 120Number only non-empty lines. 121.It Cm n 122No line numbering. 123.It Cm p Ns Ar expr 124Number only those lines that contain the basic regular expression specified 125by 126.Ar expr . 127.El 128.Pp 129The default 130.Ar type 131for logical page body lines is 132.Cm t . 133.It Fl d Ar delim 134Specify the delimiter characters used to indicate the start of a logical 135page section in the input file. At most two characters may be specified; 136if only one character is specified, the first character is replaced and the 137second character remains unchanged. 138The default 139.Ar delim 140characters are 141.Dq Li \e: . 142.It Fl f Ar type 143Specify the same as 144.Fl b Ar type 145except for logical page footer lines. 146The default 147.Ar type 148for logical page footer lines is 149.Cm n . 150.It Fl h Ar type 151Specify the same as 152.Fl b Ar type 153except for logical page header lines. 154The default 155.Ar type 156for logical page header lines is 157.Cm 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 Cm a , 167.Fl f Cm a 168or 169.Fl h Cm a 170option, 171specify the number of adjacent blank lines to be considered as one. 172For example, 173.Fl l 1742 results in only the second adjacent blank line being numbered. 175The default 176.Ar num 177value is 1. 178.It Fl n Ar format 179Specify the line numbering output format. 180Recognized 181.Ar format 182arguments are: 183.Bl -tag -width indent -compact 184.It Cm ln 185Left justified. 186.It Cm rn 187Right justified, leading zeros suppressed. 188.It Cm rz 189Right justified, leading zeros kept. 190.El 191.Pp 192The default 193.Ar format 194is 195.Cm rn . 196.It Fl p 197Specify that line numbering should not be restarted at logical page delimiters. 198.It Fl s Ar sep 199Specify the characters used in separating the line number and the corresponding 200text line. 201The default 202.Ar sep 203setting is a single tab character. 204.It Fl v Ar startnum 205Specify the initial value used to number logical page lines; see also the 206description of the 207.Fl p 208option. 209The default 210.Ar startnum 211value is 1. 212.It Fl w Ar width 213Specify the number of characters to be occupied by the line number; 214in case the 215.Ar width 216is insufficient to hold the line number, it will be truncated to its 217.Ar width 218least significant digits. 219The default 220.Ar width 221is 6. 222.El 223.Sh EXIT STATUS 224.Ex -std 225.Sh SEE ALSO 226.Xr jot 1 , 227.Xr pr 1 228.Sh STANDARDS 229The 230.Nm 231utility conforms to 232.St -p1003.1-2001 . 233.Sh HISTORY 234The 235.Nm 236utility first appeared in 237.At V.2 . 238