manual/gnumaniak/original/man1/pr.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 pr man page
  12 .\"     man pages are NOT obsolete!
  13 .\"     <ragnar@ragnar-hojland.com>
  14 .TH PR 1 "7 October 2002" "GNU textutils 2.1"
  15 .SH NAME
  16 \fBpr\fR \- paginate or columnate files for printing
  17 .SH SYNOPSIS
  18 .B pr
  19 [\fB+\fIFIRST_PAGE\fR[\fB:\fILAST_PAGE\fR]]
  20 [\fB\-\fICOLUMN\fR] [\fB\-acdfmrtvFJT\fR]
  21 [\fB\-e\fR[\fIIN-TABCHAR\fR[\fIIN\-TABWIDTH\fR]]
  22 [\fB\-h \fIHEADER\fR]
  23 [\fB\-i\fR[\fIOUT\-TABCHAR\fR[\fIOUT\-TABWIDTH\fR]]
  24 [\fB\-l \fIPAGE_LENGTH\fR]
  25 [\fB\-n\fR[\fINUMBER\-SEPARATOR\fR[\fIDIGITS\fR]]
  26 [\fB\-o \fIMARGIN\fR]
  27 [\fB\-s\fR[\fISEP\-CHAR\fR]]
  28 [\fB\-w \fIPAGE_WIDTH\fR]
  29 [\fB\-D \fIDATEFORMAT\fR]
  30 [\fB\-N \fILINE_NUMBER\fR]
  31 [\fB\-S\fR[\fISEP\-STRING\fR]]
  32 [\fB\-W \fIPAGE_WIDTH\fR]
  33 [\fB\-\-across\fR]
  34 [\fB\-\-columns=\fICOLUMN\fR]
  35 [\fB\-\-date=\fIDATEFORMAT\fR]
  36 [\fB\-\-double\-\-space\fR]
  37 [\fB\-\-expand\-tabs\fR[\fB=\fIIN-TABCHAR\fR[\fIIN\-TABWIDTH\fR]]
  38 [\fB\-\-form\-feed\fR]
  39 [\fB\-\-header \fIHEADER\fR]
  40 [\fB\-\-indent=\fIMARGIN\fR]
  41 [\fB\-\-length \fIPAGE_LENGTH\fR]
  42 [\fB\-\-merge\fR]
  43 [\fB\-\-number\-lines\fR[\fB=\fINUMBER\-SEPARATOR\fR[\fIDIGITS\fR]]
  44 [\fB\-\-no\-file\-warnings\fR]
  45 [\fB\-\-output\-tabs\fR[\fB=\fIOUT\-TABCHAR\fR[\fIOUT\-TABWIDTH\fR]]
  46 [\fB\-\-omit\-header\fR]
  47 [\fB\-\-pages=\fIFIRST_PAGE\fR[\fB:\fILAST_PAGE\fR]]
  48 [\fB\-\-page_width=\fIPAGE_WIDTH\fR]
  49 [\fB\-\-separator\fR[\fB=\fISEP\-CHAR\fR]]
  50 [\fB\-\-sep\-string\fR[\fB=\fISEP\-STRING\fR]]
  51 [\fB\-\-show\-control\-chars\fR]
  52 [\fB\-\-show\-nonprinting\fR]
  53 [\fB\-\-width=\fIPAGE_WIDTH\fR]
  54 .RI [ FILE... ]
  55
  56 .BR pr " [" \-\-help "] [" \-\-version ]
  57 .SH DESCRIPTION
  58 .B pr
  59 writes each
  60 .I FILE
  61 to standard output paginating and optionally outputting in multicolumn format.
  62 If
  63 .I FILE
  64 is omitted or if it is a
  65 .RB ` \- ',
  66 standard input is used.
  67
  68 By default, a 5\-line header is printed at each page: two blank lines; a
  69 line with the date, the file name, and the page count; and two more blank
  70 lines.  A footer of five blank lines is also printed at each page.
  71
  72 The default \fIPAGE_LENGTH\fR is 66 lines, and the text line of a header
  73 takes up the full \fIPAGE_WIDTH\fR (default is 72) in the form `yy-mm-dd
  74 HH:MM String Page nnnn', where String is a centered string.
  75
  76 Form feeds in the input cause page breaks in the output.  Multiple
  77 form feeds produce empty pages.
  78
  79 Columns have equal width, separated by a space by default.  Lines will
  80 always be truncated to \fIPAGE_WIDTH\fR, unless you use the \fB\-J\fR
  81 option.  For single column output no line truncation occurs by default.
  82 (use \fB\-W\fR for truncation).
  83 .SH OPTIONS
  84 .TP
  85 .B +\fIFIRST_PAGE\fR[\fB:\fILAST_PAGE\fR]\fB
  86 .TP
  87 .B \-\-pages=\fIFIRST_PAGE\fR[\fB:\fILAST_PAGE\fR]
  88 Begin printing with page \fIFIRST_PAGE\fR and stop with \fILAST_PAGE\fR.
  89 Missing \fB:\fILAST_PAGE\fR implies end of file.  While estimating the
  90 number of skipped pages each form feed in the input file results
  91 in a new page.  Page and line numbering with and without \fB+\fIFIRST_PAGE\fR
  92 is identical as it starts counting at the first page of input file (not
  93 first page printed); page numbering, however, may be altered by \fB\-N\fR.
  94 .TP
  95 .B \-\fICOLUMN\fB
  96 .TP
  97 .B \-\-columns=\fICOLUMN
  98 With each single \fIFILE\fR produce \fICOLUMN\fR\ columns of output (default
  99 is 1) and print columns down.  The column width is automatically calculated
 100 from \fIPAGE_WIDTH\fR, and the number of lines in the columns on each page
 101 is balanced.  Lines that don't fit in a column are truncated.
 102 \fB-\-columns\fR may not be used with \fB\-m\fR.
 103 .TP
 104 .B \-a, \-\-across
 105 With each single \fIFILE\fR, print columns across rather than down.
 106 \fICOLUMN\fR must be greater than one.  Lines that don't fit in a column are
 107 truncated.
 108 .TP
 109 .B \-c, \-\-show\-control\-chars
 110 Print control characters using hat notation (e.g., `^G'); print
 111 other unprintable characters in octal backslash notation.  By
 112 default, unprintable characters are not changed.
 113 .TP
 114 .B \-d, \-\-double\-space
 115 Double space the output.
 116 .TP
 117 .B \-e\fR[\fIIN-TABCHAR\fR[\fIIN\-TABWIDTH\fR]]
 118 .TP
 119 .B \-\-expand\-tabs\fR[\fB=\fIIN-TABCHAR\fR[\fIIN\-TABWIDTH\fR]],
 120 Expand tabs to spaces on input.  Optional argument \fIIN-TABCHAR\fR is
 121 the input tab character (default is <TAB>).  Second optional argument
 122 \fIIN-TABWIDTH\fR is the input tab character's width (default is 8).
 123 .TP
 124 .B \-f, \-F, \-\-form\-feed
 125 Use a form feed instead of newlines to separate output pages, and print only
 126 a 3\-line header (the two leading blank lines and footer are omitted).
 127 Default page length of 66 lines is not altered, but the default number of
 128 lines of text per page changes from 56 to 63 lines.
 129 .TP
 130 .B \-h \fIHEADER\fB, \-\-header=\fIHEADER
 131 Replace the name of \fIFILE\fR in the header with the centered string
 132 \fIHEADER\fR.  Left-hand-side truncation (marked by a `*') may occur if
 133 the total header line `yy-mm-dd HH:MM \fIHEADER\fR Page nnnn' becomes
 134 larger than \fIPAGE_WIDTH\fR. `\fB\-h ""\fR' prints a blank line
 135 header.
 136 .TP
 137 .B \-i\fR[\fIOUT\-TABCHAR\fR[\fIOUT\-TABWIDTH\fR]]
 138 .TP
 139 .B \-\-output\-tabs\fR[\fB=\fIOUT\-TABCHAR\fR[\fIOUT\-TABWIDTH\fR]]
 140 Collapse spaces with tabs on output.  Optional argument \fIOUT\-TABCHAR\fR
 141 is the output tab character (default is <TAB>).  Second optional
 142 argument \fIOUT\-TABWIDTH\fR is the output tab character's width (default is
 143 8).
 144 .TP
 145 .B \-J, \-\-join\-lines
 146 Merge lines of full length. Used together with the column options
 147 \fB\-\fICOLUMN\fR, `\fB\-a \-\fICOLUMN\fR' or \fB\-m\fR, it turns off
 148 \fB\-W\fR and \fB\-w\fR line truncation;  no column alignment is used.  It
 149 changes the column separator to <TAB>, unless overriden by \fB\-S\fR.
 150 .TP
 151 .B \-l \fIPAGE_LENGTH\fB, \-\-length=\fIPAGE_LENGTH
 152 Set the page length (including header and footer) to \fIPAGE_LENGTH\fR
 153 (default is 66) lines.  If \fIPAGE_LENGTH\fR is <= 10 (and <= 3 with
 154 \fB\-F\fR), the headers and footers are omitted and all form feeds set in
 155 input files are eliminated as if the \fB\-T\fR option had been given.
 156 .TP
 157 .B \-m, \-\-merge
 158 Merge and print all \fIFILE\fRs in parallel, one in each
 159 column resulting.  If a line is too long to fit in a column, it is truncated.
 160 Empty pages in \fIFILE\fRs (form feeds set) produce empty columns, still
 161 marked by \fISEPARATOR\fR (but completely empty common pages show no
 162 separators or line numbers)  The default header becomes `yy-mm-dd HH:MM
 163 <blanks> Page nnnn'; may be used with \fB\-h \fIHEADER\fR to fill up the
 164 middle part, and with \fB\-S\fR[\fISEP\-CHAR\fR].
 165 .TP
 166 .B \-n\fR[\fINUMBER\-SEPARATOR\fR[\fIDIGITS\fR]]
 167 .TP
 168 .B \-\-number\-lines\fR[\fB=\fINUMBER\-SEPARATOR\fR[\fIDIGITS\fR]]
 169 Precede each column with a line number; with parallel \fIFILE\fRs
 170 (\fB\-m\fR), precede only each line with a line number.  Default line
 171 number counting starts with first line of the input file (not with the first
 172 line printed, see \fB\-N\fR and \fB\-\fIPAGES\fR).
 173
 174 Optional argument \fINUMBER\-SEPARATOR\fR is the character to print after
 175 each number;  the default is a space, which are automagically collapsed to a
 176 <TAB> if it won't change the width .  Optional argument \fIDIGITS\fR is the
 177 number of digits per line number (default is 5).
 178 .TP
 179 .B \-o \fIMARGIN\fB, \-\-indent=\fIMARGIN
 180 Indent each line with \fIMARGIN\fR spaces wide (default is 0), i.e., set
 181 the left margin.  The total page width is \fIMARGIN\fR plus
 182 \fIPAGE_WIDTH\fR.  Overflow may happen with numbered column output.
 183 .TP
 184 .B \-r, \-\-no\-file\-warnings
 185 Do not print a warning message when an argument \fIFILE\fR cannot be
 186 opened.  (The exit status will still be nonzero, however.)
 187 .TP
 188 .B \-s\fR[\fISEP\-CHAR\fR]\fB, \-\-separator\fR[\fB=\fISEP\-CHAR\fR]
 189 Separate columns with a \fISEP\-CHAR\fR character.  The default for
 190 \fISEP\-CHAR\fR is an empty string if \fB\-s\fR is combined with \fB\-w\fR,
 191 and <TAB> if it is not.  A second effect of the \fB\-w\fR combination is
 192 that column truncation is turned off.
 193 .TP
 194 .B \-S\fR[\fISEP\-STRING\fR]\fB, \-\-sep\-string\fR[\fB=\fISEP\-STRING\fR]
 195 Separate columns with a \fISEP\-STRING\fR string (default is an empty string).
 196 Short option form \fB\-S\fR is deprecated.
 197 .TP
 198 .B \-t, \-\-omit\-header
 199 Do not print the header (and footer) on each page, and do
 200 not fill out the bottom of pages (with blank lines or a form
 201 feed).  No page structure is produced, but retain form feeds set in
 202 the input files (therefore the predefined pagination is not changed)
 203 \fB\-t\fR  or \fB\-T\fR may be useful together with other options; e.g.:
 204 `\fB\-t \-e4\fR', expand <TAB> in the input file to 4 spaces but do not do
 205 any other changes.  Use of \fB\-t\fR overrides \fB\-h\fR.
 206 .TP
 207 .B \-v, \-\-show\-nonprinting
 208 Print unprintable characters in octal backslash notation.
 209 .TP
 210 .B \-w \fIPAGE_WIDTH\fB, \-\-width=\fIPAGE_WIDTH
 211 For multiple column output only, set the page width to \fIPAGE_WIDTH\fR (default
 212 is 72) characters and truncate lines..
 213 .TP
 214 .B \-D \fIDATEFORMAT\fB, \-\-date=\fIDATEFORMAT
 215 Use \fIDATEFORMAT\fR as the date format for headers, or to specify a date.
 216 See \fBdate\fR(1) for details.
 217 .TP
 218 .B \-N \fILINE_NUMBER\fB, \-\-first\-line\-number=\fILINE_NUMBER
 219 Start counting line counting with \fILINE_NUMBER\fR at the first line of the
 220 first page printed.
 221 .TP
 222 .B \-S \fR[\fISEP\-STRING\fR]\fB, \-\-sep\-string\fR[\fB=\fISEP\-STRING\fR]
 223 Separate output columns with the string \fISEP\-STRING\fR.
 224 .TP
 225 .B \-T
 226 Do not print header (and footer).  In addition eliminate all form
 227 feeds set in the input files.
 228 .TP
 229 .B \-W \fIPAGE_WIDTH\fB, \-\-page_width=\fIPAGE_WIDTH
 230 For both single and multiple column output, set the page width to
 231 \fIPAGE_WIDTH\fR (default is 72) characters and truncate lines.  If neither
 232 \fB\-W\fR or any of the column options is used no truncation is done (except
 233 on the header line, which is always truncated).
 234 .TP
 235 .B \-\-help
 236 Print a usage message on standard output and exit successfully.
 237 .TP
 238 .B \-\-version
 239 Print version information on standard output then exit successfully.
 240 .SH POSIX NOTES
 241 Uppercase single letter options dominate over lowercase ones, being the
 242 latter redefined to be more \fBPOSIX\fR compilant.  Also, arguments to some single
 243 letter options can't be separated from the preceding option as specified in
 244 the \fBPOSIX\fR specification (for example `\fB\-s\fR a' should be `\fB\-sa\fR' instead)
 245 .SH NOTES
 246 Report bugs to bug-textutils@gnu.org.
 247 .br
 248 Man page by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>