.\"*********************
.\"* par.1             *
.\"* for Par 1.52      *
.\"* Copyright 2001 by *
.\"* Adam M. Costello  *
.\"*********************
.\"
.\" This is nroff -man (or troff -man) code.
.\"
.TH par 1 "2001-Apr-29" "Par 1.52" "USER COMMANDS"
.SH NAME
par \- filter for reformatting paragraphs
.SH SYNOPSIS
.ds O \fR[\fP
.ds C \fR]\fP
.de OP
.BI \*O\ \\$1 \\$2\ \*C
..
.TP .5i
.B par
.na
.OP help
.OP version
.OP B opset
.OP P opset
.OP Q opset
.OP h \*Ohang\*C
.OP p \*Oprefix\*C
.OP r \*Orepeat\*C
.OP s \*Osuffix\*C
.OP T \*OTab\*C
.OP w \*Owidth\*C
.OP b \*Obody\*C
.OP c \*Ocap\*C
.OP d \*Odiv\*C
.OP E \*OErr\*C
.OP e \*Oexpel\*C
.OP f \*Ofit\*C
.OP g \*Oguess\*C
.OP j \*Ojust\*C
.OP l \*Olast\*C
.OP q \*Oquote\*C
.OP R \*OReport\*C
.OP t \*Otouch\*C
.br
.ad
.SH DESCRIPTION
.ie t .ds Q ``
.el .ds Q ""
.ie t .ds U ''
.el .ds U ""
.de IT
.LP
\h'-\w'\\$1\ 'u'\\$1\ \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.LP
.B par
is a filter which copies its input to its output, changing
all white characters (except newlines) to spaces, and
reformatting each paragraph.  Paragraphs are separated
by protected, blank, and bodiless lines (see the
.SM TERMINOLOGY
section for definitions), and optionally
delimited by indentation (see the
.B d
option in the
.SM OPTIONS
section).
.LP
Each output paragraph is generated from the
corresponding input paragraph as follows:
.RS
.LP
.IT 1) An optional prefix and/or suffix
is removed from each input line.
.IT 2) The remainder is divided into
words (separated by spaces).
.IT 3) The words are joined into lines
to make an eye-pleasing paragraph.
.IT 4) The prefixes and suffixes are reattached.
.RE
.LP
If there are suffixes, spaces are inserted before
them so that they all end in the same column.
.SH QUICK START
.LP
.B par
is necessarily complex.  For those who wish to use
it immediately and understand it later, assign the
.B \s-1PARINIT\s0
environment variable the following value:
.IP
rTbgqR B=.,?_A_a Q=_s>|
.LP
The spaces, question mark, greater-than sign, and
vertical bar will probably have to be escaped or
quoted to prevent your shell from interpreting them.
.LP
The documentation, though precise, is unfortunately
not well-written for the end-user.  Your
best bet is probably to read quickly the
.SM DESCRIPTION\s0,
.SM TERMINOLOGY\s0,
.SM OPTIONS\s0,
and
.SM ENVIRONMENT
sections, then read carefully the
.SM EXAMPLES
section, referring back to the
.SM OPTIONS
and
.SM TERMINOLOGY
sections as needed.
.LP
For the \*Qpower user\*U, a full understanding of
.B par
will require multiple readings of the
.SM TERMINOLOGY\s0,
.SM OPTIONS\s0,
.SM DETAILS\s0,
and
.SM EXAMPLES
sections.
.SH TERMINOLOGY
.LP
Miscellaneous terms:
.RS
.IP "charset syntax"
A way of representing a set of characters as a string.
The set includes exactly those characters which
appear in the string, except that the underscore (_)
is an escape character.  Whenever it appears, it
must begin one of the following escape sequences:
.RS 1.5i
.IT __\ = an underscore
.IT _s\ = a space
.IT _b\ = a backslash (\e)
.IT _q\ = a single quote (')
.IT _Q\ = a double quote (")
.IT _A\ = all upper case letters
.IT _a\ = all lower case letters
.IT _0\ = all decimal digits
.IT _x\fIhh\fP\ = the character represented
by the two hexadecimal digits
.I hh
(which may be upper or lower case)
.RE
.IP
The NUL character must not appear in the string, but
it may be included in the set with the _x00 sequence.
.IP error
A condition which causes
.B par
to abort.  See the
.SM DIAGNOSTICS
section.
.IP IP
Input paragraph.
.IP OP
Output paragraph.
.IP parameter
A symbol which may take on unsigned integral values.  There
are several parameters whose values affect the behavior of
.BR par .
Parameters can be assigned values
using command line options.
.RE
.LP
Types of characters:
.RS
.IP "alphanumeric character"
An upper case letter, lower case letter, or decimal digit.
.IP "body character"
A member of the set of characters defined by the
.B \s-1PARBODY\s0
environment variable (see the
.SM ENVIRONMENT
section) and/or the
.B B
option (see the
.SM OPTIONS
section).
.IP "protective character"
A member  of the set of characters defined by the
.B \s-1PARPROTECT\s0
environment variable and/or the
.B P
option.
.IP "quote character"
A member of the set of characters defined by the
.B \s-1PARQUOTE\s0
environment variable and/or the
.B Q
option.
.IP "terminal character"
A period, question mark, exclamation point, or colon.
.IP "white character"
A space, formfeed, newline, carriage
return, tab, or vertical tab.
.RE
.LP
Functions:
.RS
.IP comprelen
Given a non-empty sequence
.I S
of lines, let
.I c
be their longest common prefix.  If the parameter
.I body
is 0, place a divider just after
the leading non-body characters in
.I c
(at the beginning if there are none).  If
.I body
is 1, place the divider just after the
last non-space non-body character in
.I c
(at the beginning if there is none), then
advance the divider over any immediately
following spaces.  The comprelen of
.I S
is the number of characters preceding the divider.
.IP comsuflen
Given a non-empty sequence
.I S
of lines, let
.I p
be the comprelen of
.IR S .
Let
.I T
be the set of lines which result from stripping the first
.I p
characters from each line in
.IR S .
Let
.I c
be the longest common suffix of the lines in
.IR T .
If
.I body
is 0, place a divider just before
the trailing non-body characters in
.I c
(at the end if there are none), then
advance the divider over all but the last
of any immediately following spaces.  If
.I body
is 1, place the divider just before the first
non-space non-body character, then back up
the divider over one immediately preceding
space if there is one.  The comsuflen of
.I S
is the number of characters following the divider.
.IP "fallback prelen (suflen)"
The fallback prelen (suflen) of an IP is: the comprelen
(comsuflen) of the IP, if the IP contains at least two
lines; otherwise, the comprelen (comsuflen) of the
block containing the IP, if the block contains at least
two lines; otherwise, the length of the longer of the
prefixes (suffixes) of the bodiless lines just above and
below the block, if the segment containing the block
has any bodiless lines; otherwise, 0.  (See below for
the definitions of block, segment, and bodiless line.)
.IP "augmented fallback prelen"
Let
.I fp
be the fallback prelen of an IP.  If the
IP contains more than one line, or if
.I quote
is 0, then the augmented fallback prelen of the IP is simply
.IR fp .
Otherwise, it is
.I fp
plus the number of quote characters
immediately following the first
.I fp
characters of the line.
.IP quoteprefix
The quoteprefix of a line is the longest string of quote
characters appearing at the beginning of the line, after
this string has been stripped of any trailing spaces.
.RE
.LP
Types of lines:
.RS
.IP "blank line"
An empty line, or a line whose first character is
not protective and which contains only spaces.
.IP "protected line"
An input line whose first character is protective.
.IP "bodiless line"
A line which is order
.I k
bodiless for some
.IR k .
.IP "order \fIk\fP bodiless line"
There is no such thing as an order 0 bodiless line.  Suppose
.I S
is a a contiguous subsequence of a segment (see below)
containing at least two lines, containing no order
.IR k \-1
bodiless lines, bounded above and below by order
.IR k \-1
bodiless lines and/or the beginning/end of the segment.  Let
.I p
and
.I s
be the comprelen and comsuflen of
.IR S .
Any member of
.I S
which, if stripped of its first
.I p
and last
.I s
characters, would be blank (or, if the parameter
.I repeat
is non-zero, would consist of the
same character repeated at least
.I repeat
times), is order
.I k
bodiless.  The first
.I p
characters of the bodiless line
comprise its prefix; the last
.I s
characters comprise its suffix.  The character which repeats
in the middle is called its repeat character.  If the middle
is empty, the space is taken to be its repeat character.
.IP "vacant line"
A bodiless line whose repeat character is the space.
.IP "superfluous line"
Only blank and vacant lines may be superfluous.  If
contiguous vacant lines lie at the beginning or end
of a segment, they are all superfluous.  But if they
lie between two non-vacant lines within a segment,
then all are superfluous except one\(emthe one which
contains the fewest non-spaces.  In case of a tie,
the first of the tied lines is chosen.  Similarly, if
contiguous blank lines lie outside of any segments
at the beginning or end of the input, they are all
superfluous.  But if they lie between two segments and/or
protected lines, then all are superfluous except the first.
.RE
.LP
Groups of lines:
.RS
.IP segment
A contiguous sequence of input lines containing no protected
or blank lines, bounded above and below by protected
lines, blank lines, and/or the beginning/end of the input.
.IP block
A contiguous subsequence of a segment containing no
bodiless lines, bounded above and below by bodiless
lines and/or the beginning/end of the segment.
.RE
.LP
Types of words:
.RS
.IP "capitalized word"
If the parameter
.I cap
is 0, a capitalized word is one which contains
at least one alphanumeric character, whose first
alphanumeric character is not a lower case letter.  If
.I cap
is 1, every word is considered a capitalized word.  (See the
.B c
option in the
.SM OPTIONS
section.)
.IP "curious word"
A word which contains a terminal character
.I c
such that there are no alphanumeric
characters in the word after
.IR c ,
but there is at least one alphanumeric
character in the word before
.IR c .
.RE
.SH OPTIONS
.LP
Any command line argument may begin with one minus
sign (\-) which is ignored.  Generally, more
than one option may appear in a single command
line argument, but there are exceptions:  The
.BR help ,
.BR version ,
.BR B ,
.BR P ,
and
.B Q
options must have whole arguments all to themselves.
.TP 1i
.B help
Causes all remaining arguments to be ignored.  No
input is read.  A usage message is printed on the
output briefly describing the options used by
.BR par .
.TP
.B version
Causes all remaining arguments to be ignored.  No input
is read.  \*Qpar 1.52\*U is printed on the output.  Of
course, this will change in future releases of Par.
.TP
.BI B opset
.I op
is a single character, either an equal sign
(=), a plus sign (+), or a minus sign (-), and
.I set
is a string using charset syntax.  If
.I op
is an equal sign, the set of body characters
is set to the character set defined by
.IR set .
If
.I op
is a plus/minus sign, the characters in the set defined by
.I set
are added/removed to/from the existing
set of body characters defined by the
.B \s-1PARBODY\s0
environment variable and any previous B options.  It
is okay to add characters that are already in the
set or to remove characters that are not in the set.
.TP
.BI P opset
Just like the
.B B
option, except that it applies to
the set of protective characters.
.TP
.BI Q opset
Just like the
.B B
option, except that it applies
to the set of quote characters.
.LP
All remaining options are used to set values of
parameters.  Values set by command line options hold for all
paragraphs.  Unset parameters are given default values.  Any
parameters whose default values depend on the IP (namely
.I prefix
and
.IR suffix ),
if left unset, are recomputed separately for each paragraph.
.LP
The approximate role of each
variable is described here.  See the
.SM DETAILS
section for the rest of the story.
.LP
The first six parameters,
.IR hang ,
.IR prefix ,
.IR repeat ,
.IR suffix ,
.IR Tab ,
and
.IR width ,
may be set to any unsigned decimal integer less than 10000.
.TP 1i
.BI h\fR[ hang\fR]
Mainly affects the default values of
.I prefix
and
.IR suffix .
Defaults to 0.  If the
.B h
option is given without a number, the
value 1 is inferred.  (See also the
.B p
and
.B s
options.)
.TP
.BI p\fR[ prefix\fR]
The first
.I prefix
characters of each line of the OP are copied from the first
.I prefix
characters of the corresponding line
of the IP.  If there are more than
.IR hang +1
lines in the IP, the default value is the comprelen
of all the lines in the IP except the first
.I hang
of them.  Otherwise, the default value is the
augmented fallback prelen of the IP.  If the
.B p
option is given without a number,
.I prefix
is unset, even if it had been set earlier.  (See also the
.B h
and
.B q
options.)
.TP
.BI r\fR[ repeat\fR]
If
.I repeat
is non-zero, bodiless lines have the number of
instances of their repeat characters increased
or decreased until the length of the line is
.IR width .
The exact value of
.I repeat
affects the definition of bodiless
line.  Defaults to 0.  If the
.B r
option is given without a number, the
value 3 is inferred.  (See also the
.B w
option.)
.TP
.BI s\fR[ suffix\fR]
The last
.I suffix
characters of each line of the OP are copied from the last
.I suffix
characters of the corresponding line
of the IP.  If there are more than
.IR hang +1
lines in the IP, the default value is the comsuflen
of all the lines of the IP except the first
.I hang
of them.  Otherwise, the default value is
the fallback suflen of the IP.  If the
.B s
option is given without a number,
.I suffix
is unset, even if it had been set earlier.  (See also the
.B h
option.)
.TP
.BI T\fR[ Tab\fR]
Tab characters in the input are expanded
to spaces, assuming tab stops every
.I Tab
columns.  Must not be 0.  Defaults to 1.  If the
.B T
option is given without a number, the value 8 is inferred.
.TP
.BI w\fR[ width\fR]
No line in the OP may contain more than
.I width
characters, not including the trailing
newlines.  Defaults to 72.  If the
.B w
option is given without a number, the value 79 is inferred.
.LP
The remaining thirteen parameters,
.IR body ,
.IR cap ,
.IR div ,
.IR Err ,
.IR expel ,
.IR fit ,
.IR guess ,
.IR invis ,
.IR just ,
.IR last ,
.IR quote ,
.IR Report ,
and
.IR touch ,
may be set to either 0 or 1.  If the number is
absent in the option, the value 1 is inferred.
.TP 1i
.BI b\fR[ body\fR]
If
.I body
is 1, prefixes may not contain any trailing body characters,
and suffixes may not contain any leading body characters.
(Actually, the situation is complicated by space characters.
See comprelen and comsuflen in the Terminology section.)  If
.I body
is 0, prefixes and suffixes may not contain
any body characters at all.  Defaults to 0.
.TP
.BI c\fR[ cap\fR]
If
.I cap
is 1, all words are considered capitalized.  This
currently affects only the application of the
.B g
option.  Defaults to 0.
.TP
.BI d\fR[ div\fR]
If
.I div
is 0, each block becomes an IP.  If
.I div
is 1, each block is subdivided into IPs as follows:  Let
.I p
be the comprelen of the block.
Let a line's status be 1 if its
.RI ( p +1)st
character is a space, 0 otherwise.  Every line in the
block whose status is the same as the status of the
first line will begin a new paragraph.  Defaults to 0.
.TP
.BI E\fR[ Err\fR]
If
.I Err
is 1, messages to the user (caused by the
.B help
and
.B version
options, or by errors) are sent to the error stream
instead of the output stream.  Defaults to 0.
.TP
.BI e\fR[ expel\fR]
If
.I expel
is 1, superfluous lines are withheld
from the output.  Defaults to 0.
.TP
.BI f\fR[ fit\fR]
If
.I fit
is 1 and
.I just
is 0,
.B par
tries to make the lines in the OP as nearly the
same length as possible, even if it means making
the OP narrower.  Defaults to 0.  (See also the
.B j
option.)
.TP
.BI g\fR[ guess\fR]
If
.I guess
is 1, then when
.B par
is choosing line breaks, whenever it encounters a curious
word followed by a capitalized word, it takes one of two
special actions.  If the two words are separated by a
single space in the input, they will be merged into one
word with an embedded non-breaking space.  If the two words
are separated by more than one space, or by a line break,
.B par
will insure that they are separated by two spaces,
or by a line break, in the output.  Defaults to 0.
.TP
.BI i\fR[ invis\fR]
If
.I invis
is 1, then vacant lines inserted because
.I quote
is 1 are invisible; that is, they are not output.  If
.I quote
is 0,
.I invis
has no effect.  Defaults to 0.  (See also the
.B q
option.)
.TP
.BI j\fR[ just\fR]
If
.I just
is 1,
.B par
justifies the OP, inserting spaces between words
so that all lines in the OP have length
.I width
(except the last, if
.I last
is 0).  Defaults to 0.  (See also the
.BR w ,
.BR l ,
and
.B f
options.)
.TP
.BI l\fR[ last\fR]
If
.I last
is 1,
.B par
tries to make the last line of the OP about
the same length as the others.  Defaults to 0.
.TP
.BI q\fR[ quote\fR]
If
.I quote
is 1, then before each segment
is scanned for bodiless lines,
.B par
supplies vacant lines between different quotation nesting
levels as follows:  For each pair of adjacent lines in
the segment, (scanned from the top down) which have
different quoteprefixes, one of two actions is taken.  If
.I invis
is 0, and either line consists entirely of quote
characters and spaces (or is empty), that line
is truncated to the longest common prefix of the
two lines (both are truncated if both qualify).
Otherwise, a line consisting of the longest common
prefix of the two lines is inserted between them.
.I quote
also affects the default value of
.IR prefix .
Defaults to 0.  (See also the
.B p
and
.B i
options.)
.TP
.BI R\fR[ Report\fR]
If
.I Report
is 1, it is considered an error for
an input word to contain more than
.IR L \ =
.RI ( width \ -
.IR prefix \ -
.IR suffix )
characters.  Otherwise, such
words are chopped after each
.IR L th
character into shorter words.  Defaults to 0.
.TP
.BI t\fR[ touch\fR]
Has no effect if
.I suffix
is 0 or
.I just
is 1.  Otherwise, if
.I touch
is 0, all lines in the OP have length
.IR width .
If
.I touch
is 1, the length of the lines is decreased until the
suffixes touch the body of the OP.  Defaults to the logical
.SM OR
of
.I fit
and
.IR last .
(See also the
.BR s ,
.BR j ,
.BR w ,
.BR f ,
and
.B l
options.)
.LP
If an argument begins with a number,
that number is assumed to belong to a
.B p
option if it is 8 or less, and to a
.B w
option otherwise.
.LP
If the value of any parameter is set more
than once, the last value is used.  When
unset parameters are assigned default values,
.I hang
and
.I quote
are assigned before
.IR prefix ,
and
.I fit
and
.I last
are assigned before
.I touch
(because of the dependencies).
.LP
It is an error if
.I width
<=
.I prefix
+
.IR suffix .
.SH ENVIRONMENT
.TP 1i
.B \s-1PARBODY\s0
Determines the initial set of body characters
(which are used for determining comprelens
and comsuflens), using charset syntax.  If
.B \s-1PARBODY\s0
is not set, the set of body characters is initially empty.
.TP
.B \s-1PARINIT\s0
If set,
.B par
will read command line options from
.B \s-1PARINIT\s0
before it reads them from the command line.
Within the value of
.B \s-1PARINIT\s0,
arguments are separated by white characters.
.TP
.B \s-1PARPROTECT\s0
Determines the set of protective
characters, using charset syntax.  If
.B \s-1PARPROTECT\s0
is not set, the set of protective
characters is initially empty.
.TP
.B \s-1PARQUOTE\s0
Determines the set of quote
characters, using charset syntax.  If
.B \s-1PARQUOTE\s0
is not set, the set of quote characters initially
contains only the greater-than sign (>) and the space.
.LP
If a
.SM NUL
character appears in the value of an environment variable,
it and the rest of the string will not be seen by
.BR par .
.LP
Note that the
.B \s-1PARINIT\s0
variable, together with the
.BR B ,
.BR P ,
and
.B Q
options, renders the other environment variables
unnecessary.  They are included for backward compatibility.
.SH DETAILS
.LP
Lines are terminated by newline characters, but the
newlines are not considered to be included in the lines.
If the last character of the input is a non-newline,
a newline will be inferred immediately after it (but
if the input is empty, no newline will be inferred;
the number of input lines will be 0).  Thus, the
input can always be viewed as a sequence of lines.
.LP
Protected lines are copied unchanged from the input to the
output.  All other input lines, as they are read, have any
.SM NUL
characters removed, and every white character
(except newlines) turned into a space.
Actually, each tab character is turned into
.I Tab
-
.RI ( n
%
.IR Tab )
spaces, where
.I n
is the number of characters preceding the
tab character on the line (evaluated after
earlier tab characters have been expanded).
.LP
Blank lines in the input are transformed
into empty lines in the output.
.LP
If
.I repeat
is 0, all bodiless lines are vacant, and they are all
simply stripped of trailing spaces before being output.  If
.I repeat
is not 0, only vacant lines whose suffixes have length
0 are treated that way; other bodiless lines have
the number of instances of their repeat characters
increased or decreased until the length of the line is
.IR width .
.LP
If
.I expel
is 1, superfluous lines are not output.  If
.I quote
and
.I invis
are both 1, there may be invisible
lines; they are not output.
.LP
The input is divided into segments, which are
divided into blocks, which are divided into
IPs.  The exact process depends on the values of
.I quote
and
.I div
(see
.B q
and
.B d
in the
.SM OPTIONS
section).  The remainder of this section describes
the process which is applied independently to
each IP to construct the corresponding OP.
.LP
After the values of the parameters are determined (see the
.SM OPTIONS
section), the first
.I prefix
characters and the last
.I suffix
characters of each input line are removed and remembered.
It is an error for any line to contain fewer than
.IR prefix \ +\  suffix
characters.
.LP
The remaining text is treated as a sequence of
characters, not lines.  The text is broken into
words, which are separated by spaces.  That is, a
word is a maximal sub-sequence of non-spaces.  If
.I guess
is 1, some words might be merged (see
.B g
in the
.SM OPTIONS
section).  The first word includes any
spaces that preced it on the same line.
.LP
Let
.I L
=
.I width
\-
.I prefix
\-
.IR suffix .
.LP
If
.I Report
is 0, some words may get chopped up at this point (see
.B R
in the
.SM OPTIONS
section).
.LP
The words are reassembled, preserving
their order, into lines.  If
.I just
is 0, adjacent words within a line are separated
by a single space, (or sometimes two if
.I guess
is 1), and line breaks are chosen so that
the paragraph satisfies the following properties:
.RS 1i
.IT 1) No line contains more than
.I L
characters.
.IT 2) If
.I fit
is 1, the difference between the lengths of the
shortest and longest lines is as small as possible.
.IT 3) The shortest line is as long as
possible, subject to properties 1 and 2.
.IT 4) Let
.I target
be
.I L
if
.I fit
is 0, or the length of the longest line if
.I fit
is 1.  The sum of the squares of the differences between
.I target
and the lengths of the lines is as small as
possible, subject to properties 1, 2, and 3.
.RE
.RS .5i
.LP
If
.I last
is 0, the last line does not count as a line for
the purposes of properties 2, 3, and 4 above.
.LP
If all the words fit on a single line, the
properties as worded above don't make much
sense.  In that case, no line breaks are inserted.
.RE
.LP
If
.I just
is 1, adjacent words within a line are
separated by one space (or sometimes two if
.I guess
is 1) plus zero or more extra spaces.  The value of
.I fit
is disregarded, and line breaks are chosen so that
the paragraph satisfies the following properties:
.RS 1i
.IT 1) Every line contains exactly
.I L
characters.
.IT 2) The largest inter-word gap is as small as
possible, subject to property 1.  (An inter-word gap
consists only of the extra spaces, not the regular spaces.)
.IT 3) The sum of the squares of the lengths
of the inter-word gaps is as small as
possible, subject to properties 1 and 2.
.RE
.RS .5i
.LP
If
.I last
is 0, the last line does not count as a line
for the purposes of property 1, and it does
not require or contain any extra spaces.
.LP
Extra spaces are distributed as uniformly as
possible among the inter-word gaps in each line.
.LP
In a justified paragraph, every line must
contain at least two words, but that's not
always possible to accomplish.  If the paragraph
cannot be justified, it is considered an error.
.RE
.LP
If the number of lines in the
resulting paragraph is less than
.IR hang ,
empty lines are added at the end
to bring the number of lines up to
.IR hang .
.LP
If
.I just
is 0 and
.I touch
is 1,
.I L
is changed to be the length of the longest line.
.LP
If
.I suffix
is not 0, each line is padded at the end
with spaces to bring its length up to
.IR L .
.LP
To each line is prepended
.I prefix
characters.  Let
.I n
be the number of lines in the IP, let
.I afp
be the augmented fallback prelen of the IP, and let
.I fs
be the fallback suflen of the IP.  The
characters which are prepended to the
.IR i th
line are chosen as follows:
.RS
.LP
.IT 1) If
.I i
<=
.IR n ,
the characters are copied from the ones
that were removed from the beginning of the
.IR n th
input line.
.IT 2) If
.I i
>
.I n
>
.IR hang ,
the characters are copied from the ones that were
removed from the beginning of the last input line.
.IT 3) If
.I i
>
.I n
and
.I n
<=
.IR hang ,
the first
.RI min( afp , prefix )
of the characters are copied from the ones
that were removed from the beginning of the
last input line, and the rest are all spaces.
.RE
.LP
Then to each line is appended
.I suffix
characters.  The characters which are appended to the
.IR i th
line are chosen as follows:
.RS
.LP
.IT 1) If
.I i
<=
.IR n ,
the characters are copied from the ones
that were removed from the end of the
.IR n th
input line.
.IT 2) If
.I i
>
.I n
>
.IR hang ,
the characters are copied from the ones that
were removed from the end of the last input line.
.IT 3) If
.I i
>
.I n
and
.I n
<=
.IR hang ,
the first
.RI min( fs , suffix )
of the characters are copied from the ones
that were removed from the beginning of the
last input line, and the rest are all spaces.
.RE
.LP
Finally, the lines are printed to the output as the OP.
.SH DIAGNOSTICS
.LP
If there are no errors,
.B par
returns
.B \s-1EXIT_SUCCESS\s0
(see
.BR <stdlib.h> ).
.LP
If there is an error, an error message
will be printed to the output, and
.B par
will return
.BR \s-1EXIT_FAILURE\s0 .
If the error is local to a single paragraph, the preceding
paragraphs will have been output before the error
was detected.  Line numbers in error messages are
local to the IP in which the error occurred.  All
error messages begin with \*Qpar\ error:\*U on a line
by itself.  Error messages concerning command line
or environment variable syntax are accompanied by
the same usage message that the help option produces.
.LP
Of course, trying to print an error message would be
futile if an error resulted from an output function, so
.B par
doesn't bother doing any error checking on output functions.
.SH EXAMPLES
.de VS
.RS -.5i
.LP
.nf
.ps -1p
.vs -2p
.ft CW
..
.de VE
.ft P
.vs
.ps
.fi
.RE
..
.de CM
\&\*Q\fB\\$1\fP\\*U:
..
.LP
The superiority of
.BR par 's
dynamic programming algorithm over a
greedy algorithm (such as the one used by
.BR fmt )
can be seen in the following example:
.LP
Original paragraph (note that
each line begins with 8 spaces):
.VS
        We the people of the United States,
        in order to form a more perfect union,
        establish justice,
        insure domestic tranquility,
        provide for the common defense,
        promote the general welfare,
        and secure the blessing of liberty
        to ourselves and our posterity,
        do ordain and establish the Constitution
        of the United States of America.
