Seth Woolley's Man Viewer

par(1) - par - filter for reformatting paragraphs - man 1 par

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

par(1)                           USER COMMANDS                          par(1)



NAME
       par - filter(1,3x,3x curs_util) for reformatting paragraphs

SYNOPSIS
       par  [ help ] [ version(1,3,5) ] [ Bopset ] [ Popset ] [ Qopset ] [ 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] ] [ j[just] ] [ l[last] ] [ q[quote] ]
            [ R[Report] ] [ t[touch] ]

DESCRIPTION
       par  is  a  filter(1,3x,3x curs_util)  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(1,8) the OPTIONS section).

       Each  output  paragraph is generated from the corresponding input para-
       graph 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 para-
              graph.

           4) The prefixes and suffixes are reattached.

       If there are suffixes, spaces are inserted before them so that they all
       end in(1,8) the same column.

QUICK START
       par  is  necessarily complex.  For those who wish to use it immediately
       and understand it later, assign 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 inter-
       preting them.

       The  documentation,  though  precise, is unfortunately not well-written
       for the end-user.  Your best  bet  is  probably  to  read(2,n,1 builtins)  quickly  the
       DESCRIPTION,  TERMINOLOGY, OPTIONS, and ENVIRONMENT sections, then read(2,n,1 builtins)
       carefully the EXAMPLES section, referring back to the OPTIONS and  TER-
       MINOLOGY 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(7,n,1 builtins) of characters  as  a  string.
                     The set(7,n,1 builtins) includes exactly those characters which appear in(1,8)
                     the string(3,n), 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(1,8) the string(3,n), but it
                     may be included in(1,8) the set(7,n,1 builtins) with the _x00 sequence.

              error(8,n)  A condition which causes par to abort.  See the  DIAGNOS-
                     TICS 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(7,n,1 builtins) 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(7,n,1 builtins) of characters defined by the PARPRO-
                     TECT environment variable and/or the P option.

              quote character
                     A member of the set(7,n,1 builtins) 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 ver-
                     tical 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(1,8) c
                     (at  the  beginning  if(3,n)  there  are none).  If body is 1,
                     place the divider just after the last non-space  non-body
                     character  in(1,8) c (at the beginning if(3,n) there is none), then
                     advance the divider over any immediately  following  spa-
                     ces.  The comprelen of S is the number of characters pre-
                     ceeding the divider.

              comsuflen
                     Given a non-empty sequence S of lines, let p be the  com-
                     prelen of S.  Let T be the set(7,n,1 builtins) of lines which result from
                     stripping the first p characters from  each  line  in(1,8)  S.
                     Let c be the longest common suffix of the lines in(1,8) T.  If
                     body is 0, place a divider just before the trailing  non-
                     body characters in(1,8) c (at the end if(3,n) there are none), then
                     advance the divider over all but the last of any  immedi-
                     ately  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(3,n) 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(3,n) the IP contains  at  least  two
                     lines;  otherwise, the comprelen (comsuflen) of the block
                     containing the IP, if(3,n) the block  contains  at  least  two
                     lines;  otherwise,  the  length of the longer of the pre-
                     fixes (suffixes) of the bodiless  lines  just  above  and
                     below  the block, if(3,n) 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 con-
                     tains more than one line, or if(3,n) quote is 0, then the aug-
                     mented  fallback  prelen  of the IP is simply fp.  Other-
                     wise, it is fp plus the number of quote characters  imme-
                     diately following the first fp characters of the line.

              quoteprefix
                     The  quoteprefix of a line is the longest string(3,n) of quote
                     characters appearing at the beginning of the line,  after
                     this string(3,n) 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.  Sup-
                     pose  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(3,n) stripped of its first p and last  s
                     characters,  would  be blank (or, if(3,n) 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(1,8) the middle is called its repeat  charac-
                     ter.   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  con-
                     tiguous  vacant  lines  lie  at the beginning or end of a
                     segment, they are  all  superfluous.   But  if(3,n)  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(3,n)  contiguous  blank
                     lines lie outside of any segments at the beginning or end
                     of the input, they are all superfluous.  But if(3,n) 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  pro-
                     tected  or  blank  lines, bounded above and below by pro-
                     tected lines, blank lines, and/or  the  beginning/end  of
                     the input.

              block  A contiguous subsequence of a segment containing no bodi-
                     less(1,3) 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(1,8) the OPTIONS section.)

              curious word
                     A  word  which  contains a terminal character c such that
                     there are no alphanumeric characters in(1,8) the word after c,
                     but  there  is at least one alphanumeric character in(1,8) 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(1,8) a single com-
       mand line argument, but there are exceptions:  The help, version(1,3,5), 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(1,3,5)   Causes  all  remaining  arguments to be ignored.  No input is
                 read.  "par 1.52" is printed on the output.  Of course,  this
                 will change in(1,8) future releases of Par.

       Bopset    op  is  a  single character, either an equal sign (=), a plus
                 sign (+), or a minus sign (-), and  set(7,n,1 builtins)  is  a  string(3,n)  using
                 charset  syntax.   If  op  is  an equal sign, the set(7,n,1 builtins) of body
                 characters is set(7,n,1 builtins) to the character set(7,n,1 builtins) defined by set(7,n,1 builtins).  If op
                 is  a  plus/minus  sign, the characters in(1,8) the set(7,n,1 builtins) defined by
                 set(7,n,1 builtins) are added/removed to/from the existing set(7,n,1 builtins) of body  char-
                 acters  defined  by  the PARBODY environment variable and any
                 previous B options.  It is okay to add  characters  that  are
                 already  in(1,8)  the  set(7,n,1 builtins) or to remove characters that are not in(1,8)
                 the set.

       Popset    Just like the B option, except that it applies to the set(7,n,1 builtins)  of
                 protective characters.

       Qopset    Just  like the B option, except that it applies to the set(7,n,1 builtins) of
                 quote characters.

       All remaining options are used to set(7,n,1 builtins) values of parameters.  Values set(7,n,1 builtins)
       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(3,n) left unset, are recomputed sepa-
       rately for each paragraph.

       The approximate role of each  variable  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(7,n,1 builtins) to any unsigned decimal integer less(1,3) 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(1,8) the  IP,  the
                 default  value  is  the  comprelen of all the lines in(1,8) 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(3,n)  it  had
                 been set(7,n,1 builtins) 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(1,8) the  IP,  the
                 default  value  is  the  comsuflen of all the lines of 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(3,n) it  had  been  set(7,n,1 builtins)
                 earlier.  (See also the h option.)

       T[Tab]    Tab  characters in(1,8) 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(1,8) 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(7,n,1 builtins) to
       either 0 or 1.  If the number is absent in(1,8) 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(1,8)  the  Terminology
                 section.)   If  body is 0, prefixes and suffixes may not con-
                 tain any body characters at all.  Defaults to 0.

       c[cap]    If cap is 1, all words are considered capitalized.  This cur-
                 rently   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 com-
                 prelen of the block.  Let a line's status be 1 if(3,n) its (p+1)st
                 character  is  a space, 0 otherwise.  Every line in(1,8) 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(1,3,5) options, or by errors) are sent to the  error(8,n)  stream
                 instead of the output stream.  Defaults to 0.

       e[expel]  If  expel  is 1, superfluous lines are withheld from the out-
                 put.  Defaults to 0.

       f[fit]    If fit is 1 and just is 0, par tries to make the lines in(1,8) the
                 OP  as  nearly  the same length as possible, even if(3,n) 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, when-
                 ever 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(1,8) 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(1,8) 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(1,8) the OP have length  width  (except
                 the last, if(3,n) 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 bodi-
                 less(1,3) lines, par supplies vacant lines between different  quo-
                 tation  nesting levels as follows:  For each pair of adjacent
                 lines in(1,8) 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  char-
                 acters  and  spaces  (or is empty), that line is truncated to
                 the longest common prefix of the two lines  (both  are  trun-
                 cated  if(3,n) 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(8,n) for an  input  word
                 to  contain  more  than L = (width - prefix - suffix) charac-
                 ters.  Otherwise, such words are chopped after each Lth char-
                 acter into shorter words.  Defaults to 0.

       t[touch]  Has  no  effect  if(3,n)  suffix is 0 or just is 1.  Otherwise, if(3,n)
                 touch is 0, all lines in(1,8) 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(3,n) it is 8 or less(1,3), and to a w option otherwise.

       If the value of any parameter is set(7,n,1 builtins) 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(8,n) if(3,n) width <= prefix + suffix.

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

       PARINIT   If set(7,n,1 builtins), par will  read(2,n,1 builtins)  command  line  options  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(7,n,1 builtins) of protective  characters,  using  charset
                 syntax.   If  PARPROTECT  is  not  set(7,n,1 builtins), the set(7,n,1 builtins) of protective
                 characters is initially empty.

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

       If a NUL character appears in(1,8) the value of an environment variable,  it
       and the rest of the string(3,n) 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(1,8) the lines.  If the last character  of  the
       input is a non-newline, a newline will be inferred immediately after it
       (but if(3,n) 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(2,n,1 builtins), have any NUL characters removed,
       and every white character (except newlines) turned into a space.  Actu-
       ally, 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(1,8) the input are transformed into empty lines in(1,8) the out-
       put.

       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 char-
       acters 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(1,8) 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 sec-
       tion), the first prefix characters and the last  suffix  characters  of
       each  input  line  are  removed and remembered.  It is an error(8,n) 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(1,8) 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(1,8)
       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(3,n)  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 short-
                 est and longest lines is as small as possible.

              3) The  shortest line is as long as possible, subject to proper-
                 ties 1 and 2.

              4) Let target be L if(3,n) fit is 0, or the  length  of  the  longest
                 line  if(3,n) 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 pur-
            poses 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(3,n) 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  pur-
            poses  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(1,8) each line.

            In  a  justified  paragraph,  every line must contain at least two
            words, but that's not always possible to accomplish.  If the para-
            graph cannot be justified, it is considered an error.

       If  the  number  of lines in(1,8) the resulting paragraph is less(1,3) 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 long-
       est 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(1,8) 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 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 first min(afp,prefix) of the charac-
              ters  are copied from the ones that were removed from the begin-
              ning 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 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 > 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 charac-
              ters are copied from the ones that were removed from the  begin-
              ning 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(8,n), an error(8,n) message will be printed to the output,
       and par will return EXIT_FAILURE.  If the error(8,n) is local  to  a  single
       paragraph,  the  preceeding paragraphs will have been output before the
       error(8,n) was detected.  Line numbers in(1,8) error(8,n) messages are local to the IP
       in(1,8)   which   the   error(8,n)  occurred.   All  error(8,n)  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(8,n) message would be futile if(3,n) an error(8,n)
       resulted from an output function, so par doesn't bother doing any error(8,n)
       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(1,8) the following
       example:

       Original paragraph (note that each line begins with 8 spaces):

          We the people of the United States,
          in(1,8) 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(1,8) 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(1,8) 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(1,8) conjunction with the text-filtering  features  of
       an  editor, such as the ! commands of vi.  You may wish to add the fol-
       lowing lines to your .exrc file:

          " use Bourne shell for speed:
          set(7,n,1 builtins) 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(1,8) vi, you can
       put the cursor anywhere in(1,8) it and type "**" (star(1,4) star(1,4)). If you need to
       supply  arguments  to par, you can type "* " (star(1,4) space) instead, then
       type the arguments.

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

       Before:

          /*   We the people of the United States, */
          /* in(1,8) 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(1,8)      */
          /* 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(1,8) 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(1,8)      */
          /* 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(1,8) 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(1,8) 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(1,8) */
          /* 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(1,8)   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(1,8) 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(1,8) 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(1,8) 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(1,8) 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(1,8) 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(1,8)
          > > 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(1,8) 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(1,8) 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(1,8) 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(1,8) 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(1,8) 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(1,2) 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(1,2) 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(1,2) 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(1,2) 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(1,2) from
          uncompress to compress.

       Before:

          I sure hope there's still room
          in(1,8) Dr. Jones' section of archaeology.
          I've heard he's the bestest.  [sic]

       After "par 50g":

          I sure hope there's still room in(1,8)
          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(1,8)
          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.

SEE ALSO
       par.doc

LIMITATIONS
       The guess feature guesses wrong in(1,8) 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 sen-
       tence.  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(1,8) the output, mainly to avoid creating the first  situation  (in(1,8)  case
       the  paragraph were to be fed back through par again).  This non-break-
       ing space policy does come in(1,8) handy for cases  like  "Mr. Johnson"  and
       "Jan. 1", though.

       The  guess  feature  only goes one way.  par can preserve wide sentence
       breaks in(1,8) a paragraph, or remove them, but it can't insert them if(3,n) they
       aren't already in(1,8) the input.

       If  you use tabs, you may not like the way par handles (or doesn't han-
       dle) 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(1,n) containing tabs gets(3,n) mangled when some-
       thing 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(3,n)
       everyone  stopped  using  tabs, so I'm doing my part by not letting par
       output them.  (Thanks to Eric 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 con-
       sider adding this capability in(1,8) a future release, but right now I'm not
       sure how I'd want it to work.

APOLOGIES
       Par began in(1,8) 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,3,5)  1.41  on
       1993-Oct-31  and  the release of version(1,3,5) 1.52 on 2001-Apr-29, no incor-
       rect behavior was reported).

       Back in(1,8) 1993 I had very little experience at writing documentation  for
       users(1,5),  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(3,n) 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(1,2,n)
       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(1,8) the program or in(1,8) the documentation), or if(3,n)
       you have any suggestions, please send(2,n) e-mail to:

              amc@cs.berkeley.edu

       When reporting a bug, please include the exact input and  command  line
       options  used,  and  the version(1,3,5) number of par, so that I can reproduce
       it.

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

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

       These addresses will change.  I'll try to leave forward pointers.



Par 1.52                          2001-Apr-29                           par(1)

References for this manual (incoming links)