text_cmds/nl/nl.1

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