File: par.doc

package info (click to toggle)
par 1.50-4
links: PTS
area: main
in suites: hamm, potato, slink
size: 232 kB
ctags: 125
sloc: ansic: 1,468; makefile: 58
file content (1367 lines) | stat: -rw-r--r-- 54,632 bytes
  *********************
  * par.doc           *
  * for Par 1.50      *
  * Copyright 1996 by *
  * Adam M. Costello  *
  *********************


    Par 1.50 is a package containing:

       + This doc file.
       + A man page based on this doc file.
       + The ANSI C source for the filter "par".


Contents

    Contents
    File List
    Rights and Responsibilities
    Compilation
    Synopsis
    Description
   *Quick Start
    Terminology
    Options
    Environment
    Details
    Diagnostics
    Examples
    Limitations
    Apologies
    Bugs


File List

    The Par 1.50 package is always distributed with at least the
    following files:

        buffer.c
        buffer.h
        charset.c
        charset.h
        errmsg.c
        errmsg.h
        par.1
        par.c
        par.doc
        protoMakefile
        reformat.c
        reformat.h
        releasenotes

    Each file is a text file which identifies itself on the second line,
    and identifies the version of Par to which it belongs on the third
    line, so you can always tell which file is which, even if the files
    have been renamed.

    The file "par.1" is a man page for the filter par (not to be
    confused with the package Par, which contains the source code for
    par). "par.1" is based on this doc file, and conveys much (not
    all) of the same information, but "par.doc" is the definitive
    documentation for both par and Par.


Rights and Responsibilities

    The files listed in the Files List section above are each Copyright
    1996 by Adam M. Costello (henceforth "I", "me").

    I grant everyone permission to use these files in any way, subject
    to the following two restrictions:

     1) No one may distribute any one of the files unless it is
        accompanied by all of the other files.

     2) No one (except me) may distribute a modified version of one of
        the files unless it clearly identifies itself as a modified
        version, and it is accompanied by the original version of the
        file.

    Regardless of whether modifications get distributed or not, I would
    appreciate being sent copies in case I wish to incorporate them into
    future versions of Par.  See the Bugs section for my addresses.

    All official versions of Par will have version numbers that fit the
    pattern "<digits>.<digits>".  Those who distribute modified files
    should, as a courtesy, make sure to modify the version number (which
    appears in many places--search for it) to something that doesn't
    fit the pattern, to avoid confusion between official versions and
    modified versions.

    Though I have tried to make sure that Par is free of bugs, I make no
    guarantees about its soundness.  Therefore, I am not responsible for
    any damage resulting from the use of these files.


Compilation

    To compile par, you need an ANSI C compiler.  Follow the
    instructions in the comments in protoMakefile.

    If your compiler generates any warnings that you think are
    legitimate, please tell me about them (see the Bugs section).

    Note that all variables in par are either constant or automatic
    (or both), which means that par can be made reentrant (if your
    compiler supports it).  Given the right operating system, it should
    be possible for several par processes to share the same code space
    and the same data space (but not the same stack, of course) in
    memory.


Synopsis
    par [help] [version] [B<op><set>] [P<op><set>] [Q<op><set>]
        [h[<hang>]] [p[<prefix>]] [r[<repeat>]] [s[<suffix>]] [T[<Tab>]]
        [w[<width>]] [b[<body>]] [c[<cap>]] [d[<div>]] [E[<Err>]]
        [e[<expel>]] [f[<fit>]] [g[<guess>]] [i[<invis>]] [j[<just>]]
        [l[<last>]] [q[<quote>]] [R[<Report>]] [t[<touch>]]

    Things enclosed in [square brackets] are optional.  Things enclosed
    in <angle brackets> are parameters.


Description

    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 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.


Quick Start

    par is necessarily complex.  For those who wish to use it
    immediately and understand it later, assign to the PARINIT
    environment variable the following value:

        rTbgqR B=.?_A_a Q=_s>|

    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.

    The documentation, though precise, is unfortunately not well-written
    for the end-user.  Your best bet is probably to read quickly the
    Description, Terminology, Options, and Environment sections, then
    read carefully the Examples section, referring back to the Options
    and Terminology sections as needed.

    For the "power user", a full understanding of par will require
    multiple readings of the Terminology, Options, Details, and Examples
    sections.


