Annotation of src/usr.bin/fmt/fmt.1, Revision 1.15
1.15 ! millert 1: .\" $OpenBSD: fmt.1,v 1.14 2001/11/28 22:09:28 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.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
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: .\" @(#)fmt.1 8.1 (Berkeley) 6/6/93
35: .\"
36: .Dd June 6, 1993
37: .Dt FMT 1
38: .Os
39: .Sh NAME
40: .Nm fmt
41: .Nd simple text formatter
42: .Sh SYNOPSIS
1.6 aaron 43: .Nm fmt
1.15 ! millert 44: .Op Fl cmnps
1.4 millert 45: .Op Fl d Ar chars
46: .Op Fl l Ar num
47: .Op Fl t Ar num
1.1 deraadt 48: .Oo
49: .Ar goal
50: .Op Ar maximum
1.10 pjanzen 51: |
52: .Fl Ns Ar width |
53: .Fl w Ar width
1.1 deraadt 54: .Oc
1.10 pjanzen 55: .Op Ar file ...
1.1 deraadt 56: .Sh DESCRIPTION
1.7 aaron 57: .Nm
1.1 deraadt 58: is a simple text formatter which reads the concatenation of input
59: files (or standard input if none are given) and produces on standard
60: output a version of its input with lines as close to the
61: .Ar goal
62: length
1.4 millert 63: as possible without exceeding the
1.5 aaron 64: .Ar maximum .
1.4 millert 65: The
1.1 deraadt 66: .Ar goal
67: length defaults
1.4 millert 68: to 65 and the
69: .Ar maximum
1.14 millert 70: to 10 more than the
71: .Ar goal
72: length.
1.10 pjanzen 73: Alternatively, a single
74: .Ar width
75: parameter can be specified either by prepending a hyphen to it or by using
76: .Fl w .
77: For example,
1.14 millert 78: .Dq Li fmt -w 72 ,
79: .Dq Li fmt -72 ,
1.10 pjanzen 80: and
1.14 millert 81: .Dq Li fmt 72 72
1.10 pjanzen 82: all produce identical output.
1.9 aaron 83: The spacing at the beginning of the input lines is preserved in the output,
84: as are blank lines and interword spacing.
1.10 pjanzen 85: Lines are joined or split only at white space; that is, words are never
86: joined or hyphenated.
1.3 millert 87: .Pp
1.8 aaron 88: The options are as follows:
1.11 aaron 89: .Bl -tag -width Ds
1.4 millert 90: .It Fl c
1.9 aaron 91: Center the text, line by line.
92: In this case, most of the other
1.4 millert 93: options are ignored; no splitting or joining of lines is done.
94: .It Fl m
95: Try to format mail header lines contained in the input sensibly.
1.15 ! millert 96: .It Fl n
! 97: Format lines beginning with a
! 98: .Ql \&.
! 99: (dot) character.
! 100: Normally,
! 101: .Nm
! 102: does not fill these lines, for compatibility with
! 103: .Xr troff 1
! 104: and
! 105: .Xr nroff 1 .
1.4 millert 106: .It Fl p
1.9 aaron 107: Allow indented paragraphs.
108: Without the
1.4 millert 109: .Fl p
110: flag, any change in the amount of whitespace at the start of a line
111: results in a new paragraph being begun.
112: .It Fl s
113: Collapse whitespace inside lines, so that multiple whitespace
1.14 millert 114: characters are turned into a single space.
115: (Or, at the end of a
1.4 millert 116: sentence, a double space.)
117: .It Fl d Ar chars
118: Treat the
119: .Ar chars
1.9 aaron 120: (and no others) as sentence-ending characters.
121: By default the
1.14 millert 122: sentence-ending characters are full stop
123: .Pq Ql \&. ,
124: question mark
125: .Pq Ql \&?
126: and exclamation mark
127: .Pq Ql \&! .
1.9 aaron 128: Remember that some characters may need to be
1.4 millert 129: escaped to protect them from your shell.
130: .It Fl l Ar number
131: Replace multiple spaces with tabs at the start of each output
132: line, if possible.
133: .Ar number
134: spaces will be replaced with one tab.
135: .It Fl t Ar number
136: Assume that the input files' tabs assume
137: .Ar number
1.9 aaron 138: spaces per tab stop.
139: The default is 8.
1.4 millert 140: .El
1.1 deraadt 141: .Pp
1.7 aaron 142: .Nm
1.1 deraadt 143: is meant to format mail messages prior to sending, but may also be useful
144: for other simple tasks.
145: For instance,
146: within visual mode of the
147: .Xr ex 1
1.7 aaron 148: editor (e.g.,
1.1 deraadt 149: .Xr vi 1 )
150: the command
151: .Pp
152: .Dl \&!}fmt
153: .Pp
154: will reformat a paragraph,
155: evening the lines.
156: .Sh SEE ALSO
1.4 millert 157: .Xr mail 1 ,
1.15 ! millert 158: .Xr nroff 1 ,
! 159: .Xr troff 1
1.1 deraadt 160: .Sh HISTORY
1.14 millert 161: The
1.4 millert 162: .Nm
1.1 deraadt 163: command appeared in
164: .Bx 3 .
1.4 millert 165: .Pp
166: The version described herein is a complete rewrite and appeared in
1.9 aaron 167: .Ox 2.4 .
1.14 millert 168: .Sh AUTHORS
169: .An Kurt Shoens
170: .An Liz Allen
171: (added goal length concept)
172: .An Gareth McCaughan
173: (wrote this version)
1.1 deraadt 174: .Sh BUGS
175: The program was designed to be simple and fast \- for more complex
176: operations, the standard text processors are likely to be more appropriate.
1.4 millert 177: .Pp
178: When the first line of an indented paragraph is very long (more than
179: about twice the goal length), the indentation in the output can be
180: wrong.
181: .Pp
182: .Nm
183: is not infallible in guessing what lines are mail headers and what
184: lines are not.