usr.bin/nl/nl.1

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