Annotation of src/usr.bin/pr/pr.1, Revision 1.7
1.7 ! pjanzen 1: .\" $OpenBSD: pr.1,v 1.6 1998/09/27 16:57:50 aaron 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
1.6 aaron 121: .Em <tab>s .
1.3 grr 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
1.3 grr 140: In the following option descriptions,
141: .Em column ,
142: .Em lines ,
143: .Em offset ,
144: .Em page ,
145: and
146: .Em width
147: are positive decimal integers and
148: .Em gap
149: is a non-negative decimal integer.
1.1 deraadt 150: .Bl -tag -width 4n
151: .It Ar \&+page
152: Begin output at page number
153: .Ar page
154: of the formatted input.
155: .It Fl Ar column
156: Produce output that is
157: .Ar columns
158: wide (default is 1) that is written vertically
159: down each column in the order in which the text
160: is received from the input file.
161: The options
162: .Fl e
163: and
164: .Fl i
165: are assumed.
166: This option should not be used with
167: .Fl m .
168: When used with
169: .Fl t ,
170: the minimum number of lines is used to display the output.
171: .It Fl a
172: Modify the effect of the
173: .Fl column
174: option so that the columns are filled across the page in a round-robin order
175: (e.g., when column is 2, the first input line heads column
176: 1, the second heads column 2, the third is the second line
177: in column 1, etc.).
178: This option requires the use of the
179: .Fl column
180: option.
181: .It Fl d
182: Produce output that is double spaced. An extra
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.1 deraadt 191: position specified by the formula
192: .Ar n*gap+1 ,
193: where
194: .Em n
195: is an integer > 0.
196: If
197: .Ar gap
198: is zero or is omitted the default is 8.
199: All
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
220: Use the string
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
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
254: depths (in lines), the
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.
277: The default for
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
288: separate it from whatever follows. The default for
289: .Ar char
290: is a
291: .Em <tab> .
292: Line numbers longer than
293: .Ar width
294: columns are truncated.
295: .It Fl o Ar offset
1.6 aaron 296: Each line of output is preceded by
1.1 deraadt 297: .Ar offset
298: .Em <spaces>s .
299: If the
1.5 deraadt 300: .Fl o
1.1 deraadt 301: option is not specified, the default is zero.
302: The space taken is in addition to the output line width.
303: .It Fl r
304: Write no diagnostic reports on failure to open a file.
305: .It Fl s Ar char
306: Separate text columns by the single character
307: .Ar char
308: instead of by the appropriate number of
309: .Em <space>s
310: (default for
311: .Ar char
312: is the
313: .Em <tab>
314: character).
315: .It Fl t
316: Print neither the five-line identifying
317: header nor the five-line trailer usually supplied for each page.
318: Quit printing after the last line of each file without spacing to the
319: end of the page.
320: .It Fl w Ar width
321: Set the width of the line to
322: .Ar width
323: column positions for multiple text-column output only.
324: If the
325: .Fl w
326: option is not specified and the
327: .Fl s
328: option is not specified, the default width is 72.
329: If the
330: .Fl w
331: option is not specified and the
332: .Fl s
333: option is specified, the default width is 512.
334: .It Ar file
335: A pathname of a file to be printed.
336: If no
337: .Ar file
338: operands are specified, or if a
339: .Ar file
340: operand is
341: .Sq Fl ,
342: the standard input is used.
343: The standard input is used only if no
344: .Ar file
345: operands are specified, or if a
346: .Ar file
347: operand is
348: .Sq Fl .
349: .El
350: .Pp
351: The
352: .Fl s
353: option does not allow the option letter to be separated from its
354: argument, and the options
355: .Fl e ,
356: .Fl i ,
357: and
358: .Fl n
359: require that both arguments, if present, not be separated from the option
360: letter.
361: .Sh ERRORS
362: If
363: .Nm pr
364: receives an interrupt while printing to a terminal, it
365: flushes all accumulated error messages to the screen before
366: terminating.
367: .Pp
368: The
369: .Nm pr
370: utility exits 0 on success, and 1 if an error occurs.
371: .Pp
372: Error messages are written to standard error during the printing
373: process (if output is redirected) or after all successful
374: file printing is complete (when printing to a terminal).
1.3 grr 375: .Sh NOTES
376: The interpretation of
377: .Em <form-feed>s
378: in the input stream is that they are special
379: .Em <newline>s
380: which have the side effect of causing a page break. While this works
381: correctly for all cases, strict interpretataion also implies that the
382: common convention of placing a
383: .Em <form-feed>
384: on a line by itself is actually interpreted as a blank line, page break,
385: blank line.
386: .Sh RESTRICTIONS
387: The
388: .Nm pr
389: utility is intended to paginate input containing basic
390: .Xr ascii 7
391: text formatting and input streams containing non-printing
392: .Em <control-characters> ,
393: .Em <escape-sequences>
394: or long lines may result in formatting errors.
395: .Pp
396: The
397: .Nm pr
398: utility does not currently understand over-printing using
399: .Em <back-space>
400: or
401: .Em <return>
402: characters, and except in the case of unmodified single-column output,
403: use of these characters will cause formatting errors.
404: .Sh BUGS
405: The lack of a line wrapping option, and the specification that truncation
406: does not apply to single-column output frequently results in formatting
407: errors when input lines are longer than actual line width of the output device.
408: .Pp
409: The default width of 72 is archaic and non-obvious since it is normally
410: ignored in the default single column mode. Using the
411: .Fl m
412: option with one column provides a way to truncate single column output but
413: there's no way to wrap long times to a fixed line width.
414: .Pp
415: The default of
416: .Em <tab>
417: for the separator for the
418: .Fl n
419: and
420: .Fl s
421: options often results in lines apparently wider than expected.
1.1 deraadt 422: .Sh SEE ALSO
423: .Xr cat 1 ,
1.3 grr 424: .Xr more 1 ,
425: .Xr ascii 7
1.1 deraadt 426: .Sh STANDARDS
427: The
428: .Nm pr
429: utility is
430: .St -p1003.2
1.7 ! pjanzen 431: compatible; however, that standard is relatively silent concerning the
1.3 grr 432: handling of input characters beyond the behavior dictated by the
433: .Nm pr
434: required command
435: 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