1par(1)                           USER COMMANDS                          par(1)
2
3
4

NAME

6       par - filter for reformatting paragraphs
7

SYNOPSIS

9       par  [ help ] [ version ] [ Bopset ] [ Popset ] [ Qopset ] [ h[hang] ]
10            [ p[prefix] ] [ r[repeat] ] [ s[suffix] ] [ T[Tab] ] [ w[width] ]
11            [ b[body] ] [ c[cap] ] [ d[div] ] [ E[Err] ] [ e[expel] ]
12            [ f[fit] ] [ g[guess] ] [ j[just] ] [ l[last] ] [ q[quote] ]
13            [ R[Report] ] [ t[touch] ]
14

DESCRIPTION

16       par  is  a  filter  which  copies its input to its output, changing all
17       white characters (except newlines) to  spaces,  and  reformatting  each
18       paragraph.   Paragraphs are separated by protected, blank, and bodiless
19       lines (see the TERMINOLOGY section  for  definitions),  and  optionally
20       delimited by indentation (see the d option in the OPTIONS section).
21
22       Each  output  paragraph is generated from the corresponding input para‐
23       graph as follows:
24
25           1) An optional prefix and/or suffix  is  removed  from  each  input
26              line.
27
28           2) The remainder is divided into words (separated by spaces).
29
30           3) The  words  are  joined into lines to make an eye-pleasing para‐
31              graph.
32
33           4) The prefixes and suffixes are reattached.
34
35       If there are suffixes, spaces are inserted before them so that they all
36       end in the same column.
37

QUICK START

39       par  is  necessarily complex.  For those who wish to use it immediately
40       and understand it later, assign the PARINIT  environment  variable  the
41       following value:
42
43              rTbgqR B=.,?_A_a Q=_s>|
44
45       The  spaces,  question  mark,  greater-than sign, and vertical bar will
46       probably have to be escaped or quoted to prevent your shell from inter‐
47       preting them.
48
49       The  documentation,  though  precise, is unfortunately not well-written
50       for the end-user.  Your best  bet  is  probably  to  read  quickly  the
51       DESCRIPTION,  TERMINOLOGY, OPTIONS, and ENVIRONMENT sections, then read
52       carefully the EXAMPLES section, referring back to the OPTIONS and  TER‐
53       MINOLOGY sections as needed.
54
55       For the "power user", a full understanding of par will require multiple
56       readings of the TERMINOLOGY, OPTIONS, DETAILS, and EXAMPLES sections.
57

TERMINOLOGY

