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 ] [ Wopset ]
10            [ Zopset ] [ h[hang] ] [ p[prefix] ] [ r[repeat] ] [ s[suffix] ]
11            [ T[Tab] ] [ w[width] ] [ b[body] ] [ c[cap] ] [ d[div] ]
12            [ E[Err] ] [ e[expel] ] [ f[fit] ] [ g[guess] ] [ j[just] ]
13            [ l[last] ] [ q[quote] ] [ 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, apostrophe, greater-than sign, and vertical
46       bar will probably have to be escaped or quoted to  prevent  your  shell
47       from interpreting 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                        _S = all space characters
73
74                        _b = a backslash (\)
75
76                        _q = a single quote (')
77
78                        _Q = a double quote (")
79
80                        _A = all upper case letters
81
82                        _a = all lower case letters
83
84                        _@ = all neither-case letters
85
86                        _0 = all decimal digits
87
88                      _xhh = the character represented by the two  hexadecimal
89                             digits hh (which may be upper or lower case)
90
91                     The  NUL  character must not appear in the string, but it
92                     may be included in the set with the _x00 sequence.
93
94                     The exact meanings of _S, _A, _a, _@, and _0 are  locale-
95                     dependent.   (Actually, all locales are supposed to agree
96                     on _0, but not  on  the  others.)   In  the  default  "C"
97                     locale:  _S  includes only space, formfeed, newline, car‐
98                     riage return, tab, and vertical tab; _A includes  only  A
99                     through  Z;  _a  includes  only  a through z; _@ includes
100                     nothing; and _0 includes only 0 through 9.
101
102              error  A condition which causes par to abort.  See the  DIAGNOS‐
103                     TICS section.
104
105              IP     Input paragraph.
106
107              OP     Output paragraph.
108
109              parameter
110                     A  symbol  which  may  take  on unsigned integral values.
111                     There are several  parameters  whose  values  affect  the
112                     behavior of par.  Parameters can be assigned values using
113                     command line options.
114
115       Types of characters:
116
117              alphanumeric character
118                     An alphabetic character or  decimal  digit,  _A_a_@_0  in
119                     charset syntax (see above).
120
121              body character
122                     A  member of the set of characters defined by the PARBODY
123                     environment variable (see the ENVIRONMENT section) and/or
124                     the B option (see the OPTIONS section).
125
126              protective character
127                     A member  of the set of characters defined by the PARPRO‐
128                     TECT environment variable and/or the P option.
129
130              quote character
131                     A member of the set of characters defined by the PARQUOTE
132                     environment variable and/or the Q option.
133
134              terminal character
135                     A  member  of  the  set  of  characters  defined by the Z
136                     option.  Initially, before any Z options have  been  pro‐
137                     cessed,  the set contains period, question mark, exclama‐
138                     tion point, and colon.
139
140              white character
141                     A member of the  set  of  characters  defined  by  the  W
142                     option.   Initially,  before any W options have been pro‐
143                     cessed, the set contains space, formfeed,  newline,  car‐
144                     riage return, tab, and vertical tab.
145
146       Functions:
147
148              comprelen
149                     Given  a  non-empty  sequence  S of lines, let c be their
150                     longest common prefix.  If the parameter body is 0, place
151                     a divider just after the leading non-body characters in c
152                     (at the beginning if there are  none).   If  body  is  1,
153                     place  the divider just after the last non-space non-body
154                     character in c (at the beginning if there is none),  then
155                     advance  the  divider over any immediately following spa‐
156                     ces.  The comprelen of S is the number of characters pre‐
157                     ceding the divider.
158
159              comsuflen
160                     Given  a non-empty sequence S of lines, let p be the com‐
161                     prelen of S.  Let T be the set of lines which result from
162                     stripping  the  first  p  characters from each line in S.
163                     Let c be the longest common suffix of the lines in T.  If
164                     body  is 0, place a divider just before the trailing non-
165                     body characters in c (at the end if there are none), then
166                     advance  the divider over all but the last of any immedi‐
167                     ately following spaces.  If body is 1, place the  divider
168                     just  before the first non-space non-body character, then
169                     back up the divider over one immediately preceding  space
170                     if  there  is  one.   The comsuflen of S is the number of
171                     characters following the divider.
172
173              fallback prelen (suflen)
174                     The fallback prelen (suflen) of an IP is:  the  comprelen
175                     (comsuflen)  of  the  IP, if the IP contains at least two
176                     lines; otherwise, the comprelen (comsuflen) of the  block
177                     containing  the  IP,  if  the block contains at least two
178                     lines; otherwise, the length of the longer  of  the  pre‐
179                     fixes  (suffixes)  of  the  bodiless lines just above and
180                     below the block, if the segment containing the block  has
181                     any  bodiless  lines;  otherwise,  0.  (See below for the
182                     definitions of block, segment, and bodiless line.)
183
184              augmented fallback prelen
185                     Let fp be the fallback prelen of an IP.  If the  IP  con‐
186                     tains more than one line, or if quote is 0, then the aug‐
187                     mented fallback prelen of the IP is  simply  fp.   Other‐
188                     wise,  it is fp plus the number of quote characters imme‐
189                     diately following the first fp characters of the line.
190
191              quoteprefix
192                     The quoteprefix of a line is the longest string of  quote
193                     characters  appearing at the beginning of the line, after
194                     this string has been stripped of any trailing spaces.
195
196       Types of lines:
197
198              blank line
199                     An empty line, or a line whose  first  character  is  not
200                     protective and which contains only spaces.
201
202              protected line
203                     An input line whose first character is protective.
204
205              bodiless line
206                     A line which is order k bodiless for some k.
207
208              order k bodiless line
209                     There is no such thing as an order 0 bodiless line.  Sup‐
210                     pose S is a a contiguous subsequence of  a  segment  (see
211                     below) containing at least two lines, containing no order
212                     k-1 bodiless lines, bounded above and below by order  k-1
213                     bodiless  lines  and/or the beginning/end of the segment.
214                     Let p and s be the comprelen and  comsuflen  of  S.   Any
215                     member  of S which, if stripped of its first p and last s
216                     characters, would be blank  (or,  if  the  line  was  not
217                     inserted  by  the quote feature  and the parameter repeat
218                     is non-zero, would consist of the same character repeated
219                     at least repeat times), is order k bodiless.  The first p
220                     characters of the bodiless line comprise its prefix;  the
221                     last  s  characters  comprise  its suffix.  The character
222                     which repeats in the middle is called its repeat  charac‐
223                     ter.   If  the  middle is empty, the space is taken to be
224                     its repeat character.
225
226              vacant line
227                     A bodiless line whose repeat character is the space.
228
229              superfluous line
230                     Only blank and vacant lines may be superfluous.  If  con‐
231                     tiguous  vacant  lines  lie  at the beginning or end of a
232                     segment, they are  all  superfluous.   But  if  they  lie
233                     between  two  non-vacant lines within a segment, then all
234                     are superfluous except one—the  one  which  contains  the
235                     fewest  non-spaces.   In  case of a tie, the first of the
236                     tied lines is chosen.   Similarly,  if  contiguous  blank
237                     lines lie outside of any segments at the beginning or end
238                     of the input, they are all superfluous.  But if they  lie
239                     between two segments and/or protected lines, then all are
240                     superfluous except the first.
241
242       Groups of lines:
243
244              segment
245                     A contiguous sequence of input lines containing  no  pro‐
246                     tected  or  blank  lines, bounded above and below by pro‐
247                     tected lines, blank lines, and/or  the  beginning/end  of
248                     the input.
249
250              block  A contiguous subsequence of a segment containing no bodi‐
251                     less lines, bounded above and  below  by  bodiless  lines
252                     and/or the beginning/end of the segment.
253
254       Types of words:
255
256              capitalized word
257                     If  the  parameter  cap  is  0, a capitalized word is one
258                     which contains at least one alphanumeric character, whose
259                     first  alphanumeric character is not a lower case letter.
260                     If cap is 1, every word is considered a capitalized word.
261                     (See the c option in the OPTIONS section.)
262
263              curious word
264                     A  word  which  contains a terminal character c such that
265                     there are no alphanumeric characters in the word after c,
266                     but  there  is at least one alphanumeric character in the
267                     word before c.
268

OPTIONS

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

ENVIRONMENT

448       PARBODY   Determines the initial set of body characters (which are used
449                 for determining comprelens  and  comsuflens),  using  charset
450                 syntax.  If PARBODY is not set, the set of body characters is
451                 initially empty.
452
453       PARINIT   If set, par will  read  command  line  options  from  PARINIT
454                 before it reads them from the command line.  Within the value
455                 of PARINIT, arguments are separated by  the  initial  set  of
456                 white characters.
457
458       PARPROTECT
459                 Determines  the  set  of protective characters, using charset
460                 syntax.  If PARPROTECT is not  set,  the  set  of  protective
461                 characters is initially empty.
462
463       PARQUOTE  Determines the set of quote characters, using charset syntax.
464                 If PARQUOTE is not set, the set of quote characters initially
465                 contains only the greater-than sign (>) and the space.
466
467       If  a NUL character appears in the value of an environment variable, it
468       and the rest of the string will not be seen by par.
469
470       Note that the PARINIT variable, together with the B, P, and Q  options,
471       renders the other environment variables unnecessary.  They are included
472       for backward compatibility.
473

DETAILS

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

DIAGNOSTICS

614       If there are no errors, par returns EXIT_SUCCESS (see <stdlib.h>).
615
616       If there is an error, an error message will be printed to  the  output,
617       and  par  will  return EXIT_FAILURE.  If the error is local to a single
618       paragraph, the preceding paragraphs will have been  output  before  the
619       error was detected.  Line numbers in error messages are local to the IP
620       in  which  the  error  occurred.   All  error   messages   begin   with
621       "par error:"  on  a  line by itself.  Error messages concerning command
622       line or environment variable syntax are accompanied by the  same  usage
623       message that the help option produces.
624
625       Of course, trying to print an error message would be futile if an error
626       resulted from an output function, so par doesn't bother doing any error
627       checking on output functions.
628

EXAMPLES

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

SEE ALSO

1156       par.doc
1157

LIMITATIONS

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

APOLOGIES

1198       Par  began  in  July  1993 as a small program designed to do one narrow
1199       task: reformat a single paragraph that might have a  border  on  either
1200       side.   It  was pretty clean back then.  Over the next three months, it
1201       very  rapidly  expanded  to  handle  multiple  paragraphs,  offer  more
1202       options,  and  take  better  guesses, at the cost of becoming extremely
1203       complex, and very unclean.  It is nowhere near the optimal  design  for
1204       the  larger  task it now tries to address.  Its only redeeming features
1205       are that it is extremely useful (I find  it  indispensable),  extremely
1206       portable, and very stable since version 1.41 released on 1993-Oct-31.
1207
1208       Back  in 1993 I had very little experience at writing documentation for
1209       users, so the documentation for Par became rather  nightmarish.   There
1210       is  no separation between how-it-works (which is painfully complex) and
1211       how-to-use-it (which is fairly simple, if you can ever figure it out).
1212
1213       Someday I ought to reexamine the problem, and  redesign  a  new,  clean
1214       solution  from scratch.  I don't know when I might get enough free time
1215       to start on such a project.  Text files may be obsolete by then.
1216

BUGS

1218       If I knew of any bugs, I wouldn't  release  the  package.   Of  course,
1219       there may be bugs that I haven't yet discovered.
1220
1221       If  you  find  any bugs (in the program or in the documentation), or if
1222       you have any suggestions, please contact me:
1223
1224              http://www.nicemice.net/amc/
1225
1226       When reporting a bug, please include the exact input and  command  line
1227       options  used,  and  the version number of par, so that I can reproduce
1228       it.
1229
1230       The latest release of Par is available on the Web at:
1231
1232              http://www.nicemice.net/par/
1233
1234       I don't expect these URLs to change in the forseeable  future,  but  if
1235       they do, I'll try to leave forward pointers.
1236
1237
1238
1239Par 1.53.0                        2020-Mar-14                           par(1)
Impressum