.VE
.LP
After a greedy algorithm with width = 39:
.VS
        We the people of the United
        States, in order to form a more
        perfect union, establish
        justice, insure domestic
        tranquility, provide for the
        common defense, promote the
        general welfare, and secure the
        blessing of liberty to
        ourselves and our posterity, do
        ordain and establish the
        Constitution of the United
        States of America.
.VE
.LP
After
.CM "par 39"
.VS
        We the people of the United
        States, in order to form a
        more perfect union, establish
        justice, insure domestic
        tranquility, provide for the
        common defense, promote the
        general welfare, and secure
        the blessing of liberty to
        ourselves and our posterity,
        do ordain and establish the
        Constitution of the United
        States of America.
.VE
.LP
The line breaks chosen by
.B par
are clearly more eye-pleasing.
.LP
.B par
is most useful in conjunction with the text-filtering
features of an editor, such as the ! commands of
.BR vi .
You may wish to add the following lines to your
.B .exrc
file:
.VS
        " use Bourne shell for speed:
        set shell=/bin/sh
        "
        " reformat paragraph with no arguments:
        map ** {!}par^M}
        "
        " reformat paragraph with arguments:
        map *^V  {!}par
.VE
.LP
Note that the leading spaces must be removed, and that what
is shown as ^M and ^V really need to be ctrl-M and ctrl-V.
Also note that the last map command contains two spaces
following the ctrl-V, plus one at the end of the line.
.LP
To reformat a simple paragraph delimited by blank lines in
.BR vi ,
you can put the cursor anywhere in it and type
\*Q\fB**\fP\*U (star star). If you need to supply
arguments to par, you can type \*Q\fB*\ \fP\*U
(star space) instead, then type the arguments.
.LP
The rest of this section is a series of
before-and-after pictures showing some typical uses of
.BR par .
In all cases, no environment variables are set.
.LP
Before:
.VS
        /*   We the people of the United States, */
        /* in order to form a more perfect union, */
        /* establish justice, */
        /* insure domestic tranquility, */
        /* provide for the common defense, */
        /* promote the general welfare, */
        /* and secure the blessing of liberty */
        /* to ourselves and our posterity, */
        /* do ordain and establish the Constitution */
        /* of the United States of America. */