59       Miscellaneous terms:
60
61              charset syntax
62                     A way of representing a set of characters  as  a  string.
63                     The set includes exactly those characters which appear in
64                     the string, except that the underscore (_) is  an  escape
65                     character.  Whenever it appears, it must begin one of the
66                     following escape sequences:
67
68                        __ = an underscore
69
70                        _s = a space
71
72                        _b = a backslash (\)
73
74                        _q = a single quote (')
75
76                        _Q = a double quote (")
77
78                        _A = all upper case letters
79
80                        _a = all lower case letters
81
82                        _0 = all decimal digits
83
84                      _xhh = the character represented by the two  hexadecimal
85                             digits hh (which may be upper or lower case)
86
87                     The  NUL  character must not appear in the string, but it
88                     may be included in the set with the _x00 sequence.
89
90              error  A condition which causes par to abort.  See the  DIAGNOS‐
91                     TICS section.
92
93              IP     Input paragraph.
94
95              OP     Output paragraph.
96
97              parameter
98                     A  symbol  which  may  take  on unsigned integral values.
99                     There are several  parameters  whose  values  affect  the
100                     behavior of par.  Parameters can be assigned values using
101                     command line options.
102
103       Types of characters:
104
105              alphanumeric character
106                     An upper case  letter,  lower  case  letter,  or  decimal
107                     digit.
108
109              body character
110                     A  member of the set of characters defined by the PARBODY
111                     environment variable (see the ENVIRONMENT section) and/or
112                     the B option (see the OPTIONS section).
113
114              protective character
115                     A member  of the set of characters defined by the PARPRO‐
116                     TECT environment variable and/or the P option.
117
118              quote character
119                     A member of the set of characters defined by the PARQUOTE
120                     environment variable and/or the Q option.
121
122              terminal character
123                     A period, question mark, exclamation point, or colon.
124
125              white character
126                     A space, formfeed, newline, carriage return, tab, or ver‐
127                     tical tab.
128
129       Functions:
130
131              comprelen
132                     Given a non-empty sequence S of lines,  let  c  be  their
133                     longest common prefix.  If the parameter body is 0, place
134                     a divider just after the leading non-body characters in c
135                     (at  the  beginning  if  there  are none).  If body is 1,
136                     place the divider just after the last non-space  non-body
137                     character  in c (at the beginning if there is none), then
138                     advance the divider over any immediately  following  spa‐
139                     ces.  The comprelen of S is the number of characters pre‐
140                     ceeding the divider.
141
142              comsuflen
143                     Given a non-empty sequence S of lines, let p be the  com‐
144                     prelen of S.  Let T be the set of lines which result from
145                     stripping the first p characters from  each  line  in  S.
146                     Let c be the longest common suffix of the lines in T.  If
147                     body is 0, place a divider just before the trailing  non-
148                     body characters in c (at the end if there are none), then
149                     advance the divider over all but the last of any  immedi‐
150                     ately  following spaces.  If body is 1, place the divider
151                     just before the first non-space non-body character,  then
152                     back up the divider over one immediately preceeding space
153                     if there is one.  The comsuflen of S  is  the  number  of
154                     characters following the divider.
155
156              fallback prelen (suflen)
157                     The  fallback  prelen (suflen) of an IP is: the comprelen
158                     (comsuflen) of the IP, if the IP contains  at  least  two
159                     lines;  otherwise, the comprelen (comsuflen) of the block
160                     containing the IP, if the block  contains  at  least  two
161                     lines;  otherwise,  the  length of the longer of the pre‐
162                     fixes (suffixes) of the bodiless  lines  just  above  and
163                     below  the block, if the segment containing the block has
164                     any bodiless lines; otherwise, 0.   (See  below  for  the
165                     definitions of block, segment, and bodiless line.)
166
167              augmented fallback prelen
168                     Let  fp  be the fallback prelen of an IP.  If the IP con‐
169                     tains more than one line, or if quote is 0, then the aug‐
170                     mented  fallback  prelen  of the IP is simply fp.  Other‐
171                     wise, it is fp plus the number of quote characters  imme‐
172                     diately following the first fp characters of the line.
173
174              quoteprefix
175                     The  quoteprefix of a line is the longest string of quote
176                     characters appearing at the beginning of the line,  after
177                     this string has been stripped of any trailing spaces.
178
179       Types of lines:
180
181              blank line
182                     An  empty  line,  or  a line whose first character is not
183                     protective and which contains only spaces.
184
185              protected line
186                     An input line whose first character is protective.
187
188              bodiless line
189                     A line which is order k bodiless for some k.
190
191              order k bodiless line
192                     There is no such thing as an order 0 bodiless line.  Sup‐
193                     pose  S  is  a a contiguous subsequence of a segment (see
194                     below) containing at least two lines, containing no order
195                     k-1  bodiless lines, bounded above and below by order k-1
196                     bodiless lines and/or the beginning/end of  the  segment.
197                     Let  p  and  s  be the comprelen and comsuflen of S.  Any
198                     member of S which, if stripped of its first p and last  s
199                     characters,  would  be blank (or, if the parameter repeat
200                     is non-zero, would consist of the same character repeated
201                     at least repeat times), is order k bodiless.  The first p
202                     characters of the bodiless line comprise its prefix;  the
203                     last  s  characters  comprise  its suffix.  The character
204                     which repeats in the middle is called its repeat  charac‐
205                     ter.   If  the  middle is empty, the space is taken to be
206                     its repeat character.
207
208              vacant line
209                     A bodiless line whose repeat character is the space.
210
211              superfluous line
212                     Only blank and vacant lines may be superfluous.  If  con‐
213                     tiguous  vacant  lines  lie  at the beginning or end of a
214                     segment, they are  all  superfluous.   But  if  they  lie
215                     between  two  non-vacant lines within a segment, then all
216                     are superfluous except one—the  one  which  contains  the
217                     fewest  non-spaces.   In  case of a tie, the first of the
218                     tied lines is chosen.   Similarly,  if  contiguous  blank
219                     lines lie outside of any segments at the beginning or end
220                     of the input, they are all superfluous.  But if they  lie
221                     between two segments and/or protected lines, then all are
222                     superfluous except the first.
223
224       Groups of lines:
225
226              segment
227                     A contiguous sequence of input lines containing  no  pro‐
228                     tected  or  blank  lines, bounded above and below by pro‐
229                     tected lines, blank lines, and/or  the  beginning/end  of
230                     the input.
231
232              block  A contiguous subsequence of a segment containing no bodi‐
233                     less lines, bounded above and  below  by  bodiless  lines
234                     and/or the beginning/end of the segment.
235
236       Types of words:
237
238              capitalized word
239                     If  the  parameter  cap  is  0, a capitalized word is one
240                     which contains at least one alphanumeric character, whose
241                     first  alphanumeric character is not a lower case letter.
242                     If cap is 1, every word is considered a capitalized word.
243                     (See the c option in the OPTIONS section.)
244
245              curious word
246                     A  word  which  contains a terminal character c such that
247                     there are no alphanumeric characters in the word after c,
248                     but  there  is at least one alphanumeric character in the
249                     word before c.
250

OPTIONS

252       Any command line argument may begin with one minus sign  (-)  which  is
253       ignored.   Generally,  more than one option may appear in a single com‐
254       mand line argument, but there are exceptions:  The help, version, B, P,
255       and Q options must have whole arguments all to themselves.
256
257       help      Causes  all  remaining  arguments to be ignored.  No input is
258                 read.  A usage message  is  printed  on  the  output  briefly
259                 describing the options used by par.
260
261       version   Causes  all  remaining  arguments to be ignored.  No input is
262                 read.  "par 1.52" is printed on the output.  Of course,  this
263                 will change in future releases of Par.
264
265       Bopset    op  is  a  single character, either an equal sign (=), a plus
266                 sign (+), or a minus sign (-), and  set  is  a  string  using
267                 charset  syntax.   If  op  is  an equal sign, the set of body
268                 characters is set to the character set defined by set.  If op
269                 is  a  plus/minus  sign, the characters in the set defined by
270                 set are added/removed to/from the existing set of body  char‐
271                 acters  defined  by  the PARBODY environment variable and any
272                 previous B options.  It is okay to add  characters  that  are
273                 already  in  the  set or to remove characters that are not in
274                 the set.
275
276       Popset    Just like the B option, except that it applies to the set  of
277                 protective characters.
278
279       Qopset    Just  like the B option, except that it applies to the set of
280                 quote characters.
281
282       All remaining options are used to set values of parameters.  Values set
283       by  command line options hold for all paragraphs.  Unset parameters are
284       given default values.  Any parameters whose default  values  depend  on
285       the  IP (namely prefix and suffix), if left unset, are recomputed sepa‐
286       rately for each paragraph.
287
288       The approximate role of each  variable  is  described  here.   See  the
289       DETAILS section for the rest of the story.
290
291       The first six parameters, hang, prefix, repeat, suffix, Tab, and width,
292       may be set to any unsigned decimal integer less than 10000.
293
294       h[hang]   Mainly affects the  default  values  of  prefix  and  suffix.
295                 Defaults  to  0.   If the h option is given without a number,
296                 the value 1 is inferred.  (See also the p and s options.)
297
298       p[prefix] The first prefix characters of each line of the OP are copied
299                 from the first prefix characters of the corresponding line of
300                 the IP.  If there are more than hang+1 lines in the  IP,  the
301                 default  value  is  the  comprelen of all the lines in the IP
302                 except the first hang of them.  Otherwise, the default  value
303                 is  the augmented fallback prelen of the IP.  If the p option
304                 is given without a number, prefix is unset, even  if  it  had
305                 been set earlier.  (See also the h and q options.)
306
307       r[repeat] If  repeat  is  non-zero,  bodiless  lines have the number of
308                 instances of their repeat characters increased  or  decreased
309                 until  the  length  of the line is width.  The exact value of
310                 repeat affects the definition of bodiless line.  Defaults  to
311                 0.  If the r option is given without a number, the value 3 is
312                 inferred.  (See also the w option.)
313
314       s[suffix] The last suffix characters of each line of the OP are  copied
315                 from  the last suffix characters of the corresponding line of
316                 the IP.  If there are more than hang+1 lines in the  IP,  the
317                 default  value  is  the  comsuflen of all the lines of the IP
318                 except the first hang of them.  Otherwise, the default  value
319                 is  the  fallback suflen of the IP.  If the s option is given
320                 without a number, suffix is unset, even if it  had  been  set
321                 earlier.  (See also the h option.)
322
323       T[Tab]    Tab  characters in the input are expanded to spaces, assuming
324                 tab stops every Tab columns.  Must not be 0.  Defaults to  1.
325                 If  the  T  option  is given without a number, the value 8 is
326                 inferred.
327
328       w[width]  No line in the OP may contain more than width characters, not
329                 including  the  trailing newlines.  Defaults to 72.  If the w
330                 option is given without a number, the value 79 is inferred.
331
332       The remaining thirteen parameters, body, cap,  div,  Err,  expel,  fit,
333       guess,  invis,  just,  last,  quote,  Report,  and touch, may be set to
334       either 0 or 1.  If the number is absent in the option, the value  1  is
335       inferred.
336
337       b[body]   If  body  is  1,  prefixes  may not contain any trailing body
338                 characters, and suffixes may not  contain  any  leading  body
339                 characters.  (Actually, the situation is complicated by space
340                 characters.  See comprelen and comsuflen in  the  Terminology
341                 section.)   If  body is 0, prefixes and suffixes may not con‐
342                 tain any body characters at all.  Defaults to 0.
343
344       c[cap]    If cap is 1, all words are considered capitalized.  This cur‐
345                 rently   affects  only  the  application  of  the  g  option.
346                 Defaults to 0.
347
348       d[div]    If div is 0, each block becomes an IP.  If  div  is  1,  each
349                 block  is  subdivided into IPs as follows:  Let p be the com‐
350                 prelen of the block.  Let a line's status be 1 if its (p+1)st
351                 character  is  a space, 0 otherwise.  Every line in the block
352                 whose status is the same as the status of the first line will
353                 begin a new paragraph.  Defaults to 0.
354
355       E[Err]    If  Err  is  1,  messages to the user (caused by the help and
356                 version options, or by errors) are sent to the  error  stream
357                 instead of the output stream.  Defaults to 0.
358
359       e[expel]  If  expel  is 1, superfluous lines are withheld from the out‐
360                 put.  Defaults to 0.
361
362       f[fit]    If fit is 1 and just is 0, par tries to make the lines in the
363                 OP  as  nearly  the same length as possible, even if it means
364                 making the OP narrower.  Defaults to  0.   (See  also  the  j
365                 option.)
366
367       g[guess]  If  guess  is 1, then when par is choosing line breaks, when‐
368                 ever it encounters a curious word followed by  a  capitalized
369                 word,  it takes one of two special actions.  If the two words
370                 are separated by a single space in the input,  they  will  be
371                 merged into one word with an embedded non-breaking space.  If
372                 the two words are separated by more than one space, or  by  a
373                 line  break,  par  will insure that they are separated by two
374                 spaces, or by a line break, in the output.  Defaults to 0.
375
376       i[invis]  If invis is 1, then vacant lines inserted because quote is  1
377                 are  invisible; that is, they are not output.  If quote is 0,
378                 invis has no  effect.   Defaults  to  0.   (See  also  the  q
379                 option.)
380
381       j[just]   If  just is 1, par justifies the OP, inserting spaces between
382                 words so that all lines in the OP have length  width  (except
383                 the last, if last is 0).  Defaults to 0.  (See also the w, l,
384                 and f options.)
385
386       l[last]   If last is 1, par tries to make the last line of the OP about
387                 the same length as the others.  Defaults to 0.
388
389       q[quote]  If  quote is 1, then before each segment is scanned for bodi‐
390                 less lines, par supplies vacant lines between different  quo‐
391                 tation  nesting levels as follows:  For each pair of adjacent
392                 lines in the segment, (scanned from the top down) which  have
393                 different  quoteprefixes,  one  of  two actions is taken.  If
394                 invis is 0, and either line consists entirely of quote  char‐
395                 acters  and  spaces  (or is empty), that line is truncated to
396                 the longest common prefix of the two lines  (both  are  trun‐
397                 cated  if both qualify).  Otherwise, a line consisting of the
398                 longest common prefix of the two lines  is  inserted  between
399                 them.   quote  also  affects  the  default  value  of prefix.
400                 Defaults to 0.  (See also the p and i options.)
401
402       R[Report] If Report is 1, it is considered an error for an  input  word
403                 to  contain  more  than L = (width - prefix - suffix) charac‐
404                 ters.  Otherwise, such words are chopped after each Lth char‐
405                 acter into shorter words.  Defaults to 0.
406
407       t[touch]  Has  no  effect  if  suffix is 0 or just is 1.  Otherwise, if
408                 touch is 0, all lines in the OP have length width.  If  touch
409                 is 1, the length of the lines is decreased until the suffixes
410                 touch the body of the OP.  Defaults to the logical OR of  fit
411                 and last.  (See also the s, j, w, f, and l options.)
412
413       If  an  argument begins with a number, that number is assumed to belong
414       to a p option if it is 8 or less, and to a w option otherwise.
415
416       If the value of any parameter is set more than once, the last value  is
417       used.   When  unset  parameters  are  assigned default values, hang and
418       quote are assigned before prefix, and fit and last are assigned  before
419       touch (because of the dependencies).
420
421       It is an error if width <= prefix + suffix.
422

ENVIRONMENT

424       PARBODY   Determines the initial set of body characters (which are used
425                 for determining comprelens  and  comsuflens),  using  charset
426                 syntax.  If PARBODY is not set, the set of body characters is
427                 initially empty.
428
429       PARINIT   If set, par will  read  command  line  options  from  PARINIT
430                 before it reads them from the command line.  Within the value
431                 of PARINIT, arguments are separated by white characters.
432
433       PARPROTECT
434                 Determines the set of protective  characters,  using  charset
435                 syntax.   If  PARPROTECT  is  not  set, the set of protective
436                 characters is initially empty.
437
438       PARQUOTE  Determines the set of quote characters, using charset syntax.
439                 If PARQUOTE is not set, the set of quote characters initially
440                 contains only the greater-than sign (>) and the space.
441
442       If a NUL character appears in the value of an environment variable,  it
443       and the rest of the string will not be seen by par.
444
445       Note  that the PARINIT variable, together with the B, P, and Q options,
446       renders the other environment variables unnecessary.  They are included
447       for backward compatibility.
448

DETAILS

450       Lines  are  terminated  by newline characters, but the newlines are not
451       considered to be included in the lines.  If the last character  of  the
452       input is a non-newline, a newline will be inferred immediately after it
453       (but if the input is empty, no newline will be inferred; the number  of
454       input  lines  will  be  0).   Thus, the input can always be viewed as a
455       sequence of lines.
456
457       Protected lines are copied unchanged from the input to the output.  All
458       other  input  lines, as they are read, have any NUL characters removed,
459       and every white character (except newlines) turned into a space.  Actu‐
460       ally, each tab character is turned into Tab - (n % Tab) spaces, where n
461       is the number of characters preceeding the tab character  on  the  line
462       (evaluated after earlier tab characters have been expanded).
463
464       Blank  lines  in the input are transformed into empty lines in the out‐
465       put.
466
467       If repeat is 0, all bodiless lines are vacant, and they are all  simply
468       stripped  of  trailing spaces before being output.  If repeat is not 0,
469       only vacant lines whose suffixes have length 0 are  treated  that  way;
470       other bodiless lines have the number of instances of their repeat char‐
471       acters increased or decreased until the length of the line is width.
472
473       If expel is 1, superfluous lines are not output.  If  quote  and  invis
474       are both 1, there may be invisible lines; they are not output.
475
476       The  input  is  divided  into  segments, which are divided into blocks,
477       which are divided into IPs.  The exact process depends on the values of
478       quote  and  div (see q and d in the OPTIONS section).  The remainder of
479       this section describes the process which is  applied  independently  to
480       each IP to construct the corresponding OP.
481
482       After the values of the parameters are determined (see the OPTIONS sec‐
483       tion), the first prefix characters and the last  suffix  characters  of
484       each  input  line  are  removed and remembered.  It is an error for any
485       line to contain fewer than prefix + suffix characters.
486
487       The remaining text is treated as a sequence of characters,  not  lines.
488       The text is broken into words, which are separated by spaces.  That is,
489       a word is a maximal sub-sequence of non-spaces.  If guess  is  1,  some
490       words  might  be merged (see g in the OPTIONS section).  The first word
491       includes any spaces that preceed it on the same line.
492
493       Let L = width - prefix - suffix.
494
495       If Report is 0, some words may get chopped up at this point (see  R  in
496       the OPTIONS section).
497
498       The words are reassembled, preserving their order, into lines.  If just
499       is 0, adjacent words within a line are separated by a single space, (or
500       sometimes  two  if  guess is 1), and line breaks are chosen so that the
501       paragraph satisfies the following properties:
502
503              1) No line contains more than L characters.
504
505              2) If fit is 1, the difference between the lengths of the short‐
506                 est and longest lines is as small as possible.
507
508              3) The  shortest line is as long as possible, subject to proper‐
509                 ties 1 and 2.
510
511              4) Let target be L if fit is 0, or the  length  of  the  longest
512                 line  if fit is 1.  The sum of the squares of the differences
513                 between target and the lengths of the lines is  as  small  as
514                 possible, subject to properties 1, 2, and 3.
515
516            If  last is 0, the last line does not count as a line for the pur‐
517            poses of properties 2, 3, and 4 above.
518
519            If all the words fit on a single line, the  properties  as  worded
520            above  don't  make  much  sense.  In that case, no line breaks are
521            inserted.
522
523       If just is 1, adjacent words within a line are separated by  one  space
524       (or  sometimes  two if guess is 1) plus zero or more extra spaces.  The
525       value of fit is disregarded, and line breaks are  chosen  so  that  the
526       paragraph satisfies the following properties:
527
528              1) Every line contains exactly L characters.
529
530              2) The  largest  inter-word gap is as small as possible, subject
531                 to property 1.  (An inter-word gap consists only of the extra
532                 spaces, not the regular spaces.)
533
534              3) The  sum of the squares of the lengths of the inter-word gaps
535                 is as small as possible, subject to properties 1 and 2.
536
537            If last is 0, the last line does not count as a line for the  pur‐
538            poses  of property 1, and it does not require or contain any extra
539            spaces.
540
541            Extra spaces are distributed as uniformly as  possible  among  the
542            inter-word gaps in each line.
543
544            In  a  justified  paragraph,  every line must contain at least two
545            words, but that's not always possible to accomplish.  If the para‐
546            graph cannot be justified, it is considered an error.
547
548       If  the  number  of lines in the resulting paragraph is less than hang,
549       empty lines are added at the end to bring the number  of  lines  up  to
550       hang.
551
552       If just is 0 and touch is 1, L is changed to be the length of the long‐
553       est line.
554
555       If suffix is not 0, each line is padded at the end with spaces to bring
556       its length up to L.
557
558       To  each  line  is prepended prefix characters.  Let n be the number of
559       lines in the IP, let afp be the augmented fallback prelen  of  the  IP,
560       and  let fs be the fallback suflen of the IP.  The characters which are
561       prepended to the ith line are chosen as follows:
562
563           1) If i <= n, the characters are copied from  the  ones  that  were
564              removed from the beginning of the nth input line.
565
566           2) If  i  >  n > hang, the characters are copied from the ones that
567              were removed from the beginning of the last input line.
568
569           3) If i > n and n <= hang, the first min(afp,prefix) of the charac‐
570              ters  are copied from the ones that were removed from the begin‐
571              ning of the last input line, and the rest are all spaces.
572
573       Then to each line is appended suffix characters.  The characters  which
574       are appended to the ith line are chosen as follows:
575
576           1) If  i  <=  n,  the characters are copied from the ones that were
577              removed from the end of the nth input line.
578
579           2) If i > n > hang, the characters are copied from  the  ones  that
580              were removed from the end of the last input line.
581
582           3) If  i > n and n <= hang, the first min(fs,suffix) of the charac‐
583              ters are copied from the ones that were removed from the  begin‐
584              ning of the last input line, and the rest are all spaces.
585
586       Finally, the lines are printed to the output as the OP.
587

