Annotation of src/usr.bin/pr/pr.1, Revision 1.26
1.26 ! jmc 1: .\" $OpenBSD: pr.1,v 1.25 2014/04/18 22:11:57 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.26 ! jmc 36: .Dd $Mdocdate: April 18 2014 $
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
1.25 jmc 44: .Op Cm + Ns Ar page
1.1 deraadt 45: .Op Fl Ar column
1.16 jmc 46: .Op Fl adFfmrt
1.24 jmc 47: .Op Fl e Ns Oo Ar char Oc Ns Op Ar gap
1.1 deraadt 48: .Op Fl h Ar header
1.24 jmc 49: .Op Fl i Ns Oo Ar char Oc Ns Op Ar gap
1.1 deraadt 50: .Op Fl l Ar lines
1.24 jmc 51: .Op Fl n Ns Oo Ar char Oc Ns Op Ar width
1.16 jmc 52: .Op Fl o Ar offset
1.24 jmc 53: .Op Fl s Ns Op Ar char
1.1 deraadt 54: .Op Fl w Ar width
1.20 sobrado 55: .Op Ar
1.1 deraadt 56: .Sh DESCRIPTION
57: The
58: .Nm pr
59: utility is a printing and pagination filter for text files.
60: When multiple input files are specified, each is read, formatted,
61: and written to standard output.
62: By default, the input is separated into 66-line pages, each with
1.11 aaron 63: .Bl -bullet -offset indent
64: .It
65: A 5-line header with the page number, date, time, and
1.1 deraadt 66: the pathname of the file.
1.11 aaron 67: .It
68: A 5-line trailer consisting of blank lines.
69: .El
1.1 deraadt 70: .Pp
1.3 grr 71: Optionally, the trailer can be replaced by a
72: .Em <form-feed>
73: where this is more appropriate for the output device being used and
1.14 deraadt 74: .Em <tab> Ns s
1.3 grr 75: can be expanded to input relative
1.14 deraadt 76: .Em <spaces> Ns s
1.3 grr 77: or
1.14 deraadt 78: .Em <space> Ns s
79: can be contracted to output relative
80: .Em <tab> Ns s .
1.3 grr 81: The
1.1 deraadt 82: .Nm pr
1.3 grr 83: utility also interprets
1.14 deraadt 84: .Em <form-feed> Ns s
85: in the input as the logical end of pages.
1.1 deraadt 86: .Pp
87: When multiple column output is specified,
88: text columns are of equal width.
89: By default text columns are separated by at least one
1.3 grr 90: .Em <blank> .
91: Input lines that do not fit into a text column are truncated, except
92: in the default single columns output mode.
93: .Pp
1.25 jmc 94: Error messages are written to standard error during the printing
95: process (if output is redirected) or after all successful
96: file printing is complete (when printing to a terminal).
97: If
1.3 grr 98: .Nm pr
1.25 jmc 99: receives an interrupt while printing to a terminal, it
100: flushes all accumulated error messages to the screen before
101: terminating.
1.12 aaron 102: .Pp
103: The options are as follows:
1.13 aaron 104: .Bl -tag -width Ds
1.25 jmc 105: .It Cm + Ns Ar page
1.8 aaron 106: Begin output at page number
1.1 deraadt 107: .Ar page
108: of the formatted input.
109: .It Fl Ar column
1.8 aaron 110: Produce output that is
1.14 deraadt 111: .Ar column Ns s
1.1 deraadt 112: wide (default is 1) that is written vertically
113: down each column in the order in which the text
114: is received from the input file.
115: The options
116: .Fl e
117: and
118: .Fl i
119: are assumed.
120: This option should not be used with
121: .Fl m .
122: When used with
123: .Fl t ,
124: the minimum number of lines is used to display the output.
125: .It Fl a
1.8 aaron 126: Modify the effect of the
1.14 deraadt 127: .Fl Ar column
1.1 deraadt 128: option so that the columns are filled across the page in a round-robin order
129: (e.g., when column is 2, the first input line heads column
130: 1, the second heads column 2, the third is the second line
131: in column 1, etc.).
132: This option requires the use of the
1.14 deraadt 133: .Fl Ar column
1.1 deraadt 134: option.
135: .It Fl d
1.11 aaron 136: Produce output that is double spaced.
137: An extra
1.1 deraadt 138: .Em <newline>
1.3 grr 139: character is output following every
140: .Em <newline>
141: found in the input.
1.24 jmc 142: .It Fl e Ns Oo Ar char Oc Ns Op Ar gap
1.3 grr 143: Expand each input
144: .Em <tab>
145: to the next greater column
1.8 aaron 146: position specified by the formula
1.1 deraadt 147: .Ar n*gap+1 ,
1.8 aaron 148: where
1.1 deraadt 149: .Em n
150: is an integer > 0.
151: If
152: .Ar gap
153: is zero or is omitted the default is 8.
1.8 aaron 154: All
1.1 deraadt 155: .Em <tab>
156: characters in the input are expanded into the appropriate
157: number of
1.14 deraadt 158: .Em <space> Ns s.
1.1 deraadt 159: If any nondigit character,
160: .Ar char ,
161: is specified, it is used as the input tab character.
162: .It Fl F
163: Use a
164: .Em <form-feed>
165: character for new pages,
166: instead of the default behavior that uses a
167: sequence of
168: .Em <newline>
169: characters.
1.3 grr 170: .It Fl f
171: Same as the
172: .Fl F
173: option.
1.1 deraadt 174: .It Fl h Ar header
1.8 aaron 175: Use the string
1.1 deraadt 176: .Ar header
177: to replace the
178: .Ar file name
179: in the header line.
1.24 jmc 180: .It Fl i Ns Oo Ar char Oc Ns Op Ar gap
1.3 grr 181: In output, replace multiple
1.14 deraadt 182: .Em <space> Ns s
1.3 grr 183: with
1.14 deraadt 184: .Em <tab> Ns s
1.3 grr 185: whenever two or more
186: adjacent
1.14 deraadt 187: .Em <space> Ns s
1.3 grr 188: reach column positions
1.1 deraadt 189: .Ar gap+1 ,
190: .Ar 2*gap+1 ,
191: etc.
192: If
193: .Ar gap
194: is zero or omitted, default
195: .Em <tab>
196: settings at every eighth column position
197: is used.
198: If any nondigit character,
199: .Ar char ,
200: is specified, it is used as the output
201: .Em <tab>
202: character.
203: .It Fl l Ar lines
1.8 aaron 204: Override the 66 line default and reset the page length to
1.3 grr 205: .Ar lines .
1.1 deraadt 206: If
207: .Ar lines
208: is not greater than the sum of both the header and trailer
1.8 aaron 209: depths (in lines), the
1.1 deraadt 210: .Nm pr
211: utility suppresses output of both the header and trailer, as if the
212: .Fl t
213: option were in effect.
214: .It Fl m
215: Merge the contents of multiple files.
216: One line from each file specified by a file operand is
217: written side by side into text columns of equal fixed widths, in
218: terms of the number of column positions.
219: The number of text columns depends on the number of
220: file operands successfully opened.
221: The maximum number of files merged depends on page width and the
222: per process open file limit.
223: The options
224: .Fl e
225: and
226: .Fl i
227: are assumed.
1.24 jmc 228: .It Fl n Ns Oo Ar char Oc Ns Op Ar width
1.1 deraadt 229: Provide
230: .Ar width
231: digit line numbering.
1.8 aaron 232: The default for
1.1 deraadt 233: .Ar width ,
234: if not specified, is 5.
235: The number occupies the first
236: .Ar width
237: column positions of each text column or each line of
238: .Fl m
239: output.
240: If
241: .Ar char
242: (any nondigit character) is given, it is appended to the line number to
1.11 aaron 243: separate it from whatever follows.
244: The default for
1.1 deraadt 245: .Ar char
246: is a
247: .Em <tab> .
248: Line numbers longer than
249: .Ar width
250: columns are truncated.
251: .It Fl o Ar offset
1.6 aaron 252: Each line of output is preceded by
1.1 deraadt 253: .Ar offset
1.14 deraadt 254: .Em <spaces> Ns s.
1.1 deraadt 255: If the
1.5 deraadt 256: .Fl o
1.1 deraadt 257: option is not specified, the default is zero.
258: The space taken is in addition to the output line width.
259: .It Fl r
260: Write no diagnostic reports on failure to open a file.
1.24 jmc 261: .It Fl s Ns Op Ar char
1.1 deraadt 262: Separate text columns by the single character
263: .Ar char
264: instead of by the appropriate number of
1.14 deraadt 265: .Em <space> Ns s
1.8 aaron 266: (default for
1.1 deraadt 267: .Ar char
268: is the
269: .Em <tab>
270: character).
271: .It Fl t
272: Print neither the five-line identifying
273: header nor the five-line trailer usually supplied for each page.
274: Quit printing after the last line of each file without spacing to the
275: end of the page.
276: .It Fl w Ar width
277: Set the width of the line to
278: .Ar width
279: column positions for multiple text-column output only.
280: If the
281: .Fl w
282: option is not specified and the
283: .Fl s
284: option is not specified, the default width is 72.
285: If the
286: .Fl w
287: option is not specified and the
288: .Fl s
289: option is specified, the default width is 512.
290: .It Ar file
291: A pathname of a file to be printed.
292: If no
293: .Ar file
294: operands are specified, or if a
295: .Ar file
296: operand is
1.25 jmc 297: .Sq - ,
1.1 deraadt 298: the standard input is used.
299: The standard input is used only if no
300: .Ar file
301: operands are specified, or if a
302: .Ar file
303: operand is
1.25 jmc 304: .Sq - .
1.1 deraadt 305: .El
1.21 jmc 306: .Sh EXIT STATUS
1.23 jmc 307: .Ex -std pr
1.25 jmc 308: .Sh SEE ALSO
309: .Xr cat 1 ,
310: .Xr more 1 ,
311: .Xr ascii 7
312: .Sh STANDARDS
313: The
314: .Nm
315: utility is compliant with the
316: .St -p1003.1-2008
1.26 ! jmc 317: specification,
! 318: except that the
! 319: .Ev TZ
! 320: environment variable is unsupported.
! 321: .Pp
! 322: The flag
! 323: .Op Fl f
! 324: is marked by
! 325: .St -p1003.1-2008
! 326: as being an
! 327: X/Open System Interfaces
! 328: option.
1.1 deraadt 329: .Pp
1.25 jmc 330: .St -p1003.1-2008
331: is relatively silent concerning the
332: handling of input characters beyond the behavior dictated by the
1.21 jmc 333: .Nm pr
1.25 jmc 334: required command
335: options.
336: .Sh HISTORY
337: A
338: .Nm
339: command appeared in
340: .At v1 .
341: .Sh CAVEATS
1.3 grr 342: The interpretation of
1.14 deraadt 343: .Em <form-feed> Ns s
1.3 grr 344: in the input stream is that they are special
1.14 deraadt 345: .Em <newline> Ns s
1.11 aaron 346: which have the side effect of causing a page break.
347: While this works
1.9 alex 348: correctly for all cases, strict interpretation also implies that the
1.3 grr 349: common convention of placing a
350: .Em <form-feed>
351: on a line by itself is actually interpreted as a blank line, page break,
352: blank line.
1.25 jmc 353: .Pp
1.3 grr 354: The
355: .Nm pr
356: utility is intended to paginate input containing basic
357: .Xr ascii 7
358: text formatting and input streams containing non-printing
359: .Em <control-characters> ,
360: .Em <escape-sequences>
361: or long lines may result in formatting errors.
362: .Pp
363: The
364: .Nm pr
365: utility does not currently understand over-printing using
366: .Em <back-space>
367: or
368: .Em <return>
369: characters, and except in the case of unmodified single-column output,
370: use of these characters will cause formatting errors.
371: .Sh BUGS
372: The lack of a line wrapping option, and the specification that truncation
373: does not apply to single-column output frequently results in formatting
374: errors when input lines are longer than actual line width of the output device.
375: .Pp
376: The default width of 72 is archaic and non-obvious since it is normally
1.11 aaron 377: ignored in the default single column mode.
378: Using the
1.3 grr 379: .Fl m
380: option with one column provides a way to truncate single column output but
1.14 deraadt 381: there's no way to wrap long lines to a fixed line width.
1.3 grr 382: .Pp
383: The default of
384: .Em <tab>
385: for the separator for the
386: .Fl n
387: and
388: .Fl s
389: 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