usr.bin/nl/nl.1

   1 .\"     $NetBSD: nl.1,v 1.9 2008/04/30 13:11:01 martin 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 .\"
  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 February 15, 1999
  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 section; empty
  87 sections are valid.
  88 Different line numbering options are independently available for header,
  89 body and footer sections.
  90 .Pp
  91 The starts of logical page sections are signaled by input lines containing
  92 nothing but one of the following sequences of delimiter characters:
  93 .Pp
  94 .Bd -unfilled -offset indent
  95 .Bl -column "\e:\e:\e: " "header "
  96 .It Em "Line"   "Start of"
  97 .It \e:\e:\e:   header
  98 .It \e:\e:      body
  99 .It \e: footer
 100 .El
 101 .Ed
 102 .Pp
 103 If the input does not contain any logical page section signaling directives,
 104 the text being read is assumed to consist of a single logical page body.
 105 .Pp
 106 The following options are available:
 107 .Bl -tag -width indent
 108 .It Fl b Ar type
 109 Specify the logical page body lines to be numbered.
 110 Recognized
 111 .Ar type
 112 arguments are:
 113 .Bl -tag -width pstringXX
 114 .It a
 115 Number all lines.
 116 .It t
 117 Number only non-empty lines.
 118 .It n
 119 No line numbering.
 120 .It p Ns Ar expr
 121 Number only those lines that contain the basic regular expression specified
 122 by
 123 .Ar expr .
 124 .El
 125 .Pp
 126 The default
 127 .Ar type
 128 for logical page body lines is t.
 129 .It Fl d Ar delim
 130 Specify the delimiter characters used to indicate the start of a logical
 131 page section in the input file.
 132 At most two characters may be specified; if only one character is specified,
 133 the first character is replaced and the second character remains unchanged.
 134 The default
 135 .Ar delim
 136 characters are ``\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 n.
 144 .It Fl h Ar type
 145 Specify the same as
 146 .Fl b Ar type
 147 except for logical page header lines.
 148 The default
 149 .Ar type
 150 for logical page header lines is n.
 151 .It Fl i Ar incr
 152 Specify the increment value used to number logical page lines.
 153 The default
 154 .Ar incr
 155 value is 1.
 156 .It Fl l Ar num
 157 If numbering of all lines is specified for the current logical section
 158 using the corresponding
 159 .Fl b
 160 a,
 161 .Fl f
 162 a
 163 or
 164 .Fl h
 165 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 lnXX -compact
 180 .It ln
 181 Left justified.
 182 .It rn
 183 Right justified, leading zeros suppressed.
 184 .It rz
 185 Right justified, leading zeros kept.
 186 .El
 187 .Pp
 188 The default
 189 .Ar format
 190 is 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 EXIT STATUS
 219 The
 220 .Nm
 221 utility exits 0 on success, and \*[Gt]0 if an error occurs.
 222 .Sh SEE ALSO
 223 .Xr pr 1
 224 .Sh STANDARDS
 225 The
 226 .Nm
 227 utility conforms to
 228 .St -xpg4.2
 229 with the exception of not supporting the intermingling of the
 230 .Ar file
 231 operand with the options, which the standard considers an obsolescent feature
 232 to be removed from a further issue.
 233 .Sh HISTORY
 234 The
 235 .Nm
 236 utility first appeared in
 237 .At V.2 .