usr.bin/nl/nl.1

   1 .\"     $NetBSD: nl.1,v 1.16 2013/09/24 22:08:06 wiz 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 May 1, 2013
  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 .Op Fl b Ar type
  40 .Op Fl d Ar delim
  41 .Op Fl f Ar type
  42 .Op Fl h Ar type
  43 .Op Fl i Ar incr
  44 .Op Fl l Ar num
  45 .Op Fl n Ar format
  46 .Op Fl s Ar sep
  47 .Op Fl v Ar startnum
  48 .Op Fl w Ar width
  49 .Op Ar file
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility reads lines from the named
  54 .Ar file ,
  55 applies a configurable line numbering filter operation,
  56 and writes the result to the standard output.
  57 If
  58 .Ar file
  59 is a single dash
  60 .Pq Sq \&-
  61 or absent,
  62 .Nm
  63 reads from the standard input.
  64 .Pp
  65 The
  66 .Nm
  67 utility treats the text it reads in terms of logical pages.
  68 Unless specified otherwise, line numbering is reset at the start of each
  69 logical page.
  70 A logical page consists of a header, a body and a footer section; empty
  71 sections are valid.
  72 Different line numbering options are independently available for header,
  73 body and footer sections.
  74 .Pp
  75 The starts of logical page sections are signaled by input lines containing
  76 nothing but one of the following sequences of delimiter characters:
  77 .Bl -column "\e:\e:\e: " "header " -offset indent
  78 .It Em "Line" Ta Em "Start of"
  79 .It \e:\e:\e:   header
  80 .It \e:\e:      body
  81 .It \e: footer
  82 .El
  83 .Pp
  84 If the input does not contain any logical page section signaling directives,
  85 the text being read is assumed to consist of a single logical page body.
  86 .Pp
  87 The following options are available:
  88 .Bl -tag -width indent
  89 .It Fl b Ar type
  90 Specify the logical page body lines to be numbered.
  91 Recognized
  92 .Ar type
  93 arguments are:
  94 .Bl -tag -width pstringXX
  95 .It a
  96 Number all lines.
  97 .It t
  98 Number only non-empty lines.
  99 .It n
 100 No line numbering.
 101 .It p Ns Ar expr
 102 Number only those lines that contain the basic regular expression specified
 103 by
 104 .Ar expr .
 105 .El
 106 .Pp
 107 The default
 108 .Ar type
 109 for logical page body lines is t.
 110 .It Fl d Ar delim
 111 Specify the delimiter characters used to indicate the start of a logical
 112 page section in the input file.
 113 At most two characters may be specified; if only one character is specified,
 114 the first character is replaced and the second character remains unchanged.
 115 The default
 116 .Ar delim
 117 characters are ``\e:''.
 118 .It Fl f Ar type
 119 Specify the same as
 120 .Fl b Ar type
 121 except for logical page footer lines.
 122 The default
 123 .Ar type
 124 for logical page footer lines is n.
 125 .It Fl h Ar type
 126 Specify the same as
 127 .Fl b Ar type
 128 except for logical page header lines.
 129 The default
 130 .Ar type
 131 for logical page header lines is n.
 132 .It Fl i Ar incr
 133 Specify the increment value used to number logical page lines.
 134 The default
 135 .Ar incr
 136 value is 1.
 137 .It Fl l Ar num
 138 If numbering of all lines is specified for the current logical section
 139 using the corresponding
 140 .Fl b
 141 a,
 142 .Fl f
 143 a
 144 or
 145 .Fl h
 146 a
 147 option,
 148 specify the number of adjacent blank lines to be considered as one.
 149 For example,
 150 .Fl l
 151 2 results in only the second adjacent blank line being numbered.
 152 The default
 153 .Ar num
 154 value is 1.
 155 .It Fl n Ar format
 156 Specify the line numbering output format.
 157 Recognized
 158 .Ar format
 159 arguments are:
 160 .Pp
 161 .Bl -tag -width lnXX -compact -offset indent
 162 .It ln
 163 Left justified.
 164 .It rn
 165 Right justified, leading zeros suppressed.
 166 .It rz
 167 Right justified, leading zeros kept.
 168 .El
 169 .Pp
 170 The default
 171 .Ar format
 172 is rn.
 173 .It Fl p
 174 Specify that line numbering should not be restarted at logical page delimiters.
 175 .It Fl s Ar sep
 176 Specify the characters used in separating the line number and the corresponding
 177 text line.
 178 The default
 179 .Ar sep
 180 setting is a single tab character.
 181 .It Fl v Ar startnum
 182 Specify the initial value used to number logical page lines; see also the
 183 description of the
 184 .Fl p
 185 option.
 186 The default
 187 .Ar startnum
 188 value is 1.
 189 .It Fl w Ar width
 190 Specify the number of characters to be occupied by the line number;
 191 if the
 192 .Ar width
 193 is insufficient to hold the line number, it will be truncated to its
 194 .Ar width
 195 least significant digits.
 196 The default
 197 .Ar width
 198 is 6.
 199 .El
 200 .Sh EXIT STATUS
 201 .Ex -std
 202 .Sh SEE ALSO
 203 .Xr pr 1
 204 .Sh STANDARDS
 205 The
 206 .Nm
 207 utility is compliant with the
 208 .St -xpg4.2
 209 specification.
 210 .Sh HISTORY
 211 The
 212 .Nm
 213 utility first appeared in
 214 .At V.2 .