Terminology

    Miscellaneous terms:

        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:

                   __ = 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)

            The NUL character must not appear in the string but it may
            be included in the set with the _x00 sequence.

        error
            A condition which causes par to abort.  See the Diagnostics
            section.

        IP  Input paragraph.

        OP  Output paragraph.

        parameter
            A symbol which may take on unsigned integral values.  There
            are several parameters whose values affect the behavior of
            par.  Parameters can be assigned values using command line
            options.


    Types of characters:

        alphanumeric character
            An upper case letter, lower case letter, or decimal digit.

        body character
            A member of the set of characters defined by the PARBODY
            environment variable (see the Environment section) and/or
            the B option (see the Options section).

        protective character
            A member of the set of characters defined by the PARPROTECT
            environment variable and/or the P option.

        quote character
            A member of the set of characters defined by the PARQUOTE
            environment variable and/or the Q option.

        terminal character
            A period, question mark, exclamation point, or colon.

        white character
            A space, formfeed, newline, carriage return, tab, or
            vertical tab.

    Functions:

        comprelen
            Given a non-empty sequence <S> of lines, let <c> be their
            longest common prefix.  If the parameter <body> is 0, place
            a divider just after the leading non-body characters in <c>
            (at the beginning if there are none).  If <body> is 1, place
            the divider just after the last non-space non-body character
            in <c> (at the beginning if there is none), then advance
            the divider over any immediately following spaces.  The
            comprelen of <S> is the number of characters preceeding the
            divider.

        comsuflen
            Given a non-empty sequence <S> of lines, let <p> be the
            comprelen of <S>.  Let <T> be the set of lines which results
            from stripping the first <p> characters from each line in
            <S>.  Let <c> be the longest common suffix of the lines
            in <T>.  If <body> is 0, place a divider just before the
            trailing non-body characters in <c> (at the end if there are
            none), then advance the divider over all but the last of any
            immediately following spaces.  If <body> is 1, place the
            divider just before the first non-space non-body character,
            then back up the divider over one immediately preceeding
            space if there is one.  The comsuflen of <S> is the number
            of characters following the divider.

        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.)

        augmented fallback prelen
            Let <fp> be the fallback prelen of an IP.  If the IP
            contains more than one line, or if <quote> is 0, then
            the augmented fallback prelen of the IP is simply <fp>.
            Otherwise, it is <fp> plus the number of quote characters
            immediately following the first <fp> characters of the line.

        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.

    Types of lines:

        blank line
            An empty line, or a line whose first character is not
            protective and which contains only spaces.

        protected line
            An input line whose first character is protective.

        bodiless line
            A line which is order <k> bodiless for some <k>.

        order <k> bodiless line
            There is no such thing as an order 0 bodiless line.  Suppose
            <S> is a a contiguous subsequence of a segment (see below)
            containing at least two lines, containing no order <k>-1
            bodiless lines, bounded above and below by order <k>-1
            bodiless lines and/or the beginning/end of the segment.
            Let <p> and <s> be the comprelen and comsuflen of <S>.
            Any member of <S> which, if stripped of its first <p> and
            last <s> characters, would be blank (or, if the parameter
            <repeat> is non-zero, would consist of the same character
            repeated at least <repeat> times), is order <k> bodiless.
            The first <p> characters of the bodiless line comprise its
            prefix; the last <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.

        vacant line
            A bodiless line whose repeat character is the space.

        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--the 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.

    Groups of lines:

        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.

        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.

    Types of words:

        capitalized word
            If the parameter <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 <cap>
            is 1, every word is considered a capitalized word.  (See the
            c option in the Options section.)

        curious word
            A word which contains a terminal character <c> such that
            there are no alphanumeric characters in the word after <c>,
            but there is at least one alphanumeric character in the word
            before <c>.


