Annotation of src/usr.bin/pr/pr.1, Revision 1.14
1.14 ! deraadt 1: .\" $OpenBSD: pr.1,v 1.13 2000/11/09 17:52:30 aaron 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.
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
1.14 ! deraadt 114: .Em <tab> Ns s
1.3 grr 115: can be expanded to input relative
1.14 ! deraadt 116: .Em <spaces> Ns s
1.3 grr 117: or
1.14 ! deraadt 118: .Em <space> Ns s
! 119: can be contracted to output relative
! 120: .Em <tab> Ns s .
1.3 grr 121: The
1.1 deraadt 122: .Nm pr
1.3 grr 123: utility also interprets
1.14 ! deraadt 124: .Em <form-feed> Ns s
! 125: in the input as the 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.12 aaron 138: .Pp
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.12 aaron 149: .Pp
150: The options are as follows:
1.13 aaron 151: .Bl -tag -width Ds
1.1 deraadt 152: .It Ar \&+page
1.8 aaron 153: Begin output at page number
1.1 deraadt 154: .Ar page
155: of the formatted input.
156: .It Fl Ar column
1.8 aaron 157: Produce output that is
1.14 ! deraadt 158: .Ar column Ns s
1.1 deraadt 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
1.8 aaron 173: Modify the effect of the
1.14 ! deraadt 174: .Fl Ar column
1.1 deraadt 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
1.14 ! deraadt 180: .Fl Ar column
1.1 deraadt 181: option.
182: .It Fl d
1.11 aaron 183: Produce output that is double spaced.
184: An extra
1.1 deraadt 185: .Em <newline>
1.3 grr 186: character is output following every
187: .Em <newline>
188: found in the input.
1.1 deraadt 189: .It Fl e Ar \&[char\&]\&[gap\&]
1.3 grr 190: Expand each input
191: .Em <tab>
192: to the next greater column
1.8 aaron 193: position specified by the formula
1.1 deraadt 194: .Ar n*gap+1 ,
1.8 aaron 195: where
1.1 deraadt 196: .Em n
197: is an integer > 0.
198: If
199: .Ar gap
200: is zero or is omitted the default is 8.
1.8 aaron 201: All
1.1 deraadt 202: .Em <tab>
203: characters in the input are expanded into the appropriate
204: number of
1.14 ! deraadt 205: .Em <space> Ns s.
1.1 deraadt 206: If any nondigit character,
207: .Ar char ,
208: is specified, it is used as the input tab character.
209: .It Fl F
210: Use a
211: .Em <form-feed>
212: character for new pages,
213: instead of the default behavior that uses a
214: sequence of
215: .Em <newline>
216: characters.
1.3 grr 217: .It Fl f
218: Same as the
219: .Fl F
220: option.
1.1 deraadt 221: .It Fl h Ar header
1.8 aaron 222: Use the string
1.1 deraadt 223: .Ar header
224: to replace the
225: .Ar file name
226: in the header line.
227: .It Fl i Ar \&[char\&]\&[gap\&]
1.3 grr 228: In output, replace multiple
1.14 ! deraadt 229: .Em <space> Ns s
1.3 grr 230: with
1.14 ! deraadt 231: .Em <tab> Ns s
1.3 grr 232: whenever two or more
233: adjacent
1.14 ! deraadt 234: .Em <space> Ns s
1.3 grr 235: reach column positions
1.1 deraadt 236: .Ar gap+1 ,
237: .Ar 2*gap+1 ,
238: etc.
239: If
240: .Ar gap
241: is zero or omitted, default
242: .Em <tab>
243: settings at every eighth column position
244: is used.
245: If any nondigit character,
246: .Ar char ,
247: is specified, it is used as the output
248: .Em <tab>
249: character.
250: .It Fl l Ar lines
1.8 aaron 251: Override the 66 line default and reset the page length to
1.3 grr 252: .Ar lines .
1.1 deraadt 253: If
254: .Ar lines
255: is not greater than the sum of both the header and trailer
1.8 aaron 256: depths (in lines), the
1.1 deraadt 257: .Nm pr
258: utility suppresses output of both the header and trailer, as if the
259: .Fl t
260: option were in effect.
261: .It Fl m
262: Merge the contents of multiple files.
263: One line from each file specified by a file operand is
264: written side by side into text columns of equal fixed widths, in
265: terms of the number of column positions.
266: The number of text columns depends on the number of
267: file operands successfully opened.
268: The maximum number of files merged depends on page width and the
269: per process open file limit.
270: The options
271: .Fl e
272: and
273: .Fl i
274: are assumed.
275: .It Fl n Ar \&[char\&]\&[width\&]
276: Provide
277: .Ar width
278: digit line numbering.
1.8 aaron 279: The default for
1.1 deraadt 280: .Ar width ,
281: if not specified, is 5.
282: The number occupies the first
283: .Ar width
284: column positions of each text column or each line of
285: .Fl m
286: output.
287: If
288: .Ar char
289: (any nondigit character) is given, it is appended to the line number to
1.11 aaron 290: separate it from whatever follows.
291: The default for
1.1 deraadt 292: .Ar char
293: is a
294: .Em <tab> .
295: Line numbers longer than
296: .Ar width
297: columns are truncated.
298: .It Fl o Ar offset
1.6 aaron 299: Each line of output is preceded by
1.1 deraadt 300: .Ar offset
1.14 ! deraadt 301: .Em <spaces> Ns s.
1.1 deraadt 302: If the
1.5 deraadt 303: .Fl o
1.1 deraadt 304: option is not specified, the default is zero.
305: The space taken is in addition to the output line width.
306: .It Fl r
307: Write no diagnostic reports on failure to open a file.
308: .It Fl s Ar char
309: Separate text columns by the single character
310: .Ar char
311: instead of by the appropriate number of
1.14 ! deraadt 312: .Em <space> Ns s
1.8 aaron 313: (default for
1.1 deraadt 314: .Ar char
315: is the
316: .Em <tab>
317: character).
318: .It Fl t
319: Print neither the five-line identifying
320: header nor the five-line trailer usually supplied for each page.
321: Quit printing after the last line of each file without spacing to the
322: end of the page.
323: .It Fl w Ar width
324: Set the width of the line to
325: .Ar width
326: column positions for multiple text-column output only.
327: If the
328: .Fl w
329: option is not specified and the
330: .Fl s
331: option is not specified, the default width is 72.
332: If the
333: .Fl w
334: option is not specified and the
335: .Fl s
336: option is specified, the default width is 512.
337: .It Ar file
338: A pathname of a file to be printed.
339: If no
340: .Ar file
341: operands are specified, or if a
342: .Ar file
343: operand is
1.11 aaron 344: .Dq - ,
1.1 deraadt 345: the standard input is used.
346: The standard input is used only if no
347: .Ar file
348: operands are specified, or if a
349: .Ar file
350: operand is
1.11 aaron 351: .Dq - .
1.1 deraadt 352: .El
353: .Pp
354: The
355: .Fl s
356: option does not allow the option letter to be separated from its
357: argument, and the options
358: .Fl e ,
359: .Fl i ,
360: and
361: .Fl n
362: require that both arguments, if present, not be separated from the option
363: letter.
364: .Sh ERRORS
365: If
366: .Nm pr
367: receives an interrupt while printing to a terminal, it
368: flushes all accumulated error messages to the screen before
369: terminating.
370: .Pp
371: The
372: .Nm pr
373: utility exits 0 on success, and 1 if an error occurs.
374: .Pp
375: Error messages are written to standard error during the printing
376: process (if output is redirected) or after all successful
377: file printing is complete (when printing to a terminal).
1.3 grr 378: .Sh NOTES
379: The interpretation of
1.14 ! deraadt 380: .Em <form-feed> Ns s
1.3 grr 381: in the input stream is that they are special
1.14 ! deraadt 382: .Em <newline> Ns s
1.11 aaron 383: which have the side effect of causing a page break.
384: While this works
1.9 alex 385: correctly for all cases, strict interpretation also implies that the
1.3 grr 386: common convention of placing a
387: .Em <form-feed>
388: on a line by itself is actually interpreted as a blank line, page break,
389: blank line.
390: .Sh RESTRICTIONS
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.
1.12 aaron 408: .Sh SEE ALSO
409: .Xr cat 1 ,
410: .Xr more 1 ,
411: .Xr ascii 7
412: .Sh STANDARDS
413: The
414: .Nm pr
415: utility is
416: .St -p1003.2
417: compatible; however, that standard is relatively silent concerning the
418: handling of input characters beyond the behavior dictated by the
419: .Nm pr
420: required command
421: options.
422: .Sh HISTORY
423: A
424: .Nm
425: command appeared in
426: .At v1 .
1.3 grr 427: .Sh BUGS
428: The lack of a line wrapping option, and the specification that truncation
429: does not apply to single-column output frequently results in formatting
430: errors when input lines are longer than actual line width of the output device.
431: .Pp
432: The default width of 72 is archaic and non-obvious since it is normally
1.11 aaron 433: ignored in the default single column mode.
434: Using the
1.3 grr 435: .Fl m
436: option with one column provides a way to truncate single column output but
1.14 ! deraadt 437: there's no way to wrap long lines to a fixed line width.
1.3 grr 438: .Pp
439: The default of
440: .Em <tab>
441: for the separator for the
442: .Fl n
443: and
444: .Fl s
445: 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