Annotation of src/usr.bin/fmt/fmt.1, Revision 1.25
1.25 ! jmc 1: .\" $OpenBSD: fmt.1,v 1.24 2012/01/17 04:26:28 lum 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: .\"
1.25 ! jmc 32: .Dd $Mdocdate: January 17 2012 $
1.1 deraadt 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
1.22 jmc 117: does not fill these lines,
118: for compatibility with troff and nroff.
1.4 millert 119: .It Fl p
1.9 aaron 120: Allow indented paragraphs.
121: Without the
1.4 millert 122: .Fl p
123: flag, any change in the amount of whitespace at the start of a line
124: results in a new paragraph being begun.
125: .It Fl s
126: Collapse whitespace inside lines, so that multiple whitespace
1.19 jmc 127: characters are turned into a single space
128: (or, at the end of a
129: sentence, a double space).
1.4 millert 130: .It Fl t Ar number
131: Assume that the input files' tabs assume
132: .Ar number
1.9 aaron 133: spaces per tab stop.
134: The default is 8.
1.4 millert 135: .El
1.1 deraadt 136: .Pp
1.7 aaron 137: .Nm
1.1 deraadt 138: is meant to format mail messages prior to sending, but may also be useful
139: for other simple tasks.
140: For instance,
1.20 jmc 141: within an editor such as
142: .Xr vi 1 ,
143: the following command
144: will reformat a paragraph,
145: evening the lines:
1.1 deraadt 146: .Pp
1.20 jmc 147: .Dl !}fmt
1.23 schwarze 148: .Sh EXIT STATUS
149: .Ex -std
150: The latter happens with invalid options, insufficient memory,
151: or when an input file is not found or not readable.
1.25 ! jmc 152: The >0 exit value is the sum of all errors up to a maximum of 127;
1.24 lum 153: more errors may occur but the counter will only increment to this number.
1.1 deraadt 154: .Sh SEE ALSO
1.20 jmc 155: .Xr indent 1 ,
1.4 millert 156: .Xr mail 1 ,
1.20 jmc 157: .Xr vi 1
1.1 deraadt 158: .Sh HISTORY
1.14 millert 159: The
1.4 millert 160: .Nm
1.23 schwarze 161: command first appeared in
162: .Bx 2 .
1.4 millert 163: .Pp
164: The version described herein is a complete rewrite and appeared in
1.9 aaron 165: .Ox 2.4 .
1.14 millert 166: .Sh AUTHORS
167: .An Kurt Shoens
1.23 schwarze 168: (July 1978)
1.14 millert 169: .An Liz Allen
170: (added goal length concept)
171: .An Gareth McCaughan
172: (wrote this version)
1.1 deraadt 173: .Sh BUGS
1.19 jmc 174: The program was designed to be simple and fast \(en for more complex
1.1 deraadt 175: operations, the standard text processors are likely to be more appropriate.
1.4 millert 176: .Pp
177: When the first line of an indented paragraph is very long (more than
178: about twice the goal length), the indentation in the output can be
179: wrong.
180: .Pp
181: .Nm
182: is not infallible in guessing what lines are mail headers and what
183: lines are not.