.VE
.LP
After
.CM "par 59"
.VS
        /*   We the people of the United States, in      */
        /* order to form a more perfect union, establish */
        /* justice, insure domestic tranquility, provide */
        /* for the common defense, promote the general   */
        /* welfare, and secure the blessing of liberty   */
        /* to ourselves and our posterity, do ordain     */
        /* and establish the Constitution of the United  */
        /* States of America.                            */
.VE
.LP
Or after
.CM "par 59f"
.VS
        /*   We the people of the United States,  */
        /* in order to form a more perfect union, */
        /* establish justice, insure domestic     */
        /* tranquility, provide for the common    */
        /* defense, promote the general welfare,  */
        /* and secure the blessing of liberty to  */
        /* ourselves and our posterity, do ordain */
        /* and establish the Constitution of the  */
        /* United States of America.              */
.VE
.LP
Or after
.CM "par 59l"
.VS
        /*   We the people of the United States, in      */
        /* order to form a more perfect union, establish */
        /* justice, insure domestic tranquility,         */
        /* provide for the common defense, promote       */
        /* the general welfare, and secure the           */
        /* blessing of liberty to ourselves and our      */
        /* posterity, do ordain and establish the        */
        /* Constitution of the United States of America. */
.VE
.LP
Or after
.CM "par 59lf"
.VS
        /*   We the people of the United States,  */
        /* in order to form a more perfect union, */
        /* establish justice, insure domestic     */
        /* tranquility, provide for the common    */
        /* defense, promote the general welfare,  */
        /* and secure the blessing of liberty     */
        /* to ourselves and our posterity, do     */
        /* ordain and establish the Constitution  */
        /* of the United States of America.       */
