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