manual/gnumaniak/original/man1/nl.1

   1 .\" You may copy, distribute and modify under the terms of the LDP General
   2 .\" Public License as specified in the LICENSE file that comes with the
   3 .\" gnumaniak distribution
   4 .\"
   5 .\" The author kindly requests that no comments regarding the "better"
   6 .\" suitability or up-to-date notices of any info documentation alternative
   7 .\" is added without contacting him first.
   8 .\"
   9 .\" (C) 2002 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
  10 .\"
  11 .\"     GNU nl man page
  12 .\"     man pages are NOT obsolete!
  13 .\"     <ragnar@ragnar-hojland.com>
  14 .TH NL 1 "7 October 2002" "GNU textutils 2.1"
  15 .SH NAME
  16 \fBnl\fR \- number lines and write files
  17 .SH SYNOPSIS
  18 .B nl
  19 .RB [ \-p "] [" "\-b \fISTYLE\fR" "] [" "\-d \fICD\fR" ]
  20 .RB [ "\-f \fISTYLE\fR" "] [" "\-h \fISTYLE\fR" "] [" "\-i \fINUMBER\fR" ]
  21 .RB [ "\-l \fINUMBER\fR" "] [" "\-n \fIFORMAT\fR" "] [" "\-s \fISTRING\fR" ]
  22 .RB [ "\-v \fINUMBER\fR" "] [" "\-w \fINUMBER\fR" ]
  23 .RB [ "\-\-body\-numbering=\fISTYLE\fR" ]
  24 .RB [ "\-\-footer\-numbering=\fISTYLE\fR" ]
  25 .RB [ "\-\-header\-numbering=\fISTYLE\fR" ]
  26 .RB [ "\-\-join\-blank\-lines=\fINUMBER\fR" ]
  27 .RB [ "\-\-page\-increment=\fINUMBER\fR" ]
  28 .RB [ \-\-no\-renumber ]
  29 .RB [ "\-\-number\-format=\fIFORMAT\fR" ]
  30 .RB [ "\-\-number\-separator=\fIFORMAT\fR" ]
  31 .RB [ "\-\-number\-width=\fINUMBER\fR" ]
  32 .RB [ "\-\-section\-delimiter=\fICD\fR" ]
  33 .RB [ "\-\-starting\-line\-number=\fINUMBER\fR" ]
  34 .RI [ FILE... ]
  35
  36 .BR nl " [" \-\-help "] [" \-\-version ]
  37 .SH DESCRIPTION
  38 .B nl
  39 writes each
  40 .I FILE
  41 to standard output, with line numbers added to some or all of the lines.  If
  42 .I FILE
  43 is omitted or if is a
  44 .RB ` \- ',
  45 standard input is used.
  46
  47 .B nl
  48 decomposes its input into (logical) pages; by default, the line
  49 number is reset to 1 at the top of each logical page.
  50 .B nl
  51 treats all of the input files as a single document; it does not reset line
  52 numbers or logical pages between files.
  53 .SH OPTIONS
  54 .TP
  55 .B \-b \fISTYLE\fB, \-\-body\-numbering=\fISTYLE
  56 Select the numbering style for lines in the body section of each
  57 logical page.  When a line is not numbered, the current line number
  58 is not incremented, but the line number separator character is
  59 still prepended to the line.  The styles are:
  60 .RS
  61 .TP
  62 .B a
  63 number all lines
  64 .TP
  65 .B t
  66 number only nonempty lines (default for body)
  67 .TP
  68 .B n
  69 do not number lines (default for header and footer)
  70 .TP
  71 .BI p REGEXP
  72 number only lines that contain a match for
  73 .IR REGEXP .
  74 .RE
  75 .TP
  76 .B \-d \fICD\fB, \-\-section\-delimiter=\fICD
  77 Set the section delimiter characters to \fICD\fR; default is `\e:'. If
  78 only \fIC\fR is given, the second remains `:'.  (Remember to protect `\e'
  79 or other metacharacters from shell expansion with quotes or extra
  80 backslashes)
  81 .TP
  82 .B \-f \fISTYLE\fB, \-\-footer\-numbering=\fISTYLE
  83 Analogous to
  84 .BR \-\-body\-numbering .
  85 .TP
  86 .B \-h \fISTYLE\fB, \-\-header\-numbering=\fISTYLE
  87 Analogous to
  88 .BR \-\-body\-numbering .
  89 .TP
  90 .B \-i \fINUMBER\fB, \-\-page\-increment=\fINUMBER
  91 Increment line numbers by
  92 .I NUMBER
  93 (default 1).
  94 .TP
  95 .B \-l \fINUMBER\fB, \-\-join\-blank\-lines=\fINUMBER
  96 Consider
  97 .I NUMBER
  98 (default 1) consecutive empty lines to be one logical line for numbering,
  99 and only number the last one.  Where fewer than
 100 .I NUMBER
 101 consecutive empty lines occur, do not number them.  An empty line is one
 102 that contains no characters, not even spaces or tabs.
 103 .TP
 104 .B \-n \fIFORMAT\fB, \-\-number\-format=\fIFORMAT
 105 Select the line numbering format (default is `\fBrn\fR'):
 106 .RS
 107 .TP
 108 .B ln
 109 left justified, no leading zeros
 110 .TP
 111 .B rn
 112 right justified, no leading zeros
 113 .TP
 114 .B rz
 115 right justified, leading zeros
 116 .RE
 117 .TP
 118 .B \-p, \-\-no\-renumber
 119 Do not reset the line number at the start of a logical page.
 120 .TP
 121 .B \-s \fISTRING\fB, \-\-number\-separator=\fIFORMAT
 122 Separate the line number from the text line in the output with
 123 .I STRING
 124 (default is <TAB>).
 125 .TP
 126 .B \-v \fINUMBER\fB, \-\-starting\-line\-number=\fINUMBER
 127 Set the initial line number on each logical page to
 128 .I NUMBER
 129 (default 1).
 130 .TP
 131 .B \-w \fINUMBER\fB, \-\-number\-width=\fINUMBER
 132 Use
 133 .I NUMBER
 134 characters for line numbers (default 6).
 135 .TP
 136 .B "\-\-help"
 137 Print a usage message on standard output and exit successfully.
 138 .TP
 139 .B "\-\-version"
 140 Print version information on standard output then exit successfully.
 141 .SH LOGICAL PAGES
 142 A logical page consists of three sections: header, body, and footer.
 143 Any of the sections can be empty.  Each can be numbered in a different
 144 style from the others.
 145
 146 The beginnings of the sections of logical pages are indicated in the
 147 input file by a line containing exactly one of these delimiter strings:
 148 .TP
 149 .B \e:\e:\e:
 150 start of header
 151 .TP
 152 .B \e:\e:
 153 start of body;
 154 .TP
 155 .B \e:
 156 start of footer.
 157 .PP
 158 The two characters from which these strings are made can be changed
 159 from
 160 .RB ` \e "' and `" : '
 161 via options, but the pattern and length of each string cannot be
 162 changed.  A section delimiter is replaced by an empty line on output.  Any
 163 text that comes before the first section delimiter string in the input file
 164 is considered to be part of a body section, so
 165 .B nl
 166 treats a file that contains no section delimiters as a single body section.
 167 .SH NOTES
 168 Report bugs to bug-textutils@gnu.org.
 169 .br
 170 Man page by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>