.VE
.LP
Or after
.CM "par 59lft0"
.VS
        /*   We the people of the United States,         */
        /* in order to form a more perfect union,        */
        /* establish justice, insure domestic            */
        /* tranquility, provide for the common           */
        /* defense, promote the general welfare,         */
        /* and secure the blessing of liberty            */
        /* to ourselves and our posterity, do            */
        /* ordain and establish the Constitution         */
        /* of the United States of America.              */
.VE
.LP
Or after
.CM "par 59j"
.VS
        /*   We  the people  of  the  United States,  in */
        /* order to form a more perfect union, establish */
        /* justice, insure domestic tranquility, provide */
        /* for the  common defense, promote  the general */
        /* welfare, and  secure the blessing  of liberty */
        /* to ourselves and our posterity, do ordain and */
        /* establish  the  Constitution  of  the  United */
        /* States of America.                            */
.VE
.LP
Or after
.CM "par 59jl"
.VS
        /*   We  the   people  of  the   United  States, */
        /* in   order    to   form   a    more   perfect */
        /* union,  establish  justice,  insure  domestic */
        /* tranquility, provide for  the common defense, */
        /* promote  the  general   welfare,  and  secure */
        /* the  blessing  of  liberty to  ourselves  and */
        /* our  posterity, do  ordain and  establish the */
        /* Constitution of the United States of America. */
