Annotation of src/usr.bin/pr/pr.1, Revision 1.23
1.23 ! jmc 1: .\" $OpenBSD: pr.1,v 1.22 2010/09/29 07:44:56 jmc 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: .\"
1.23 ! jmc 36: .Dd $Mdocdate: September 29 2010 $
1.1 deraadt 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 -
1.20 sobrado 76: .Op Ar
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.
1.21 jmc 355: .Sh EXIT STATUS
1.23 ! jmc 356: .Ex -std pr
1.1 deraadt 357: .Pp
358: Error messages are written to standard error during the printing
359: process (if output is redirected) or after all successful
360: file printing is complete (when printing to a terminal).
1.22 jmc 361: .Pp
1.21 jmc 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.
1.3 grr 367: .Sh NOTES
368: The interpretation of
1.14 deraadt 369: .Em <form-feed> Ns s
1.3 grr 370: in the input stream is that they are special
1.14 deraadt 371: .Em <newline> Ns s
1.11 aaron 372: which have the side effect of causing a page break.
373: While this works
1.9 alex 374: correctly for all cases, strict interpretation also implies that the
1.3 grr 375: common convention of placing a
376: .Em <form-feed>
377: on a line by itself is actually interpreted as a blank line, page break,
378: blank line.
379: .Sh RESTRICTIONS
380: The
381: .Nm pr
382: utility is intended to paginate input containing basic
383: .Xr ascii 7
384: text formatting and input streams containing non-printing
385: .Em <control-characters> ,
386: .Em <escape-sequences>
387: or long lines may result in formatting errors.
388: .Pp
389: The
390: .Nm pr
391: utility does not currently understand over-printing using
392: .Em <back-space>
393: or
394: .Em <return>
395: characters, and except in the case of unmodified single-column output,
396: use of these characters will cause formatting errors.
1.12 aaron 397: .Sh SEE ALSO
398: .Xr cat 1 ,
399: .Xr more 1 ,
400: .Xr ascii 7
401: .Sh STANDARDS
402: The
1.17 jmc 403: .Nm
404: utility is compliant with the
1.19 jmc 405: .St -p1003.1-2008
1.17 jmc 406: specification.
407: .Pp
1.19 jmc 408: .St -p1003.1-2008
1.17 jmc 409: is relatively silent concerning the
1.12 aaron 410: handling of input characters beyond the behavior dictated by the
411: .Nm pr
412: required command
413: options.
414: .Sh HISTORY
415: A
416: .Nm
417: command appeared in
418: .At v1 .
1.3 grr 419: .Sh BUGS
420: The lack of a line wrapping option, and the specification that truncation
421: does not apply to single-column output frequently results in formatting
422: errors when input lines are longer than actual line width of the output device.
423: .Pp
424: The default width of 72 is archaic and non-obvious since it is normally
1.11 aaron 425: ignored in the default single column mode.
426: Using the
1.3 grr 427: .Fl m
428: option with one column provides a way to truncate single column output but
1.14 deraadt 429: there's no way to wrap long lines to a fixed line width.
1.3 grr 430: .Pp
431: The default of
432: .Em <tab>
433: for the separator for the
434: .Fl n
435: and
436: .Fl s
437: 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