Annotation of src/usr.bin/fmt/fmt.1, Revision 1.20
1.20 ! jmc 1: .\" $OpenBSD: fmt.1,v 1.19 2006/11/29 20:18:50 jmc 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
1.18 jmc 42: .Op Fl l Ar number
43: .Op Fl t Ar number
44: .br
1.1 deraadt 45: .Oo
46: .Ar goal
1.18 jmc 47: .Oo Ar maximum Oc \*(Ba
48: .Fl Ns Ar width \*(Ba
1.10 pjanzen 49: .Fl w Ar width
1.1 deraadt 50: .Oc
1.18 jmc 51: .Op Ar
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.19 jmc 69: .Pp
1.10 pjanzen 70: Alternatively, a single
71: .Ar width
72: parameter can be specified either by prepending a hyphen to it or by using
73: .Fl w .
74: For example,
1.19 jmc 75: .Dq fmt -w 72 ,
76: .Dq fmt -72 ,
1.10 pjanzen 77: and
1.19 jmc 78: .Dq fmt 72 72
1.10 pjanzen 79: all produce identical output.
1.9 aaron 80: The spacing at the beginning of the input lines is preserved in the output,
81: as are blank lines and interword spacing.
1.10 pjanzen 82: Lines are joined or split only at white space; that is, words are never
83: joined or hyphenated.
1.3 millert 84: .Pp
1.8 aaron 85: The options are as follows:
1.11 aaron 86: .Bl -tag -width Ds
1.4 millert 87: .It Fl c
1.9 aaron 88: Center the text, line by line.
89: In this case, most of the other
1.4 millert 90: options are ignored; no splitting or joining of lines is done.
1.18 jmc 91: .It Fl d Ar chars
1.19 jmc 92: Treat
1.18 jmc 93: .Ar chars
94: (and no others) as sentence-ending characters.
95: By default the
96: sentence-ending characters are full stop
97: .Pq Ql \&. ,
98: question mark
1.19 jmc 99: .Pq Ql \&? ,
1.18 jmc 100: and exclamation mark
101: .Pq Ql \&! .
102: Remember that some characters may need to be
1.19 jmc 103: escaped to protect them from the shell.
1.18 jmc 104: .It Fl l Ar number
105: Replace multiple spaces with tabs at the start of each output
106: line, if possible.
107: .Ar number
108: spaces will be replaced with one tab.
1.4 millert 109: .It Fl m
110: Try to format mail header lines contained in the input sensibly.
1.15 millert 111: .It Fl n
112: Format lines beginning with a
113: .Ql \&.
114: (dot) character.
115: Normally,
116: .Nm
117: does not fill these lines, for compatibility with
118: .Xr troff 1
1.17 jmc 119: and
1.15 millert 120: .Xr nroff 1 .
1.4 millert 121: .It Fl p
1.9 aaron 122: Allow indented paragraphs.
123: Without the
1.4 millert 124: .Fl p
125: flag, any change in the amount of whitespace at the start of a line
126: results in a new paragraph being begun.
127: .It Fl s
128: Collapse whitespace inside lines, so that multiple whitespace
1.19 jmc 129: characters are turned into a single space
130: (or, at the end of a
131: sentence, a double space).
1.4 millert 132: .It Fl t Ar number
133: Assume that the input files' tabs assume
134: .Ar number
1.9 aaron 135: spaces per tab stop.
136: The default is 8.
1.4 millert 137: .El
1.1 deraadt 138: .Pp
1.7 aaron 139: .Nm
1.1 deraadt 140: is meant to format mail messages prior to sending, but may also be useful
141: for other simple tasks.
142: For instance,
1.20 ! jmc 143: within an editor such as
! 144: .Xr vi 1 ,
! 145: the following command
! 146: will reformat a paragraph,
! 147: evening the lines:
1.1 deraadt 148: .Pp
1.20 ! jmc 149: .Dl !}fmt
1.1 deraadt 150: .Sh SEE ALSO
1.20 ! jmc 151: .Xr indent 1 ,
1.4 millert 152: .Xr mail 1 ,
1.15 millert 153: .Xr nroff 1 ,
1.20 ! jmc 154: .Xr vi 1
1.1 deraadt 155: .Sh HISTORY
1.14 millert 156: The
1.4 millert 157: .Nm
1.1 deraadt 158: command appeared in
159: .Bx 3 .
1.4 millert 160: .Pp
161: The version described herein is a complete rewrite and appeared in
1.9 aaron 162: .Ox 2.4 .
1.14 millert 163: .Sh AUTHORS
164: .An Kurt Shoens
165: .An Liz Allen
166: (added goal length concept)
167: .An Gareth McCaughan
168: (wrote this version)
1.1 deraadt 169: .Sh BUGS
1.19 jmc 170: The program was designed to be simple and fast \(en for more complex
1.1 deraadt 171: operations, the standard text processors are likely to be more appropriate.
1.4 millert 172: .Pp
173: When the first line of an indented paragraph is very long (more than
174: about twice the goal length), the indentation in the output can be
175: wrong.
176: .Pp
177: .Nm
178: is not infallible in guessing what lines are mail headers and what
179: lines are not.