.VE
.LP
Before:
.VS
        Preamble      We the people of the United States,
        to the US     in order to form
        Constitution  a more perfect union,
                      establish justice,
                      insure domestic tranquility,
                      provide for the common defense,
                      promote the general welfare,
                      and secure the blessing of liberty
                      to ourselves and our posterity,
                      do ordain and establish
                      the Constitution
                      of the United States of America.
.VE
.LP
After
.CM "par 52h3"
.VS
        Preamble      We the people of the United
        to the US     States, in order to form a
        Constitution  more perfect union, establish
                      justice, insure domestic
                      tranquility, provide for the
                      common defense, promote the
                      general welfare, and secure
                      the blessing of liberty to
                      ourselves and our posterity,
                      do ordain and establish the
                      Constitution of the United
                      States of America.
.VE
.LP
Before:
.VS
         1  We the people of the United States,
         2  in order to form a more perfect union,
         3  establish justice,
         4  insure domestic tranquility,
         5  provide for the common defense,
         6  promote the general welfare,
         7  and secure the blessing of liberty
         8  to ourselves and our posterity,
         9  do ordain and establish the Constitution
        10  of the United States of America.
.VE
.LP
After
.CM "par 59p12l"
.VS
         1  We the people of the United States, in order to
         2  form a more perfect union, establish justice,
         3  insure domestic tranquility, provide for the
         4  common defense, promote the general welfare,
         5  and secure the blessing of liberty to ourselves
         6  and our posterity, do ordain and establish the
         7  Constitution of the United States of America.
