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 vacant lines, (see the TERMINOLOGY section for definitions), and optionally delimited by indentation (see the d option in the OPTIONS section).
Each output paragraph is generated from the corresponding input paragraph as follows:
1) An optional prefix and/or suffix is removed from each input line.
2) The remainder is divided into words (separated by spaces).
3) The words are joined into lines to make an eye-pleasing paragraph.
4) The prefixes and suffixes are reattached.
If there are suffixes, spaces are inserted before them so that they all end in the same column.
Miscellaneous terms:
__ = an underscore
_s = a space
_b = a backslash (\)
_q = a single quote (')
_Q = a double quote ()
_A = all upper case letters
_a = all lower case letters
_0 = all decimal digits
_xhh = the character represented by the two hexadecimal digits hh (which may be upper or lower case)
Types of characters:
Functions:
Types of lines:
Groups of lines:
Types of words:
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 help, version, B, P, and Q options must have a whole arguments all to themselves.
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 unset parameters whose default values depend on the IP are recomputed separately for each paragraph.
The approximate role of each variable is described here. See the DETAILS section for the rest of the story.
The first four parameters, hang, prefix, suffix, and width, may be set to any unsigned decimal integer less than 10000.
The remaining eight parameters, div, fit, guess, just, last, quote, Report, and touch, may be set to either 0 or 1. If the number is absent in the option, the value 1 is inferred.
If the value of any parameter is set more than once, the last value is used. When unset parameters are assigned default values, hang and quote are assigned before prefix, and fit and last are assigned before touch (because of the dependencies).
It is an error if width <= prefix + suffix.
If a NUL character appears in the value of an environment variable, it and the rest of the string will not be seen by par.
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.
Protected lines are copied unchanged from the input to the output. All other input lines, as they are read, have any NUL characters removed, and every white character (except newlines) turned into a space.
Blank lines in the input are transformed into empty lines in the output. Vacant lines in the input are stripped of trailing spaces before being output.
The input is divided into segments, which are divided into blocks, which are divided into IPs. The exact process depends on the values of quote and div (see q and d in the OPTIONS section). The remainder of this section describes the process which is applied independently to each IP to construct the corresponding OP.
After the values of the parameters are determined (see the OPTIONS section), the first prefix characters and the last suffix characters of each input line are removed and remembered. It is an error for any line to contain fewer than prefix + suffix characters.
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 guess is 1, some words might be merged (see g in the OPTIONS section). The first word includes any spaces that preceed it on the same line.
Let L = width - prefix - suffix.
If Report is 0, some words may get chopped up at this point (see R in the OPTIONS section).
The words are reassembled, preserving their order, into lines. If just is 0, adjacent words within a line are separated by a single space, (or sometimes two if guess is 1), and line breaks are chosen so that the paragraph satisfies the following properties:
1) No line contains more than L characters.
2) If fit is 1, the difference between the lengths of the shortest and longest lines is as small as possible.
3) The shortest line is as long as possible, subject to properties 1 and 2.
4) Let target be L if fit is 0, or the length of the longest line if fit is 1. The sum of the squares of the differences between target and the lengths of the lines is as small as possible, subject to properties 1, 2, and 3.
If last is 0, the last line does not count as a line for the purposes of properties 2, 3, and 4 above.
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.
If just is 1, adjacent words within a line are separated by one space (or sometimes two if guess is 1) plus zero or more extra spaces. The value of fit is disregarded, and line breaks are chosen so that the paragraph satisfies the following properties:
1) Every line contains exactly L characters.
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.)
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.
If 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.
Extra spaces are distributed as uniformly as possible among the inter-word gaps in each line.
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.
If the number of lines in the resulting paragraph is less than hang, empty lines are added at the end to bring the number of lines up to hang.
If just is 0 and touch is 1, L is changed to be the length of the longest line.
If suffix is not 0, each line is padded at the end with spaces to bring its length up to L.
To each line is prepended prefix characters. Let n be the number of lines in the IP. The characters which are prepended to the ith line are chosen as follows:
1) If i <= n, the characters are copied from the ones that were removed from the beginning of the nth input line.
2) If i > n > hang, the characters are copied from the ones that were removed from the beginning of the last input line.
3) If i > n and n <= hang, the characters are all spaces.
Then to each line is appended suffix characters. The characters which are appended to the ith line are chosen as follows:
1) If i <= n, the characters are copied from the ones that were removed from the end of the nth input line.
2) If i > n > 0, the characters are copied from the ones that were removed from the end of the last input line.
3) If n = 0, the characters are all spaces.
Finally, the lines are printed to the output as the OP.
If there are no errors, par returns EXIT_SUCCESS (see <stdlib.h>).
If there is an error, an error message will be printed to the output, and par will return EXIT_FAILURE. If the error is local to a single paragraph, the preceeding 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 "par error:" 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.
Of course, trying to print an error message would be futile if an error resulted from an output function, so par doesn't bother doing any error checking on output functions.
The superiority of par's dynamic programming algorithm over a greedy algorithm (such as the one used by fmt) can be seen in the following example:
Original paragraph (note that each line begins with 8 spaces):
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.
After a greedy algorithm with width = 39:
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.
After "par 39":
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.
The line breaks chosen by par are clearly more eye-pleasing.
par is most useful in conjunction with the text-filtering features of an editor, such as the ! commands of vi.
The rest of this section is a series of before-and-after pictures showing some typical uses of par.
Before:
/* 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. */
After "par 59":
/* 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. */
Or after "par 59f":
/* 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. */
Or after "par 59l":
/* 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. */
Or after "par 59lf":
/* 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. */
Or after "par 59lft0":
/* 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. */
Or after "par 59j":
/* 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. */
Or after "par 59jl":
/* 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. */
Before:
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.
After "par 52h3":
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.
Before:
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.
After "par 59p12l":
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.
Before:
> > 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.
After "par 52":
> > 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.
Before:
> 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.
After "par 52d":
> 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.
Before:
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.
After "par 40q":
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.
Before:
I sure hope there's still room
in Dr. Jones' section of archaeology.
I've heard he's the bestest. [sic]
After "par 50g":
I sure hope there's still room in
Dr. Jones' section of archaeology. I've
heard he's the bestest. [sic]
Or after "par 50gc":
I sure hope there's still room in
Dr. Jones' section of archaeology. I've
heard he's the bestest. [sic]
The guess feature guesses wrong in cases like the following:
I calc'd the approx.
Fermi level to 3 sig. digits.
With guess = 1, par will incorrectly assume that "approx." ends a sentence. If the input were:
I calc'd the approx. Fermi
level to 3 sig. digits.
then par would refuse to put a line break between "approx." and "Fermi" in the output, mainly to avoid creating the first situation (in case the paragraph were to be fed back through par again). This non-breaking space policy does come in handy for cases like "Mr. Johnson" and "Jan. 1", though.
The guess feature only goes one way. 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.
If you use tabs, you probably won't like the way par handles (or doesn't handle) them. It turns them into spaces. I didn't bother trying to make sense of tabs because they don't make sense to begin with. 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 supporting them in par.) (Thanks to ets1@cs.wustl.edu (Eric T. Stuebe) for showing me the light about tabs.)
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.
If I knew of any bugs, I wouldn't release the package. Of course, there may be bugs that I haven't yet discovered.
If you find any bugs (in the program or in the documentation), or if you have any suggestions, please send e-mail to:
or send paper mail to:
Adam M. Costello Campus Box 1045 Washington University One Brookings Dr. St. Louis, MO 63130 USA
Note that both addresses could change anytime after June 1994.
When reporting a bug, please include the exact input and command line options used, and the version number of par, so that I can reproduce it.