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