Options

    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 whole arguments all to themselves.

    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 par.

    version     Causes all remaining arguments to be ignored.  No input
                is read. "par 1.50" is printed on the output.  Of
                course, this will change in future releases of Par.

    B<op><set>  <op> is a single character, either an equal sign (=),
                a plus sign (+), or a minus sign (-), and <set> is a
                string using charset syntax.  If <op> is an equal sign,
                the set of body characters is set to the character set
                defined by <set>.  If <op> is a plus/minus sign, the
                characters in the set defined by <set> are added/removed
                to/from the existing set of body characters defined by
                the PARBODY 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.

    P<op><set>  Just like the B option, except that it applies to the
                set of protective characters.

    Q<op><set>  Just like the B option, except that it applies to the
                set of quote characters.

    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 <prefix> and <suffix>), if left
    unset, are recomputed separately for each paragraph.

    The approximate role of each parameter is described here.  See the
    Details section for the rest of the story.

    The first six parameters, <hang>, <prefix>, <repeat>, <suffix>,
    <Tab>, and <width>, may be set to any unsigned decimal integer less
    than 10000.

    h[<hang>]   Mainly affects the default values of <prefix> and
                <suffix>.  Defaults to 0.  If the h option is given
                without a number, the value 1 is inferred.  (See also
                the p and s options.)

    p[<prefix>] The first <prefix> characters of each line of the OP
                are copied from the first <prefix> characters of the
                corresponding line of the IP.  If there are more than
                <hang>+1 lines in the IP, the default value is the
                comprelen of all the lines in the IP except the first
                <hang> of them.  Otherwise, the default value is the
                augmented fallback prelen of the IP.  If the p option is
                given without a number, <prefix> is unset, even if it
                had been set earlier.  (See also the h and q options.)

    r[<repeat>] If <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 <width>.
                The exact value of <repeat> affects the definition of
                bodiless line.  Defaults to 0.  If the r option is given
                without a number, the value 3 is inferred.  (See also
                the w option.)

    s[<suffix>] The last <suffix> characters of each line of the OP
                are copied from the last <suffix> characters of the
                corresponding line of the IP.  If there are more than
                <hang>+1 lines in the IP, the default value is the
                comsuflen of all the lines in the IP except the first
                <hang> of them.  Otherwise, the default value is the
                fallback suflen of the IP.  If the s option is given
                without a number, <suffix> is unset, even if it had been
                set earlier.  (See also the h option.)

    T[<Tab>]    Tab characters in the input are expanded to spaces,
                assuming tab stops every <Tab> columns.  Must not be
                0.  Defaults to 1.  If the T option is given without a
                number, the value 8 is inferred.

    w[<width>]  No line in the OP may contain more than <width>
                characters, not including the trailing newlines.
                Defaults to 72.  If the w option is given without a
                number, the value 79 is inferred.

    The remaining thirteen parameters, <body>, <cap>, <div>, <Err>,
    <expel>, <fit>, <guess>, <invis>, <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.

    b[<body>]   If <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 <body>
                is 0, prefixes and suffixes may not contain any body
                characters at all.  Defaults to 0.

    c[<cap>]    If <cap> is 1, all words are considered capitalized.
                This currently affects only the application of the g
                option.  Defaults to 0.

    d[<div>]    If <div> is 0, each block becomes an IP.  If <div> is 1,
                each block is subdivided into IPs as follows:  Let <p>
                be the comprelen of the block.  Let a line's status be
                1 if its (<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.

    E[<Err>]    If <Err> is 1, messages to the user (caused by the help
                and version options, or by errors) are sent to the error
                stream instead of the output stream.  Defaults to 0.

    e[<expel>]  If <expel> is 1, superfluous lines withheld from the
                output.  Defaults to 0.

    f[<fit>]    If <fit> is 1 and <just> is 0, 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 j option.)

    g[<guess>]  If <guess> is 1, then when 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,
                par will insure that they are separated by two spaces,
                or by a line break, in the output.  Defaults to 0.

    i[<invis>]  If <invis> is 1, then vacant lines inserted because
                <quote> is 1 are invisible; that is, they are not
                output.  If <quote> is 0, <invis> has no effect.
                Defaults to 0.  (See also the q option.)

    j[<just>]   If <just> is 1, par justifies the OP, inserting spaces
                between words so that all lines in the OP have length
                <width> (except the last, if <last> is 0).  Defaults to
                0.  (See also the w, l, and f options.)

    l[<last>]   If <last> is 1, par tries to make the last line of the
                OP about the same length as the others.  Defaults to 0.

    q[<quote>]  If <quote> is 1, then before each segment is scanned
                for bodiless lines, 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 <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.
                <quote> also affects the default value of <prefix>.
                Defaults to 0.  (See also the p and i options.)

    R[<Report>] If <Report> is 1, it is considered an error for an input
                word to contain more than <L> = (<width> - <prefix> -
                <suffix>) characters.  Otherwise, such words are chopped
                after each <L>th character into shorter words.  Defaults
                to 0.

    t[<touch>]  Has no effect if <suffix> is 0 or <just> is 1.
                Otherwise, if <touch> is 0, all lines in the OP have
                length <width>.  If <touch> is 1, the length of the
                lines is decreased until the suffixes touch the body of
                the OP.  Defaults to the logical OR of <fit> and <last>.
                (See also the s, j, w, f, and l options.)

    If an argument begins with a number, that number is assumed
    to belong to a p option if it is 8 or less, and to a w option
    otherwise.

    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>.


