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