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