DIAGNOSTICS

589       If there are no errors, par returns EXIT_SUCCESS (see <stdlib.h>).
590
591       If  there  is an error, an error message will be printed to the output,
592       and par will return EXIT_FAILURE.  If the error is local  to  a  single
593       paragraph,  the  preceeding paragraphs will have been output before the
594       error was detected.  Line numbers in error messages are local to the IP
595       in   which   the   error  occurred.   All  error  messages  begin  with
596       "par error:" on a line by itself.  Error  messages  concerning  command
597       line  or  environment variable syntax are accompanied by the same usage
598       message that the help option produces.
599
600       Of course, trying to print an error message would be futile if an error
601       resulted from an output function, so par doesn't bother doing any error
602       checking on output functions.
603

EXAMPLES

605       The superiority of par's dynamic programming algorithm  over  a  greedy
606       algorithm  (such  as  the one used by fmt) can be seen in the following
607       example:
608
609       Original paragraph (note that each line begins with 8 spaces):
610
611          We the people of the United States,
612          in order to form a more perfect union,
613          establish justice,
614          insure domestic tranquility,
615          provide for the common defense,
616          promote the general welfare,
617          and secure the blessing of liberty
618          to ourselves and our posterity,
619          do ordain and establish the Constitution
620          of the United States of America.
621
622       After a greedy algorithm with width = 39:
623
624          We the people of the United
625          States, in order to form a more
626          perfect union, establish
627          justice, insure domestic
628          tranquility, provide for the
629          common defense, promote the
630          general welfare, and secure the
631          blessing of liberty to
632          ourselves and our posterity, do
633          ordain and establish the
634          Constitution of the United
635          States of America.
636
637       After "par 39":
638
639          We the people of the United
640          States, in order to form a
641          more perfect union, establish
642          justice, insure domestic
643          tranquility, provide for the
644          common defense, promote the
645          general welfare, and secure
646          the blessing of liberty to
647          ourselves and our posterity,
648          do ordain and establish the
649          Constitution of the United
650          States of America.
651
652       The line breaks chosen by par are clearly more eye-pleasing.
653
654       par is most useful in conjunction with the text-filtering  features  of
655       an  editor, such as the ! commands of vi.  You may wish to add the fol‐
656       lowing lines to your .exrc file:
657
658          " use Bourne shell for speed:
659          set shell=/bin/sh
660          "
661          " reformat paragraph with no arguments:
662          map ** {!}par^M}
663          "
664          " reformat paragraph with arguments:
665          map *^V  {!}par
666
667       Note that the leading spaces must be removed, and that what is shown as
668       ^M and ^V really need to be ctrl-M and ctrl-V.  Also note that the last
669       map command contains two spaces following the ctrl-V, plus one  at  the
670       end of the line.
671
672       To  reformat a simple paragraph delimited by blank lines in vi, you can
673       put the cursor anywhere in it and type "**" (star star). If you need to
674       supply  arguments  to par, you can type "* " (star space) instead, then
675       type the arguments.
676
677       The rest of this section is a series of before-and-after pictures show‐
678       ing  some  typical uses of par.  In all cases, no environment variables
679       are set.
680
681       Before:
682
683          /*   We the people of the United States, */
684          /* in order to form a more perfect union, */
685          /* establish justice, */
686          /* insure domestic tranquility, */
687          /* provide for the common defense, */
688          /* promote the general welfare, */
689          /* and secure the blessing of liberty */
690          /* to ourselves and our posterity, */
691          /* do ordain and establish the Constitution */
692          /* of the United States of America. */
693
694       After "par 59":
695
696          /*   We the people of the United States, in      */
697          /* order to form a more perfect union, establish */
698          /* justice, insure domestic tranquility, provide */
699          /* for the common defense, promote the general   */
700          /* welfare, and secure the blessing of liberty   */
701          /* to ourselves and our posterity, do ordain     */
702          /* and establish the Constitution of the United  */
703          /* States of America.                            */
704
705       Or after "par 59f":
706
707          /*   We the people of the United States,  */
708          /* in order to form a more perfect union, */
709          /* establish justice, insure domestic     */
710          /* tranquility, provide for the common    */
711          /* defense, promote the general welfare,  */
712          /* and secure the blessing of liberty to  */
713          /* ourselves and our posterity, do ordain */
714          /* and establish the Constitution of the  */
715          /* United States of America.              */
716
717       Or after "par 59l":
718
719          /*   We the people of the United States, in      */
720          /* order to form a more perfect union, establish */
721          /* justice, insure domestic tranquility,         */
722          /* provide for the common defense, promote       */
723          /* the general welfare, and secure the           */
724          /* blessing of liberty to ourselves and our      */
725          /* posterity, do ordain and establish the        */
726          /* Constitution of the United States of America. */
727
728       Or after "par 59lf":
729
730          /*   We the people of the United States,  */
731          /* in order to form a more perfect union, */
732          /* establish justice, insure domestic     */
733          /* tranquility, provide for the common    */
734          /* defense, promote the general welfare,  */
735          /* and secure the blessing of liberty     */
736          /* to ourselves and our posterity, do     */
737          /* ordain and establish the Constitution  */
738          /* of the United States of America.       */
739
740       Or after "par 59lft0":
741
742          /*   We the people of the United States,         */
743          /* in order to form a more perfect union,        */
744          /* establish justice, insure domestic            */
745          /* tranquility, provide for the common           */
746          /* defense, promote the general welfare,         */
747          /* and secure the blessing of liberty            */
748          /* to ourselves and our posterity, do            */
749          /* ordain and establish the Constitution         */
750          /* of the United States of America.              */
751
752       Or after "par 59j":
753
754          /*   We  the people  of  the  United States,  in */
755          /* order to form a more perfect union, establish */
756          /* justice, insure domestic tranquility, provide */
757          /* for the  common defense, promote  the general */
758          /* welfare, and  secure the blessing  of liberty */
759          /* to ourselves and our posterity, do ordain and */
760          /* establish  the  Constitution  of  the  United */
761          /* States of America.                            */
762
763       Or after "par 59jl":
764
765          /*   We  the   people  of  the   United  States, */
766          /* in   order    to   form   a    more   perfect */
767          /* union,  establish  justice,  insure  domestic */
768          /* tranquility, provide for  the common defense, */
769          /* promote  the  general   welfare,  and  secure */
770          /* the  blessing  of  liberty to  ourselves  and */
771          /* our  posterity, do  ordain and  establish the */
772          /* Constitution of the United States of America. */
773
774       Before:
775
776          Preamble      We the people of the United States,
777          to the US     in order to form
778          Constitution  a more perfect union,
779                        establish justice,
780                        insure domestic tranquility,
781                        provide for the common defense,
782                        promote the general welfare,
783                        and secure the blessing of liberty
784                        to ourselves and our posterity,
785                        do ordain and establish
786                        the Constitution
787                        of the United States of America.
788
789       After "par 52h3":
790
791          Preamble      We the people of the United
792          to the US     States, in order to form a
793          Constitution  more perfect union, establish
794                        justice, insure domestic
795                        tranquility, provide for the
796                        common defense, promote the
797                        general welfare, and secure
798                        the blessing of liberty to
799                        ourselves and our posterity,
800                        do ordain and establish the
801                        Constitution of the United
802                        States of America.
803
804       Before:
805
806           1  We the people of the United States,
807           2  in order to form a more perfect union,
808           3  establish justice,
809           4  insure domestic tranquility,
810           5  provide for the common defense,
811           6  promote the general welfare,
812           7  and secure the blessing of liberty
813           8  to ourselves and our posterity,
814           9  do ordain and establish the Constitution
815          10  of the United States of America.
816
817       After "par 59p12l":
818
819           1  We the people of the United States, in order to
820           2  form a more perfect union, establish justice,
821           3  insure domestic tranquility, provide for the
822           4  common defense, promote the general welfare,
823           5  and secure the blessing of liberty to ourselves
824           6  and our posterity, do ordain and establish the
825           7  Constitution of the United States of America.
826
827       Before:
828
829          > > We the people
830          > > of the United States,
831          > > in order to form a more perfect union,
832          > > establish justice,
833          > > ensure domestic tranquility,
834          > > provide for the common defense,
835          >
836          > Promote the general welfare,
837          > and secure the blessing of liberty
838          > to ourselves and our posterity,
839          > do ordain and establish
840          > the Constitution of the United States of America.
841
842       After "par 52":
843
844          > > We the people of the United States, in
845          > > order to form a more perfect union,
846          > > establish justice, ensure domestic
847          > > tranquility, provide for the common
848          > > defense,
849          >
850          > Promote the general welfare, and secure
851          > the blessing of liberty to ourselves and
852          > our posterity, do ordain and establish
853          > the Constitution of the United States of
854          > America.
855
856       Before:
857
858          >   We the people
859          > of the United States,
860          > in order to form a more perfect union,
861          > establish justice,
862          > ensure domestic tranquility,
863          > provide for the common defense,
864          >   Promote the general welfare,
865          > and secure the blessing of liberty
866          > to ourselves and our posterity,
867          > do ordain and establish
868          > the Constitution of the United States of America.
869
870       After "par 52d":
871
872          >   We the people of the United States,
873          > in order to form a more perfect union,
874          > establish justice, ensure domestic
875          > tranquility, provide for the common
876          > defense,
877          >   Promote the general welfare, and secure
878          > the blessing of liberty to ourselves and
879          > our posterity, do ordain and establish
880          > the Constitution of the United States of
881          > America.
882
883       Before:
884
885          # 1. We the people of the United States.
886          # 2. In order to form a more perfect union.
887          # 3. Establish justice, ensure domestic
888          #    tranquility.
889          # 4. Provide for the common defense
890          # 5. Promote the general welfare.
891          # 6. And secure the blessing of liberty
892          #    to ourselves and our posterity.
893          # 7. Do ordain and establish the Constitution.
894          # 8. Of the United States of America.
895
896       After "par 37p13dh":
897
898          # 1. We the people of the
899          #    United States.
900          # 2. In order to form a more
901          #    perfect union.
902          # 3. Establish justice,
903          #    ensure domestic
904          #    tranquility.
905          # 4. Provide for the common
906          #    defense
907          # 5. Promote the general
908          #    welfare.
909          # 6. And secure the blessing
910          #    of liberty to ourselves
911          #    and our posterity.
912          # 7. Do ordain and establish
913          #    the Constitution.
914          # 8. Of the United States of
915          #    America.
916
917       Before:
918
919          /*****************************************/
920          /*   We the people of the United States, */
921          /* in order to form a more perfect union, */
922          /* establish justice, insure domestic    */
923          /* tranquility,                          */
924          /*                                       */
925          /*                                       */
926          /*   [ provide for the common defense, ] */
927          /*   [ promote the general welfare,    ] */
928          /*   [ and secure the blessing of liberty ] */
929          /*   [ to ourselves and our posterity, ] */
930          /*   [                                 ] */
931          /*                                       */
932          /* do ordain and establish the Constitution */
933          /* of the United States of America.       */
934          /******************************************/
935
936       After "par 42r":
937
938          /********************************/
939          /*   We the people of the       */
940          /* United States, in order to   */
941          /* form a more perfect union,   */
942          /* establish justice, insure    */
943          /* domestic tranquility,        */
944          /*                              */
945          /*                              */
946          /*   [ provide for the common ] */
947          /*   [ defense, promote the   ] */
948          /*   [ general welfare, and   ] */
949          /*   [ secure the blessing of ] */
950          /*   [ liberty to ourselves   ] */
951          /*   [ and our posterity,     ] */
952          /*   [                        ] */
953          /*                              */
954          /* do ordain and establish the  */
955          /* Constitution of the United   */
956          /* States of America.           */
957          /********************************/
958
959       Or after "par 42re":
960
961          /********************************/
962          /*   We the people of the       */
963          /* United States, in order to   */
964          /* form a more perfect union,   */
965          /* establish justice, insure    */
966          /* domestic tranquility,        */
967          /*                              */
968          /*   [ provide for the common ] */
969          /*   [ defense, promote the   ] */
970          /*   [ general welfare, and   ] */
971          /*   [ secure the blessing of ] */
972          /*   [ liberty to ourselves   ] */
973          /*   [ and our posterity,     ] */
974          /*                              */
975          /* do ordain and establish the  */
976          /* Constitution of the United   */
977          /* States of America.           */
978          /********************************/
979
980       Before:
981
982          Joe Public writes:
983          > Jane Doe writes:
984          > >
985          > >
986          > > I can't find the source for uncompress.
987          > Oh no, not again!!!
988          >
989          >
990          > Isn't there a FAQ for this?
991          >
992          >
993          That wasn't very helpful, Joe. Jane,
994          just make a link from uncompress to compress.
995
996       After "par 40q":
997
998          Joe Public writes:
999
1000          > Jane Doe writes:
1001          >
1002          >
1003          > > I can't find the source for
1004          > > uncompress.
1005          >
1006          > Oh no, not again!!!
1007          >
1008          >
1009          > Isn't there a FAQ for this?
1010          >
1011
1012          That wasn't very helpful, Joe.
1013          Jane, just make a link from
1014          uncompress to compress.
1015
1016       Or after "par 40qe":
1017
1018          Joe Public writes:
1019
1020          > Jane Doe writes:
1021          >
1022          > > I can't find the source for
1023          > > uncompress.
1024          >
1025          > Oh no, not again!!!
1026          >
1027          > Isn't there a FAQ for this?
1028
1029          That wasn't very helpful, Joe.
1030          Jane, just make a link from
1031          uncompress to compress.
1032
1033       Or after "par 40qi":
1034
1035          Joe Public writes:
1036          > Jane Doe writes:
1037          > >
1038          > >
1039          > > I can't find the source for
1040          > > uncompress.
1041          > Oh no, not again!!!
1042          >
1043          >
1044          > Isn't there a FAQ for this?
1045          >
1046          >
1047          That wasn't very helpful, Joe.
1048          Jane, just make a link from
1049          uncompress to compress.
1050
1051       Or after "par 40qie":
1052
1053          Joe Public writes:
1054          > Jane Doe writes:
1055          > > I can't find the source for
1056          > > uncompress.
1057          > Oh no, not again!!!
1058          >
1059          > Isn't there a FAQ for this?
1060          That wasn't very helpful, Joe.
1061          Jane, just make a link from
1062          uncompress to compress.
1063
1064       Before:
1065
1066          I sure hope there's still room
1067          in Dr. Jones' section of archaeology.
1068          I've heard he's the bestest.  [sic]
1069
1070       After "par 50g":
1071
1072          I sure hope there's still room in
1073          Dr. Jones' section of archaeology.  I've
1074          heard he's the bestest. [sic]
1075
1076       Or after "par 50gc":
1077
1078          I sure hope there's still room in
1079          Dr. Jones' section of archaeology.  I've
1080          heard he's the bestest.  [sic]
1081
1082       Before:
1083
1084          John writes:
1085          : Mary writes:
1086          : + Anastasia writes:
1087          : + > Hi all!
1088          : + Hi Ana!
1089          : Hi Ana & Mary!
1090          Please unsubscribe me from alt.hello.
1091
1092       After "par Q+:+ q":
1093
1094          John writes:
1095
1096          : Mary writes:
1097          :
1098          : + Anastasia writes:
1099          : +
1100          : + > Hi all!
1101          : +
1102          : + Hi Ana!
1103          :
1104          : Hi Ana & Mary!
1105
1106          Please unsubscribe me from alt.hello.
1107
1108       Before:
1109
1110          amc> The b option was added primarily to deal with
1111          amc> this new style of quotation
1112          amc> which became popular after Par 1.41 was released.
1113          amc>
1114          amc> Par still pays attention to body characters.
1115          amc> Par should not mistake "Par" for part of the prefix.
1116          amc> Par should not mistake "." for a suffix.
1117
1118       After "par B=._A_a 50bg":
1119
1120          amc> The b option was added primarily to
1121          amc> deal with this new style of quotation
1122          amc> which became popular after Par 1.41
1123          amc> was released.
1124          amc>
1125          amc> Par still pays attention to body
1126          amc> characters.  Par should not mistake
1127          amc> "Par" for part of the prefix.  Par
1128          amc> should not mistake "." for a suffix.
1129

