Annotation of src/usr.bin/fmt/fmt.1, Revision 1.16
1.16 ! millert 1: .\" $OpenBSD: fmt.1,v 1.15 2001/11/29 00:33:06 millert Exp $
1.1 deraadt 2: .\"
3: .\" Copyright (c) 1980, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.16 ! millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
30: .\" @(#)fmt.1 8.1 (Berkeley) 6/6/93
31: .\"
32: .Dd June 6, 1993
33: .Dt FMT 1
34: .Os
35: .Sh NAME
36: .Nm fmt
37: .Nd simple text formatter
38: .Sh SYNOPSIS
1.6 aaron 39: .Nm fmt
1.15 millert 40: .Op Fl cmnps
1.4 millert 41: .Op Fl d Ar chars
42: .Op Fl l Ar num
43: .Op Fl t Ar num
1.1 deraadt 44: .Oo
45: .Ar goal
46: .Op Ar maximum
1.10 pjanzen 47: |
48: .Fl Ns Ar width |
49: .Fl w Ar width
1.1 deraadt 50: .Oc
1.10 pjanzen 51: .Op Ar file ...
1.1 deraadt 52: .Sh DESCRIPTION
1.7 aaron 53: .Nm
1.1 deraadt 54: is a simple text formatter which reads the concatenation of input
55: files (or standard input if none are given) and produces on standard
56: output a version of its input with lines as close to the
57: .Ar goal
58: length
1.4 millert 59: as possible without exceeding the
1.5 aaron 60: .Ar maximum .
1.4 millert 61: The
1.1 deraadt 62: .Ar goal
63: length defaults
1.4 millert 64: to 65 and the
65: .Ar maximum
1.14 millert 66: to 10 more than the
67: .Ar goal
68: length.
1.10 pjanzen 69: Alternatively, a single
70: .Ar width
71: parameter can be specified either by prepending a hyphen to it or by using
72: .Fl w .
73: For example,
1.14 millert 74: .Dq Li fmt -w 72 ,
75: .Dq Li fmt -72 ,
1.10 pjanzen 76: and
1.14 millert 77: .Dq Li fmt 72 72
1.10 pjanzen 78: all produce identical output.
1.9 aaron 79: The spacing at the beginning of the input lines is preserved in the output,
80: as are blank lines and interword spacing.
1.10 pjanzen 81: Lines are joined or split only at white space; that is, words are never
82: joined or hyphenated.
1.3 millert 83: .Pp
1.8 aaron 84: The options are as follows:
1.11 aaron 85: .Bl -tag -width Ds
1.4 millert 86: .It Fl c
1.9 aaron 87: Center the text, line by line.
88: In this case, most of the other
1.4 millert 89: options are ignored; no splitting or joining of lines is done.
90: .It Fl m
91: Try to format mail header lines contained in the input sensibly.
1.15 millert 92: .It Fl n
93: Format lines beginning with a
94: .Ql \&.
95: (dot) character.
96: Normally,
97: .Nm
98: does not fill these lines, for compatibility with
99: .Xr troff 1
100: and
101: .Xr nroff 1 .
1.4 millert 102: .It Fl p
1.9 aaron 103: Allow indented paragraphs.
104: Without the
1.4 millert 105: .Fl p
106: flag, any change in the amount of whitespace at the start of a line
107: results in a new paragraph being begun.
108: .It Fl s
109: Collapse whitespace inside lines, so that multiple whitespace
1.14 millert 110: characters are turned into a single space.
111: (Or, at the end of a
1.4 millert 112: sentence, a double space.)
113: .It Fl d Ar chars
114: Treat the
115: .Ar chars
1.9 aaron 116: (and no others) as sentence-ending characters.
117: By default the
1.14 millert 118: sentence-ending characters are full stop
119: .Pq Ql \&. ,
120: question mark
121: .Pq Ql \&?
122: and exclamation mark
123: .Pq Ql \&! .
1.9 aaron 124: Remember that some characters may need to be
1.4 millert 125: escaped to protect them from your shell.
126: .It Fl l Ar number
127: Replace multiple spaces with tabs at the start of each output
128: line, if possible.
129: .Ar number
130: spaces will be replaced with one tab.
131: .It Fl t Ar number
132: Assume that the input files' tabs assume
133: .Ar number
1.9 aaron 134: spaces per tab stop.
135: The default is 8.
1.4 millert 136: .El
1.1 deraadt 137: .Pp
1.7 aaron 138: .Nm
1.1 deraadt 139: is meant to format mail messages prior to sending, but may also be useful
140: for other simple tasks.
141: For instance,
142: within visual mode of the
143: .Xr ex 1
1.7 aaron 144: editor (e.g.,
1.1 deraadt 145: .Xr vi 1 )
146: the command
147: .Pp
148: .Dl \&!}fmt
149: .Pp
150: will reformat a paragraph,
151: evening the lines.
152: .Sh SEE ALSO
1.4 millert 153: .Xr mail 1 ,
1.15 millert 154: .Xr nroff 1 ,
155: .Xr troff 1
1.1 deraadt 156: .Sh HISTORY
1.14 millert 157: The
1.4 millert 158: .Nm
1.1 deraadt 159: command appeared in
160: .Bx 3 .
1.4 millert 161: .Pp
162: The version described herein is a complete rewrite and appeared in
1.9 aaron 163: .Ox 2.4 .
1.14 millert 164: .Sh AUTHORS
165: .An Kurt Shoens
166: .An Liz Allen
167: (added goal length concept)
168: .An Gareth McCaughan
169: (wrote this version)
1.1 deraadt 170: .Sh BUGS
171: The program was designed to be simple and fast \- for more complex
172: operations, the standard text processors are likely to be more appropriate.
1.4 millert 173: .Pp
174: When the first line of an indented paragraph is very long (more than
175: about twice the goal length), the indentation in the output can be
176: wrong.
177: .Pp
178: .Nm
179: is not infallible in guessing what lines are mail headers and what
180: lines are not.