Annotation of src/usr.bin/fmt/fmt.1, Revision 1.30
1.30 ! schwarze 1: .\" $OpenBSD: fmt.1,v 1.29 2015/12/15 17:48:16 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: .\"
1.29 jmc 32: .Dd $Mdocdate: December 15 2015 $
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
1.27 schwarze 44: .Op Ar goal Oo Ar maximum Oc | Fl Ar width | Fl w Ar width
1.18 jmc 45: .Op Ar
1.1 deraadt 46: .Sh DESCRIPTION
1.7 aaron 47: .Nm
1.1 deraadt 48: is a simple text formatter which reads the concatenation of input
49: files (or standard input if none are given) and produces on standard
50: output a version of its input with lines as close to the
51: .Ar goal
52: length
1.4 millert 53: as possible without exceeding the
1.5 aaron 54: .Ar maximum .
1.4 millert 55: The
1.1 deraadt 56: .Ar goal
57: length defaults
1.4 millert 58: to 65 and the
59: .Ar maximum
1.14 millert 60: to 10 more than the
61: .Ar goal
62: length.
1.19 jmc 63: .Pp
1.10 pjanzen 64: Alternatively, a single
65: .Ar width
66: parameter can be specified either by prepending a hyphen to it or by using
67: .Fl w .
68: For example,
1.19 jmc 69: .Dq fmt -w 72 ,
70: .Dq fmt -72 ,
1.10 pjanzen 71: and
1.19 jmc 72: .Dq fmt 72 72
1.10 pjanzen 73: all produce identical output.
1.9 aaron 74: The spacing at the beginning of the input lines is preserved in the output,
75: as are blank lines and interword spacing.
1.10 pjanzen 76: Lines are joined or split only at white space; that is, words are never
77: joined or hyphenated.
1.3 millert 78: .Pp
1.8 aaron 79: The options are as follows:
1.11 aaron 80: .Bl -tag -width Ds
1.4 millert 81: .It Fl c
1.9 aaron 82: Center the text, line by line.
83: In this case, most of the other
1.4 millert 84: options are ignored; no splitting or joining of lines is done.
1.18 jmc 85: .It Fl d Ar chars
1.19 jmc 86: Treat
1.18 jmc 87: .Ar chars
88: (and no others) as sentence-ending characters.
89: By default the
90: sentence-ending characters are full stop
91: .Pq Ql \&. ,
92: question mark
1.19 jmc 93: .Pq Ql \&? ,
1.18 jmc 94: and exclamation mark
95: .Pq Ql \&! .
96: Remember that some characters may need to be
1.19 jmc 97: escaped to protect them from the shell.
1.18 jmc 98: .It Fl l Ar number
99: Replace multiple spaces with tabs at the start of each output
100: line, if possible.
101: .Ar number
102: spaces will be replaced with one tab.
1.4 millert 103: .It Fl m
104: Try to format mail header lines contained in the input sensibly.
1.15 millert 105: .It Fl n
106: Format lines beginning with a
107: .Ql \&.
108: (dot) character.
109: Normally,
110: .Nm
1.22 jmc 111: does not fill these lines,
112: for compatibility with troff and nroff.
1.4 millert 113: .It Fl p
1.9 aaron 114: Allow indented paragraphs.
115: Without the
1.4 millert 116: .Fl p
117: flag, any change in the amount of whitespace at the start of a line
118: results in a new paragraph being begun.
119: .It Fl s
120: Collapse whitespace inside lines, so that multiple whitespace
1.19 jmc 121: characters are turned into a single space
122: (or, at the end of a
123: sentence, a double space).
1.4 millert 124: .It Fl t Ar number
125: Assume that the input files' tabs assume
126: .Ar number
1.9 aaron 127: spaces per tab stop.
128: The default is 8.
1.4 millert 129: .El
1.1 deraadt 130: .Pp
1.7 aaron 131: .Nm
1.1 deraadt 132: is meant to format mail messages prior to sending, but may also be useful
133: for other simple tasks.
134: For instance,
1.20 jmc 135: within an editor such as
136: .Xr vi 1 ,
137: the following command
138: will reformat a paragraph,
139: evening the lines:
1.1 deraadt 140: .Pp
1.20 jmc 141: .Dl !}fmt
1.28 schwarze 142: .Sh ENVIRONMENT
143: .Bl -tag -width LC_CTYPE
144: .It Ev LC_CTYPE
1.30 ! schwarze 145: The character encoding
1.28 schwarze 146: .Xr locale 1 .
1.30 ! schwarze 147: It decides which byte sequences form characters
! 148: and what their display width is.
! 149: If unset or set to
1.28 schwarze 150: .Qq C ,
1.29 jmc 151: .Qq POSIX ,
1.30 ! schwarze 152: or an unsupported value, each byte except the tab
! 153: is treated as a character of display width 1.
1.28 schwarze 154: .El
1.23 schwarze 155: .Sh EXIT STATUS
156: .Ex -std
157: The latter happens with invalid options, insufficient memory,
158: or when an input file is not found or not readable.
1.25 jmc 159: The >0 exit value is the sum of all errors up to a maximum of 127;
1.24 lum 160: more errors may occur but the counter will only increment to this number.
1.1 deraadt 161: .Sh SEE ALSO
1.20 jmc 162: .Xr indent 1 ,
1.4 millert 163: .Xr mail 1 ,
1.20 jmc 164: .Xr vi 1
1.1 deraadt 165: .Sh HISTORY
1.14 millert 166: The
1.4 millert 167: .Nm
1.23 schwarze 168: command first appeared in
169: .Bx 2 .
1.4 millert 170: .Pp
171: The version described herein is a complete rewrite and appeared in
1.9 aaron 172: .Ox 2.4 .
1.14 millert 173: .Sh AUTHORS
174: .An Kurt Shoens
1.23 schwarze 175: (July 1978)
1.14 millert 176: .An Liz Allen
177: (added goal length concept)
178: .An Gareth McCaughan
179: (wrote this version)
1.1 deraadt 180: .Sh BUGS
1.19 jmc 181: The program was designed to be simple and fast \(en for more complex
1.1 deraadt 182: operations, the standard text processors are likely to be more appropriate.
1.4 millert 183: .Pp
184: When the first line of an indented paragraph is very long (more than
185: about twice the goal length), the indentation in the output can be
186: wrong.
187: .Pp
188: .Nm
189: is not infallible in guessing what lines are mail headers and what
190: lines are not.