SEE ALSO

1131       par.doc
1132

LIMITATIONS

1134       The guess feature guesses wrong in cases like the following:
1135
1136          I calc'd the approx.
1137          Fermi level to 3 sig. digits.
1138
1139       With guess = 1, par will incorrectly assume that "approx."  ends a sen‐
1140       tence.  If the input were:
1141
1142          I calc'd the approx. Fermi
1143          level to 3 sig. digits.
1144
1145       then par would refuse to put a line break between "approx." and "Fermi"
1146       in the output, mainly to avoid creating the first  situation  (in  case
1147       the  paragraph were to be fed back through par again).  This non-break‐
1148       ing space policy does come in handy for cases  like  "Mr. Johnson"  and
1149       "Jan. 1", though.
1150
1151       The  guess  feature  only goes one way.  par can preserve wide sentence
1152       breaks in a paragraph, or remove them, but it can't insert them if they
1153       aren't already in the input.
1154
1155       If  you use tabs, you may not like the way par handles (or doesn't han‐
1156       dle) them.  It expands them into spaces.  I didn't let par output  tabs
1157       because  tabs  don't  make sense.  Not everyone's terminal has the same
1158       tab settings, so text files containing tabs are sometimes mangled.   In
1159       fact,  almost  every  text file containing tabs gets mangled when some‐
1160       thing is inserted at the beginning of each line (when quoting e-mail or
1161       commenting out a section of a shell script, for example), making them a
1162       pain to edit.  In my opinion, the world  would  be  a  nicer  place  if
1163       everyone  stopped  using  tabs, so I'm doing my part by not letting par
1164       output them.  (Thanks to Eric Stuebe for showing  me  the  light  about
1165       tabs.)
1166
1167       There is currently no way for the length of the output prefix to differ
1168       from the length of the input prefix.  Ditto for the suffix.  I may con‐
1169       sider adding this capability in a future release, but right now I'm not
1170       sure how I'd want it to work.
1171

