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