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 .\"
   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 September 20, 2001
  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 ommitted,
  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.  A logical page consists of a header, a body and a footer
  93 section; empty sections are valid.  Different line numbering options are
  94 independently available for header, body and footer sections.
  95 .Pp
  96 The starts of logical page sections are signalled by input lines containing
  97 nothing but one of the following sequences of delimiter characters:
  98 .Pp
  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 DIAGNOSTICS
 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 .