usr.bin/nl/nl.1

   1 .\" $FreeBSD: head/usr.bin/nl/nl.1 265319 2014-05-04 12:20:40Z pluknet $
   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 January 3, 2016
  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 applies a configurable line numbering filter operation,
  76 and writes the result to the standard output.
  77 If
  78 .Ar file
  79 is a single dash
  80 .Pq Sq Fl
  81 or absent,
  82 .Nm
  83 reads from the standard input.
  84 .Pp
  85 The
  86 .Nm
  87 utility treats the text it reads in terms of logical pages.
  88 Unless specified otherwise, line numbering is reset at the start of each
  89 logical page.
  90 A logical page consists of a header, a body and a footer
  91 section; empty sections are valid.
  92 Different line numbering options are
  93 independently available for header, body and footer sections.
  94 .Pp
  95 The starts of logical page sections are signalled by input lines containing
  96 nothing but one of the following sequences of delimiter characters:
  97 .Bl -column "\e:\e:\e:" "Start of" -offset indent
  98 .Em "Line       Start of"
  99 .It "\e:\e:\e:  header"
 100 .It "\e:\e:     body"
 101 .It "\e:        footer"
 102 .El
 103 .Pp
 104 If the input does not contain any logical page section signalling directives,
 105 the text being read is assumed to consist of a single logical page body.
 106 .Pp
 107 The following options are available:
 108 .Bl -tag -width ".Fl v Ar startnum"
 109 .It Fl b Ar type
 110 Specify the logical page body lines to be numbered.
 111 Recognized
 112 .Ar type
 113 arguments are:
 114 .Bl -tag -width indent
 115 .It Cm a
 116 Number all lines.
 117 .It Cm t
 118 Number only non-empty lines.
 119 .It Cm n
 120 No line numbering.
 121 .It Cm p Ns Ar expr
 122 Number only those lines that contain the basic regular expression specified
 123 by
 124 .Ar expr .
 125 .El
 126 .Pp
 127 The default
 128 .Ar type
 129 for logical page body lines is
 130 .Cm t .
 131 .It Fl d Ar delim
 132 Specify the delimiter characters used to indicate the start of a logical
 133 page section in the input file.
 134 At most two characters may be specified;
 135 if only one character is specified, the first character is replaced and the
 136 second character remains unchanged.
 137 The default
 138 .Ar delim
 139 characters are
 140 .Dq Li \e: .
 141 .It Fl f Ar type
 142 Specify the same as
 143 .Fl b Ar type
 144 except for logical page footer lines.
 145 The default
 146 .Ar type
 147 for logical page footer lines is
 148 .Cm n .
 149 .It Fl h Ar type
 150 Specify the same as
 151 .Fl b Ar type
 152 except for logical page header lines.
 153 The default
 154 .Ar type
 155 for logical page header lines is
 156 .Cm n .
 157 .It Fl i Ar incr
 158 Specify the increment value used to number logical page lines.
 159 The default
 160 .Ar incr
 161 value is 1.
 162 .It Fl l Ar num
 163 If numbering of all lines is specified for the current logical section
 164 using the corresponding
 165 .Fl b Cm a ,
 166 .Fl f Cm a
 167 or
 168 .Fl h Cm a
 169 option,
 170 specify the number of adjacent blank lines to be considered as one.
 171 For example,
 172 .Fl l
 173 2 results in only the second adjacent blank line being numbered.
 174 The default
 175 .Ar num
 176 value is 1.
 177 .It Fl n Ar format
 178 Specify the line numbering output format.
 179 Recognized
 180 .Ar format
 181 arguments are:
 182 .Bl -tag -width indent -compact
 183 .It Cm ln
 184 Left justified.
 185 .It Cm rn
 186 Right justified, leading zeros suppressed.
 187 .It Cm rz
 188 Right justified, leading zeros kept.
 189 .El
 190 .Pp
 191 The default
 192 .Ar format
 193 is
 194 .Cm rn .
 195 .It Fl p
 196 Specify that line numbering should not be restarted at logical page delimiters.
 197 .It Fl s Ar sep
 198 Specify the characters used in separating the line number and the corresponding
 199 text line.
 200 The default
 201 .Ar sep
 202 setting is a single tab character.
 203 .It Fl v Ar startnum
 204 Specify the initial value used to number logical page lines; see also the
 205 description of the
 206 .Fl p
 207 option.
 208 The default
 209 .Ar startnum
 210 value is 1.
 211 .It Fl w Ar width
 212 Specify the number of characters to be occupied by the line number;
 213 in case the
 214 .Ar width
 215 is insufficient to hold the line number, it will be truncated to its
 216 .Ar width
 217 least significant digits.
 218 The default
 219 .Ar width
 220 is 6.
 221 .El
 222 .Sh ENVIRONMENT
 223 The
 224 .Ev LANG , LC_ALL , LC_CTYPE
 225 and
 226 .Ev LC_COLLATE
 227 environment variables affect the execution of
 228 .Nm
 229 as described in
 230 .Xr environ 7 .
 231 .Sh EXIT STATUS
 232 .Ex -std
 233 .Sh SEE ALSO
 234 .Xr jot 1 ,
 235 .Xr pr 1
 236 .Sh STANDARDS
 237 The
 238 .Nm
 239 utility conforms to
 240 .St -p1003.1-2001 .
 241 .Sh HISTORY
 242 The
 243 .Nm
 244 utility first appeared in
 245 .At V.2 .
 246 .Sh BUGS
 247 Input lines are limited to
 248 .Dv LINE_MAX
 249 (2048) bytes in length.