Annotation of src/usr.bin/pr/pr.1, Revision 1.1.1.1
1.1 deraadt 1: .\" Copyright (c) 1991 Keith Muller.
2: .\" Copyright (c) 1993
3: .\" The Regents of the University of California. All rights reserved.
4: .\"
5: .\" This code is derived from software contributed to Berkeley by
6: .\" Keith Muller of the University of California, San Diego.
7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
16: .\" 3. All advertising materials mentioning features or use of this software
17: .\" must display the following acknowledgement:
18: .\" This product includes software developed by the University of
19: .\" California, Berkeley and its contributors.
20: .\" 4. Neither the name of the University nor the names of its contributors
21: .\" may be used to endorse or promote products derived from this software
22: .\" without specific prior written permission.
23: .\"
24: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34: .\" SUCH DAMAGE.
35: .\"
36: .\" from: @(#)pr.1 8.1 (Berkeley) 6/6/93
37: .\" $Id: pr.1,v 1.3 1995/09/12 18:47:09 jtc Exp $
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
53: .Op Fl adFmrt
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
112: If standard output is associated with a terminal,
113: diagnostic messages are suppressed until the
114: .Nm pr
115: utility has completed processing.
116: .Pp
117: When multiple column output is specified,
118: text columns are of equal width.
119: By default text columns are separated by at least one
120: .Em <blank>.
121: Input lines that do not fit into a text column are truncated.
122: Lines are not truncated under single column output.
123: .Sh OPTIONS
124: .Pp
125: In the following option descriptions, column, lines, offset, page, and
126: width are positive decimal integers and gap is a nonnegative decimal integer.
127: .Bl -tag -width 4n
128: .It Ar \&+page
129: Begin output at page number
130: .Ar page
131: of the formatted input.
132: .It Fl Ar column
133: Produce output that is
134: .Ar columns
135: wide (default is 1) that is written vertically
136: down each column in the order in which the text
137: is received from the input file.
138: The options
139: .Fl e
140: and
141: .Fl i
142: are assumed.
143: This option should not be used with
144: .Fl m .
145: When used with
146: .Fl t ,
147: the minimum number of lines is used to display the output.
148: .It Fl a
149: Modify the effect of the
150: .Fl column
151: option so that the columns are filled across the page in a round-robin order
152: (e.g., when column is 2, the first input line heads column
153: 1, the second heads column 2, the third is the second line
154: in column 1, etc.).
155: This option requires the use of the
156: .Fl column
157: option.
158: .It Fl d
159: Produce output that is double spaced. An extra
160: .Em <newline>
161: character is output following every <newline> found in the input.
162: .It Fl e Ar \&[char\&]\&[gap\&]
163: Expand each input <tab> to the next greater column
164: position specified by the formula
165: .Ar n*gap+1 ,
166: where
167: .Em n
168: is an integer > 0.
169: If
170: .Ar gap
171: is zero or is omitted the default is 8.
172: All
173: .Em <tab>
174: characters in the input are expanded into the appropriate
175: number of
176: .Em <space>s .
177: If any nondigit character,
178: .Ar char ,
179: is specified, it is used as the input tab character.
180: .It Fl F
181: Use a
182: .Em <form-feed>
183: character for new pages,
184: instead of the default behavior that uses a
185: sequence of
186: .Em <newline>
187: characters.
188: .It Fl h Ar header
189: Use the string
190: .Ar header
191: to replace the
192: .Ar file name
193: in the header line.
194: .It Fl i Ar \&[char\&]\&[gap\&]
195: In output, replace multiple <space>s with <tab>s whenever two or more
196: adjacent <space>s reach column positions
197: .Ar gap+1 ,
198: .Ar 2*gap+1 ,
199: etc.
200: If
201: .Ar gap
202: is zero or omitted, default
203: .Em <tab>
204: settings at every eighth column position
205: is used.
206: If any nondigit character,
207: .Ar char ,
208: is specified, it is used as the output
209: .Em <tab>
210: character.
211: .It Fl l Ar lines
212: Override the 66 line default and reset the page length to
213: .Ar lines.
214: If
215: .Ar lines
216: is not greater than the sum of both the header and trailer
217: depths (in lines), the
218: .Nm pr
219: utility suppresses output of both the header and trailer, as if the
220: .Fl t
221: option were in effect.
222: .It Fl m
223: Merge the contents of multiple files.
224: One line from each file specified by a file operand is
225: written side by side into text columns of equal fixed widths, in
226: terms of the number of column positions.
227: The number of text columns depends on the number of
228: file operands successfully opened.
229: The maximum number of files merged depends on page width and the
230: per process open file limit.
231: The options
232: .Fl e
233: and
234: .Fl i
235: are assumed.
236: .It Fl n Ar \&[char\&]\&[width\&]
237: Provide
238: .Ar width
239: digit line numbering.
240: The default for
241: .Ar width ,
242: if not specified, is 5.
243: The number occupies the first
244: .Ar width
245: column positions of each text column or each line of
246: .Fl m
247: output.
248: If
249: .Ar char
250: (any nondigit character) is given, it is appended to the line number to
251: separate it from whatever follows. The default for
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
259: Each line of output is preceeded by
260: .Ar offset
261: .Em <spaces>s .
262: If the
263: .FL o
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.
268: .It Fl s Ar char
269: Separate text columns by the single character
270: .Ar char
271: instead of by the appropriate number of
272: .Em <space>s
273: (default for
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
304: .Sq Fl ,
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
311: .Sq Fl .
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.
324: .Sh ERRORS
325: .Pp
326: If
327: .Nm pr
328: receives an interrupt while printing to a terminal, it
329: flushes all accumulated error messages to the screen before
330: terminating.
331: .Pp
332: The
333: .Nm pr
334: utility exits 0 on success, and 1 if an error occurs.
335: .Pp
336: Error messages are written to standard error during the printing
337: process (if output is redirected) or after all successful
338: file printing is complete (when printing to a terminal).
339: .Sh SEE ALSO
340: .Xr cat 1 ,
341: .Xr more 1
342: .Sh STANDARDS
343: The
344: .Nm pr
345: utility is
346: .St -p1003.2
347: compatible.