usr.bin/nl/nl.1

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