APOLOGIES

1173       Par began in July 1993 as a small program designed  to  do  one  narrow
1174       task:  reformat  a  single paragraph that might have a border on either
1175       side.  It was pretty clean back then.  Over the next three  months,  it
1176       very  rapidly  expanded  to  handle  multiple  paragraphs,  offer  more
1177       options, and take better guesses, at the  cost  of  becoming  extremely
1178       complex,  and  very unclean.  It is nowhere near the optimal design for
1179       the larger task it now tries to address.  Its only  redeeming  features
1180       are  that  it  is extremely useful (I find it indispensable), extremely
1181       portable, and very stable (between  the  release  of  version  1.41  on
1182       1993-Oct-31  and  the release of version 1.52 on 2001-Apr-29, no incor‐
1183       rect behavior was reported).
1184
1185       Back in 1993 I had very little experience at writing documentation  for
1186       users,  so  the documentation for Par became rather nightmarish.  There
1187       is no separation between how-it-works (which is painfully complex)  and
1188       how-to-use-it (which is fairly simple, if you can ever figure it out).
1189
1190       Someday  I  ought  to  reexamine the problem, and redesign a new, clean
1191       solution from scratch.  I don't know when I might get enough free  time
1192       to start on such a project.  Text files may be obsolete by then.
1193

BUGS

1195       If  I  knew  of  any  bugs, I wouldn't release the package.  Of course,
1196       there may be bugs that I haven't yet discovered.
1197
1198       If you find any bugs (in the program or in the  documentation),  or  if
1199       you have any suggestions, please send e-mail to:
1200
1201              amc@cs.berkeley.edu
1202
1203       When  reporting  a bug, please include the exact input and command line
1204       options used, and the version number of par, so that  I  can  reproduce
1205       it.
1206
1207       The latest release of Par is available on the Web at:
1208
1209              http://www.cs.berkeley.edu/~amc/Par/
1210
1211       These addresses will change.  I'll try to leave forward pointers.
1212
1213
1214
1215Par 1.52                          2001-Apr-29                           par(1)
Impressum