.VE
.LP
Before:
.VS
        > > We the people
        > > of the United States,
        > > in order to form a more perfect union,
        > > establish justice,
        > > ensure domestic tranquility,
        > > provide for the common defense,
        >
        > Promote the general welfare,
        > and secure the blessing of liberty
        > to ourselves and our posterity,
        > do ordain and establish
        > the Constitution of the United States of America.
.VE
.LP
After
.CM "par 52"
.VS
        > > We the people of the United States, in
        > > order to form a more perfect union,
        > > establish justice, ensure domestic
        > > tranquility, provide for the common
        > > defense,
        >
        > Promote the general welfare, and secure
        > the blessing of liberty to ourselves and
        > our posterity, do ordain and establish
        > the Constitution of the United States of
        > America.
.VE
.LP
Before:
.VS
        >   We the people
        > of the United States,
        > in order to form a more perfect union,
        > establish justice,
        > ensure domestic tranquility,
        > provide for the common defense,
        >   Promote the general welfare,
        > and secure the blessing of liberty
        > to ourselves and our posterity,
        > do ordain and establish
        > the Constitution of the United States of America.
.VE
.LP
After
.CM "par 52d"
.VS
        >   We the people of the United States,
        > in order to form a more perfect union,
        > establish justice, ensure domestic
        > tranquility, provide for the common
        > defense,
        >   Promote the general welfare, and secure
        > the blessing of liberty to ourselves and
        > our posterity, do ordain and establish
        > the Constitution of the United States of
        > America.