Environment

    PARBODY     Determines the initial set of body characters (which are
                used for determining comprelens and comsuflens), using
                charset syntax.  If PARBODY is not set, the set of body
                characters is initially empty.

    PARINIT     If set, par will read command line arguments from PARINIT
                before it reads them from the command line.  Within
                the value of PARINIT, arguments are separated by white
                characters.

    PARPROTECT  Determines the set of protective characters, using charset
                syntax.  If PARPROTECT is not set, the set of protective
                characters is initially empty.

    PARQUOTE    Determines the set of quote characters, using charset
                syntax.  If PARQUOTE is not set, the set of quote characters
                initially contains only the greater-than sign (>) and the
                space.

    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.

    Note that the PARINIT variable, together with the B, P, and Q
    options, renders the other environment variables unnecessary.  They
    are included for backward compatibility.

Details

    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.  Actually, each tab character is turned into <Tab> - (<n> %
    <Tab>) spaces, where <n> is the number of characters preceeding the
    tab character on the line (evaluated after earlier tab characters
    have been expanded).

    Blank lines in the input are transformed into empty lines in the
    output.

    If <repeat> is 0, all bodiless lines are vacant, and they are all
    simply stripped of trailing spaces before being output.  If <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 <width>.

    If <expel> is 1, superfluous lines are not output.  If <quote> and
    <invis> are both 1, there may be invisible lines; they are not
    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, let <afp> be the augmented fallback
    prelen of the IP, and let <fs> be the fallback suflen of the IP.
    The characters which are prepended to the <i>th line are chosen as
    follows:

     1) If <i> <= <n>, the characters are copied from the ones that were
        removed from the beginning of the <n>th 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 first 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.

    Then to each line is appended <suffix> characters.  The characters
    which are appended to the <i>th 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> > <hang>, the characters are copied from the ones
        that were removed from the end of the last input line.

     3) If <i> > <n> and <n> <= <hang>, the first 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.

    Finally, the lines are printed to the output as the OP.


Diagnostics

    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.


Examples

    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.  You may wish to add the
    following lines to your .exrc file:

        " use Bourne shell for speed:
        set shell=/bin/sh
        "
        " reformat paragraph with no arguments:
        map ** {!}par^M}
        "
        " reformat paragraph with arguments:
        map *^V  {!}par 

    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.

    To reformat a simple paragraph delimited by blank lines in vi, you
    can put the cursor anywhere in it and type "**" (star star).  If
    you need to supply arguments to par, you can type "* " (star space)
    instead, then type the arguments.

    The rest of this section is a series of before-and-after pictures
    showing some typical uses of par.  In all cases, no environment
    variables are set.

    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:

        # 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.

    After "par 37p13dh":

        # 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.

    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 42r":

        /********************************/
        /*   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 42re":

        /********************************/
        /*   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:

        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.

    Or after "par 40qe":

        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.

    Or after "par 40qi":

        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.

    Or after "par 40qie":

        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]

    Before:

        John writes:
        : Mary writes:
        : + Anastasia writes:
        : + > Hi all!
        : + Hi Ana!
        : Hi Ana & Mary!
        Please unsubscribe me from alt.hello.

    After "par Q+:+ q":

        John writes:

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

        Please unsubscribe me from alt.hello.

    Before:

        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.

    After "par B=._A_a 50bg":

        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.


Limitations

    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 may not like the way par handles (or doesn't
    handle) them.  It expands them into spaces.  I didn't let 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 par output them.  (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.


Apologies

    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 31 Oct 1993 and the release of version 1.50 on 11 Feb 1996,
    no bugs were reported).

    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).

    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.


Bugs

    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:

        amc@cs.wustl.edu

    or send paper mail to:

        Adam M. Costello
        Campus Box 1115
        Washington University
        One Brookings Dr.
        St. Louis, MO 63130-4899
        USA

    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.

    The latest release of Par is available on the Web at:

        http://www.cs.wustl.edu/~amc/Par/

    Note that all of these addresses could change anytime after August
    1996.  I'll try to leave forward pointers.