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