.VE
.LP
Before:
.VS
        # 1. We the people of the United States.
        # 2. In order to form a more perfect union.
        # 3. Establish justice, ensure domestic
        #    tranquility.
        # 4. Provide for the common defense
        # 5. Promote the general welfare.
        # 6. And secure the blessing of liberty
        #    to ourselves and our posterity.
        # 7. Do ordain and establish the Constitution.
        # 8. Of the United States of America.
.VE
.LP
After
.CM "par 37p13dh"
.VS
        # 1. We the people of the
        #    United States.
        # 2. In order to form a more
        #    perfect union.
        # 3. Establish justice,
        #    ensure domestic
        #    tranquility.
        # 4. Provide for the common
        #    defense
        # 5. Promote the general
        #    welfare.
        # 6. And secure the blessing
        #    of liberty to ourselves
        #    and our posterity.
        # 7. Do ordain and establish
        #    the Constitution.
        # 8. Of the United States of
        #    America.
.VE
.LP
Before:
.VS
        /*****************************************/
        /*   We the people of the United States, */
        /* in order to form a more perfect union, */
        /* establish justice, insure domestic    */
        /* tranquility,                          */
        /*                                       */
        /*                                       */
        /*   [ provide for the common defense, ] */
        /*   [ promote the general welfare,    ] */
        /*   [ and secure the blessing of liberty ] */
        /*   [ to ourselves and our posterity, ] */
        /*   [                                 ] */
        /*                                       */
        /* do ordain and establish the Constitution */
        /* of the United States of America.       */
        /******************************************/
.VE
.LP
After
.CM "par 42r"
.VS
        /********************************/
        /*   We the people of the       */
        /* United States, in order to   */
        /* form a more perfect union,   */
        /* establish justice, insure    */
        /* domestic tranquility,        */
        /*                              */
        /*                              */
        /*   [ provide for the common ] */
        /*   [ defense, promote the   ] */
        /*   [ general welfare, and   ] */
        /*   [ secure the blessing of ] */
        /*   [ liberty to ourselves   ] */
        /*   [ and our posterity,     ] */
        /*   [                        ] */
        /*                              */
        /* do ordain and establish the  */
        /* Constitution of the United   */
        /* States of America.           */
        /********************************/
.VE
.LP
Or after
.CM "par 42re"
.VS
        /********************************/
        /*   We the people of the       */
        /* United States, in order to   */
        /* form a more perfect union,   */
        /* establish justice, insure    */
        /* domestic tranquility,        */
        /*                              */
        /*   [ provide for the common ] */
        /*   [ defense, promote the   ] */
        /*   [ general welfare, and   ] */
        /*   [ secure the blessing of ] */
        /*   [ liberty to ourselves   ] */
        /*   [ and our posterity,     ] */
        /*                              */
        /* do ordain and establish the  */
        /* Constitution of the United   */
        /* States of America.           */
        /********************************/
.VE
.LP
Before:
.VS
        Joe Public writes:
        > Jane Doe writes:
        > >
        > >
        > > I can't find the source for uncompress.
        > Oh no, not again!!!
        >
        >
        > Isn't there a FAQ for this?
        >
        >
        That wasn't very helpful, Joe. Jane,
        just make a link from uncompress to compress.
.VE
.LP
After
.CM "par 40q"
.VS
        Joe Public writes:

        > Jane Doe writes:
        >
        >
        > > I can't find the source for
        > > uncompress.
        >
        > Oh no, not again!!!
        >
        >
        > Isn't there a FAQ for this?
        >

        That wasn't very helpful, Joe.
        Jane, just make a link from
        uncompress to compress.
.VE
.LP
Or after
.CM "par 40qe"
.VS
        Joe Public writes:

        > Jane Doe writes:
        >
        > > I can't find the source for
        > > uncompress.
        >
        > Oh no, not again!!!
        >
        > Isn't there a FAQ for this?

        That wasn't very helpful, Joe.
        Jane, just make a link from
        uncompress to compress.
.VE
.LP
Or after
.CM "par 40qi"
.VS
        Joe Public writes:
        > Jane Doe writes:
        > >
        > >
        > > I can't find the source for
        > > uncompress.
        > Oh no, not again!!!
        >
        >
        > Isn't there a FAQ for this?
        >
        >
        That wasn't very helpful, Joe.
        Jane, just make a link from
        uncompress to compress.
