Annotation of src/usr.bin/pr/pr.1, Revision 1.24
1.24 ! jmc 1: .\" $OpenBSD: pr.1,v 1.23 2010/10/01 07:06:16 jmc Exp $
1.11 aaron 2: .\"
1.1 deraadt 3: .\" Copyright (c) 1991 Keith Muller.
4: .\" Copyright (c) 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" Keith Muller of the University of California, San Diego.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
1.15 millert 18: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" from: @(#)pr.1 8.1 (Berkeley) 6/6/93
35: .\"
1.24 ! jmc 36: .Dd $Mdocdate: October 1 2010 $
1.1 deraadt 37: .Dt PR 1
1.8 aaron 38: .Os
1.1 deraadt 39: .Sh NAME
40: .Nm pr
41: .Nd print files
42: .Sh SYNOPSIS
43: .Nm pr
1.16 jmc 44: .Op Ar +page
1.1 deraadt 45: .Op Fl Ar column
1.16 jmc 46: .Op Fl adFfmrt
1.24 ! jmc 47: .Op Fl e Ns Oo Ar char Oc Ns Op Ar gap
1.1 deraadt 48: .Op Fl h Ar header
1.24 ! jmc 49: .Op Fl i Ns Oo Ar char Oc Ns Op Ar gap
1.1 deraadt 50: .Op Fl l Ar lines
1.24 ! jmc 51: .Op Fl n Ns Oo Ar char Oc Ns Op Ar width
1.16 jmc 52: .Op Fl o Ar offset
1.24 ! jmc 53: .Op Fl s Ns Op Ar char
1.1 deraadt 54: .Op Fl w Ar width
1.20 sobrado 55: .Op Ar
1.1 deraadt 56: .Sh DESCRIPTION
57: The
58: .Nm pr
59: utility is a printing and pagination filter for text files.
60: When multiple input files are specified, each is read, formatted,
61: and written to standard output.
62: By default, the input is separated into 66-line pages, each with
1.11 aaron 63: .Bl -bullet -offset indent
64: .It
65: A 5-line header with the page number, date, time, and
1.1 deraadt 66: the pathname of the file.
1.11 aaron 67: .It
68: A 5-line trailer consisting of blank lines.
69: .El
1.1 deraadt 70: .Pp
1.3 grr 71: Optionally, the trailer can be replaced by a
72: .Em <form-feed>
73: where this is more appropriate for the output device being used and
1.14 deraadt 74: .Em <tab> Ns s
1.3 grr 75: can be expanded to input relative
1.14 deraadt 76: .Em <spaces> Ns s
1.3 grr 77: or
1.14 deraadt 78: .Em <space> Ns s
79: can be contracted to output relative
80: .Em <tab> Ns s .
1.3 grr 81: The
1.1 deraadt 82: .Nm pr
1.3 grr 83: utility also interprets
1.14 deraadt 84: .Em <form-feed> Ns s
85: in the input as the logical end of pages.
1.1 deraadt 86: .Pp
87: When multiple column output is specified,
88: text columns are of equal width.
89: By default text columns are separated by at least one
1.3 grr 90: .Em <blank> .
91: Input lines that do not fit into a text column are truncated, except
92: in the default single columns output mode.
93: .Pp
94: If standard output is associated with a terminal,
95: diagnostic messages are suppressed until the
96: .Nm pr
97: utility has completed processing.
1.12 aaron 98: .Pp
1.3 grr 99: In the following option descriptions,
100: .Em column ,
101: .Em lines ,
102: .Em offset ,
103: .Em page ,
104: and
105: .Em width
106: are positive decimal integers and
107: .Em gap
108: is a non-negative decimal integer.
1.12 aaron 109: .Pp
110: The options are as follows:
1.13 aaron 111: .Bl -tag -width Ds
1.1 deraadt 112: .It Ar \&+page
1.8 aaron 113: Begin output at page number
1.1 deraadt 114: .Ar page
115: of the formatted input.
116: .It Fl Ar column
1.8 aaron 117: Produce output that is
1.14 deraadt 118: .Ar column Ns s
1.1 deraadt 119: wide (default is 1) that is written vertically
120: down each column in the order in which the text
121: is received from the input file.
122: The options
123: .Fl e
124: and
125: .Fl i
126: are assumed.
127: This option should not be used with
128: .Fl m .
129: When used with
130: .Fl t ,
131: the minimum number of lines is used to display the output.
132: .It Fl a
1.8 aaron 133: Modify the effect of the
1.14 deraadt 134: .Fl Ar column
1.1 deraadt 135: option so that the columns are filled across the page in a round-robin order
136: (e.g., when column is 2, the first input line heads column
137: 1, the second heads column 2, the third is the second line
138: in column 1, etc.).
139: This option requires the use of the
1.14 deraadt 140: .Fl Ar column
1.1 deraadt 141: option.
142: .It Fl d
1.11 aaron 143: Produce output that is double spaced.
144: An extra
1.1 deraadt 145: .Em <newline>
1.3 grr 146: character is output following every
147: .Em <newline>
148: found in the input.
1.24 ! jmc 149: .It Fl e Ns Oo Ar char Oc Ns Op Ar gap
1.3 grr 150: Expand each input
151: .Em <tab>
152: to the next greater column
1.8 aaron 153: position specified by the formula
1.1 deraadt 154: .Ar n*gap+1 ,
1.8 aaron 155: where
1.1 deraadt 156: .Em n
157: is an integer > 0.
158: If
159: .Ar gap
160: is zero or is omitted the default is 8.
1.8 aaron 161: All
1.1 deraadt 162: .Em <tab>
163: characters in the input are expanded into the appropriate
164: number of
1.14 deraadt 165: .Em <space> Ns s.
1.1 deraadt 166: If any nondigit character,
167: .Ar char ,
168: is specified, it is used as the input tab character.
169: .It Fl F
170: Use a
171: .Em <form-feed>
172: character for new pages,
173: instead of the default behavior that uses a
174: sequence of
175: .Em <newline>
176: characters.
1.3 grr 177: .It Fl f
178: Same as the
179: .Fl F
180: option.
1.1 deraadt 181: .It Fl h Ar header
1.8 aaron 182: Use the string
1.1 deraadt 183: .Ar header
184: to replace the
185: .Ar file name
186: in the header line.
1.24 ! jmc 187: .It Fl i Ns Oo Ar char Oc Ns Op Ar gap
1.3 grr 188: In output, replace multiple
1.14 deraadt 189: .Em <space> Ns s
1.3 grr 190: with
1.14 deraadt 191: .Em <tab> Ns s
1.3 grr 192: whenever two or more
193: adjacent
1.14 deraadt 194: .Em <space> Ns s
1.3 grr 195: reach column positions
1.1 deraadt 196: .Ar gap+1 ,
197: .Ar 2*gap+1 ,
198: etc.
199: If
200: .Ar gap
201: is zero or omitted, default
202: .Em <tab>
203: settings at every eighth column position
204: is used.
205: If any nondigit character,
206: .Ar char ,
207: is specified, it is used as the output
208: .Em <tab>
209: character.
210: .It Fl l Ar lines
1.8 aaron 211: Override the 66 line default and reset the page length to
1.3 grr 212: .Ar lines .
1.1 deraadt 213: If
214: .Ar lines
215: is not greater than the sum of both the header and trailer
1.8 aaron 216: depths (in lines), the
1.1 deraadt 217: .Nm pr
218: utility suppresses output of both the header and trailer, as if the
219: .Fl t
220: option were in effect.
221: .It Fl m
222: Merge the contents of multiple files.
223: One line from each file specified by a file operand is
224: written side by side into text columns of equal fixed widths, in
225: terms of the number of column positions.
226: The number of text columns depends on the number of
227: file operands successfully opened.
228: The maximum number of files merged depends on page width and the
229: per process open file limit.
230: The options
231: .Fl e
232: and
233: .Fl i
234: are assumed.
1.24 ! jmc 235: .It Fl n Ns Oo Ar char Oc Ns Op Ar width
1.1 deraadt 236: Provide
237: .Ar width
238: digit line numbering.
1.8 aaron 239: The default for
1.1 deraadt 240: .Ar width ,
241: if not specified, is 5.
242: The number occupies the first
243: .Ar width
244: column positions of each text column or each line of
245: .Fl m
246: output.
247: If
248: .Ar char
249: (any nondigit character) is given, it is appended to the line number to
1.11 aaron 250: separate it from whatever follows.
251: The default for
1.1 deraadt 252: .Ar char
253: is a
254: .Em <tab> .
255: Line numbers longer than
256: .Ar width
257: columns are truncated.
258: .It Fl o Ar offset
1.6 aaron 259: Each line of output is preceded by
1.1 deraadt 260: .Ar offset
1.14 deraadt 261: .Em <spaces> Ns s.
1.1 deraadt 262: If the
1.5 deraadt 263: .Fl o
1.1 deraadt 264: option is not specified, the default is zero.
265: The space taken is in addition to the output line width.
266: .It Fl r
267: Write no diagnostic reports on failure to open a file.
1.24 ! jmc 268: .It Fl s Ns Op Ar char
1.1 deraadt 269: Separate text columns by the single character
270: .Ar char
271: instead of by the appropriate number of
1.14 deraadt 272: .Em <space> Ns s
1.8 aaron 273: (default for
1.1 deraadt 274: .Ar char
275: is the
276: .Em <tab>
277: character).
278: .It Fl t
279: Print neither the five-line identifying
280: header nor the five-line trailer usually supplied for each page.
281: Quit printing after the last line of each file without spacing to the
282: end of the page.
283: .It Fl w Ar width
284: Set the width of the line to
285: .Ar width
286: column positions for multiple text-column output only.
287: If the
288: .Fl w
289: option is not specified and the
290: .Fl s
291: option is not specified, the default width is 72.
292: If the
293: .Fl w
294: option is not specified and the
295: .Fl s
296: option is specified, the default width is 512.
297: .It Ar file
298: A pathname of a file to be printed.
299: If no
300: .Ar file
301: operands are specified, or if a
302: .Ar file
303: operand is
1.11 aaron 304: .Dq - ,
1.1 deraadt 305: the standard input is used.
306: The standard input is used only if no
307: .Ar file
308: operands are specified, or if a
309: .Ar file
310: operand is
1.11 aaron 311: .Dq - .
1.1 deraadt 312: .El
313: .Pp
314: The
315: .Fl s
316: option does not allow the option letter to be separated from its
317: argument, and the options
318: .Fl e ,
319: .Fl i ,
320: and
321: .Fl n
322: require that both arguments, if present, not be separated from the option
323: letter.
1.21 jmc 324: .Sh EXIT STATUS
1.23 jmc 325: .Ex -std pr
1.1 deraadt 326: .Pp
327: Error messages are written to standard error during the printing
328: process (if output is redirected) or after all successful
329: file printing is complete (when printing to a terminal).
1.22 jmc 330: .Pp
1.21 jmc 331: If
332: .Nm pr
333: receives an interrupt while printing to a terminal, it
334: flushes all accumulated error messages to the screen before
335: terminating.
1.3 grr 336: .Sh NOTES
337: The interpretation of
1.14 deraadt 338: .Em <form-feed> Ns s
1.3 grr 339: in the input stream is that they are special
1.14 deraadt 340: .Em <newline> Ns s
1.11 aaron 341: which have the side effect of causing a page break.
342: While this works
1.9 alex 343: correctly for all cases, strict interpretation also implies that the
1.3 grr 344: common convention of placing a
345: .Em <form-feed>
346: on a line by itself is actually interpreted as a blank line, page break,
347: blank line.
348: .Sh RESTRICTIONS
349: The
350: .Nm pr
351: utility is intended to paginate input containing basic
352: .Xr ascii 7
353: text formatting and input streams containing non-printing
354: .Em <control-characters> ,
355: .Em <escape-sequences>
356: or long lines may result in formatting errors.
357: .Pp
358: The
359: .Nm pr
360: utility does not currently understand over-printing using
361: .Em <back-space>
362: or
363: .Em <return>
364: characters, and except in the case of unmodified single-column output,
365: use of these characters will cause formatting errors.
1.12 aaron 366: .Sh SEE ALSO
367: .Xr cat 1 ,
368: .Xr more 1 ,
369: .Xr ascii 7
370: .Sh STANDARDS
371: The
1.17 jmc 372: .Nm
373: utility is compliant with the
1.19 jmc 374: .St -p1003.1-2008
1.17 jmc 375: specification.
376: .Pp
1.19 jmc 377: .St -p1003.1-2008
1.17 jmc 378: is relatively silent concerning the
1.12 aaron 379: handling of input characters beyond the behavior dictated by the
380: .Nm pr
381: required command
382: options.
383: .Sh HISTORY
384: A
385: .Nm
386: command appeared in
387: .At v1 .
1.3 grr 388: .Sh BUGS
389: The lack of a line wrapping option, and the specification that truncation
390: does not apply to single-column output frequently results in formatting
391: errors when input lines are longer than actual line width of the output device.
392: .Pp
393: The default width of 72 is archaic and non-obvious since it is normally
1.11 aaron 394: ignored in the default single column mode.
395: Using the
1.3 grr 396: .Fl m
397: option with one column provides a way to truncate single column output but
1.14 deraadt 398: there's no way to wrap long lines to a fixed line width.
1.3 grr 399: .Pp
400: The default of
401: .Em <tab>
402: for the separator for the
403: .Fl n
404: and
405: .Fl s
406: options often results in lines apparently wider than expected.
![[BACK]](/icons/back.gif){kind=icon}
Return to pr.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / pr