.TH FM 1
.SH NAME
fm, nroff, tex \- a simple text formatter
.SH SYNOPSIS
.B fm
[
.BI \- width
] [
.BR \- ijcCxmoubsdan
] [
.BI \-h hyph
] [
.BI \-p offset
]
.br
[
.BI \-t tabsize
] [
.I files
]
.SH DESCRIPTION
.I Fm
is a simple text formatter.  With no options, the default
behavior of
.I fm
is to copy its input (from specified files or from stdin, if no files
are specified) to its output but with input reformatted into lines no
longer than 72 characters long.  A blank line is taken to indicate the
beginning of a new paragraph.  Lines that begin with a period are
preserved.
.PP
The program will partially emulate some other text formatters, depending
on what options it is given or what name it is called by.
If the program is invoked by
.I nroff
or
.I nroff
.IR -man ,
it will interpret man pages (this is equivalent to
.I fm
.IR -jmo .)
With the name
.IR fmt ,
(or the
.B \-b
option) it works like the UCB program of that name.
With the name
.IR tex ,
a very few
.B TeX
commands are interpreted (this is equivalent to
.I fm
.IR -jx .)
.PP
The indentation and spacing of the input text is not
preserved, unless there is some formatting command to the
contrary, or the program is called
.IR fmt ,
in which case spacing and increased indents are kept
(and the latter cause paragraph breaks).
.SH OPTIONS
The following options modify the default behavior:
.TP
.BI \- width
This changes the line width from the default of 72 characters.
This is the maximum number of visible characters allowed, not taking
account of the newline character at the end of each line.  However,
with the
.B \-b
option, if the program is called by the name
.IR fmt ,
for compatibility, the width requested is decreased by one, so that
in effect, the newline character does count toward the maximum.
.TP
.B \-i
This option will cause
.I fm 
to preserve indentations, and blanks or tabs at the beginning of a line
begin a new paragraph.
.TP
.B \-j
Justify output lines.  (The default is to output lines with a ragged right margin).
.TP
.B \-c
Crown margin mode.  The indentation for the first line of
a paragraph is taken from the indentation of the first input
line of the paragraph, and the indentation of the second input
line of the paragraph is used for the remainder of the paragraph.
This option is for compatibility with UCB
.IR fmt ,
which has the problem that
if input lines are much longer than output lines, more lines than
just the first may get the indentation of the first input line.
This bug is preserved.
.TP
.B \-C
For C code, display comments reversed, flow-of-control keywords
in bold, storage-class keywords underlined, and pre-processor
keywords blinking.
No other formatting is done.  The -u option is assumed unless the -o
option is given.
.TP
.B \-m
Interpret a few commonly used
.I nroff
-man commands.
Those understood (in some fashion) are:
.DS
 .B .I .R .S .G .SM .C
 .IR .BR .RI .BI .RB .IB
 .SH .SS .TH .PP .P .LP .TP .IP .HP
 .RS .RE .DS .DE .NT .NE .VS .VE
 .CT .PN .MS
 .UC (ignored) .DT (ignored) .PD (ignored)
.DE
.sp
And a few other nroff commands that occur commonly in man
pages are recognized:
.DS
 \\fI \\fB \\fR \\fP \\fC
 .sp .br .nf .fi .ti .na .ad .hy
 .\\" \\*(lq \\*(rq .ta (ignored)
.DE
.sp
More details can be found in the document
.IR cmds.tex .
.TP
.B \-o
Produce bold and underlined text with overstriking.
If the terminal and termcap entries permit, the bold and underlined
portions can be seen on the screen by feeding
.I fm
output to
.MS ul 1 .
Bold is produced by fonts B/bf, S/tt, and underlined
by I/it, G/sl.
.TP
.B \-u
Produce bold, underlined, reversed, and blinking text for terminal
display (using termcap md, us, mr, and mb entries, respectively).
This is useful only if one of the options -m or -x is also chosen.
Bold is produced by font B/bf, underlined by I/it, reversed by S/tt,
and blinking by G/sl.
.TP
.B \-s
Split lines only.  Short input lines are not joined to form
paragraphs.
.TP
.B \-b
Berkeley mode.  Preserve indentation and word spacing like the
UCB
.I fmt
program.
.TP
.B \-x
Interpret a few commonly used
.I TeX
commands.
Those understood (in some fashion) are:
.DS
 \\hsize \\hoffset \\parindent \\parskip \\noindent \\par
 \\break \\leftskip \\rightskip \\bye \\end
 \\bigskip \\medskip \\smallskip \\$ \\# \\{ \\}
 \\& \\% \\^ \\_ \\~ \\' \\" \\\\ \\it \\sl \\bf \\rm \\tt
 \\TeX \\centerline \\rightline \\raggedright \\obeylines \\item
 { } \\(space) ~ $ (ignored) \\backslash \\beginsection
.DE
.TP
.BI \-h hyph
Assign hyphenation level.  0 means don't hyphenate; a digit from
1 through 9 means do hyphenate.
2-9 prevents dividing a long word arbitrarily, when no legitimate
hyphenation point can be found, in the extreme situation when the
word exceeds the total available line width.
6-9 prevents dividing after a real hyphen.
7-9 prevents hyphenating a "word" with non-alphabetic characters
surrounded by alphabetic ones, as in an email address.
(Default is level 1, unless the program is called
.IR fmt ,
in which case the default is no hyphenation.)
.TP
.BI \-p offset
Change the page offset.  This moves the output text to the right
by the indicated number of columns.
.TP
.BI \-t tabsize
Change the default spacing between tab stops from 8 to some other
value.  This affects the interpretation of tab characters in the
input text when spacing makes a difference, and it also affects
the output, since
.I fm
putputs tab characters for leading white space only when the tabsize is 8.
.TP
.B \-a
.TP
.B \-n
These options have no effect.  (They are present to allow the
program to be invoked with "nroff -man ...".)
.SH EXAMPLES
Display a man page
.I binmail.1
on the screen with right justification, a page at a time:
.EX
fm -jmu binmail.1 | more -f
.EE
Display a man page with underlining, but no bold face:
.EX
fm -mo binmail.1 | more -f
.EE
Prepare a preformatted man page to be displayed with
.MS ul 1 :
.EX
fm -mo binmail.1 >binmail.doc
.EE
Display high-lighted C source code on the screen:
.EX
fm -C \fIfile\fR.c
.EE
.SH TIPS
In
.IR vi ,
you can define a macro that will reformat paragraphs by typing
.I ":map V {!}fm -i -h0^M" 
or by putting the line
.RS
.I "map V {!}fm -i -h0^M"
.RE
in your
.I .exrc
file.  After defining this macro, pressing
.I V 
will cause the paragraph under the cursor to be reformatted.  (Use the
.I u
key to
.I undo
if necessary.
.SH "SEE ALSO"
nroff(1), vi(1), ul(1)
.SH BUGS
TeX command interpretation doesn't have a chance of working except
for files prepared with the limitations of
.I fm
in mind.
Nroff -man interpretation has a fair chance.
.PP
Not all combinations of options will give sensible results.
.SH AUTHORS
original version: bgray@marque.mu.edu (Bill Gray)
.br
TeX, man, C mods: lee@uhccux.uhcc.hawaii.edu (Greg Lee)
.br
The hyphenation data and code is taken from TeX and derives
from the work of Donald E. Knuth and Frank M. Liang.