.VE
.LP
Or after
.CM "par 40qie"
.VS
        Joe Public writes:
        > Jane Doe writes:
        > > I can't find the source for
        > > uncompress.
        > Oh no, not again!!!
        >
        > Isn't there a FAQ for this?
        That wasn't very helpful, Joe.
        Jane, just make a link from
        uncompress to compress.
.VE
.LP
Before:
.VS
        I sure hope there's still room
        in Dr. Jones' section of archaeology.
        I've heard he's the bestest.  [sic]
.VE
.LP
After
.CM "par 50g"
.VS
        I sure hope there's still room in
        Dr. Jones' section of archaeology.  I've
        heard he's the bestest. [sic]
.VE
.LP
Or after
.CM "par 50gc"
.VS
        I sure hope there's still room in
        Dr. Jones' section of archaeology.  I've
        heard he's the bestest.  [sic]
.VE
.LP
Before:
.VS
        John writes:
        : Mary writes:
        : + Anastasia writes:
        : + > Hi all!
        : + Hi Ana!
        : Hi Ana & Mary!
        Please unsubscribe me from alt.hello.
.VE
.LP
After
.CM "par Q+:+ q"
.VS
        John writes:

        : Mary writes:
        :
        : + Anastasia writes:
        : +
        : + > Hi all!
        : +
        : + Hi Ana!
        :
        : Hi Ana & Mary!

        Please unsubscribe me from alt.hello.
.VE
.LP
Before:
.VS
        amc> The b option was added primarily to deal with
        amc> this new style of quotation
        amc> which became popular after Par 1.41 was released.
        amc>
        amc> Par still pays attention to body characters.
        amc> Par should not mistake "Par" for part of the prefix.
        amc> Par should not mistake "." for a suffix.
.VE
.LP
After
.CM "par B=._A_a 50bg"
.VS
        amc> The b option was added primarily to
        amc> deal with this new style of quotation
        amc> which became popular after Par 1.41
        amc> was released.
        amc>
        amc> Par still pays attention to body
        amc> characters.  Par should not mistake
        amc> "Par" for part of the prefix.  Par
        amc> should not mistake "." for a suffix.
.VE
.SH SEE ALSO
.LP
.B par.doc
.SH LIMITATIONS
.LP
The
.I guess
feature guesses wrong in cases like the following:
.VS
        I calc'd the approx.
        Fermi level to 3 sig. digits.
.VE
.LP
With
.I guess
= 1,
.B par
will incorrectly assume that \*Qapprox.\*U
ends a sentence.  If the input were:
.VS
        I calc'd the approx. Fermi
        level to 3 sig. digits.
.VE
.LP
then
.B par
would refuse to put a line break between
\*Qapprox.\*U and \*QFermi\*U in the output,
mainly to avoid creating the first situation (in
case the paragraph were to be fed back through
.B par
again).  This non-breaking space policy does come in handy
for cases like \*QMr.\ Johnson\*U and \*QJan.\ 1\*U, though.
.LP
The
.I guess
feature only goes one way.
.B par
can preserve wide sentence breaks in a
paragraph, or remove them, but it can't insert
them if they aren't already in the input.
.LP
If you use tabs, you may not like the way
.B par
handles (or doesn't handle) them.  It
expands them into spaces.  I didn't let
.B par
output tabs because tabs don't make sense.  Not everyone's
terminal has the same tab settings, so text files containing
tabs are sometimes mangled.  In fact, almost every text file
containing tabs gets mangled when something is inserted at the
beginning of each line (when quoting e-mail or commenting out
a section of a shell script, for example), making them a pain
to edit.  In my opinion, the world would be a nicer place if
everyone stopped using tabs, so I'm doing my part by not letting
.B par
output them.  (Thanks to Eric Stuebe for showing me the
light about tabs.)
.LP
There is currently no way for the length of the
output prefix to differ from the length of the
input prefix.  Ditto for the suffix.  I may consider
adding this capability in a future release, but
right now I'm not sure how I'd want it to work.
.SH APOLOGIES
.LP
Par began in July 1993 as a small program designed to do one
narrow task: reformat a single paragraph that might have a
border on either side.  It was pretty clean back then.  Over
the next three months, it very rapidly expanded to handle
multiple paragraphs, offer more options, and take better
guesses, at the cost of becoming extremely complex, and very
unclean.  It is nowhere near the optimal design for the larger
task it now tries to address.  Its only redeeming features
are that it is extremely useful (I find it indispensable),
extremely portable, and very stable (between the release
of version 1.41 on 1993-Oct-31 and the release of version
1.52 on 2001-Apr-29, no incorrect behavior was reported).
.LP
Back in 1993 I had very little experience at writing
documentation for users, so the documentation for Par
became rather nightmarish.  There is no separation between
how-it-works (which is painfully complex) and how-to-use-it
(which is fairly simple, if you can ever figure it out).
.LP
Someday I ought to reexamine the problem, and redesign
a new, clean solution from scratch.  I don't know
when I might get enough free time to start on such
a project.  Text files may be obsolete by then.
.SH BUGS
.LP
If I knew of any bugs, I wouldn't release the package.  Of
course, there may be bugs that I haven't yet discovered.
.LP
If you find any bugs (in the program or
in the documentation), or if you have
any suggestions, please send e-mail to:
.RS
.LP
amc@cs.berkeley.edu
.RE
.LP
When reporting a bug, please include the exact input and
command line options used, and the version number of
.BR par ,
so that I can reproduce it.
.LP
The latest release of Par is available on the Web at:
.RS
.LP
http://www.cs.berkeley.edu/~amc/Par/
.RE
.LP
These addresses will change.  I'll try to leave forward pointers.