1par(1) USER COMMANDS par(1)
2
6 par - filter for reformatting paragraphs
7
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
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 Each output paragraph is generated from the corresponding input para‐
23 graph as follows:
24 1) An optional prefix and/or suffix is removed from each input
26 line.
27 2) The remainder is divided into words (separated by spaces).
29 3) The words are joined into lines to make an eye-pleasing para‐
31 graph.
32 4) The prefixes and suffixes are reattached.
34 If there are suffixes, spaces are inserted before them so that they all
36 end in the same column.
37
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 rTbgqR B=.,?_A_a Q=_s>|
44 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 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 For the "power user", a full understanding of par will require multiple
56 readings of the TERMINOLOGY, OPTIONS, DETAILS, and EXAMPLES sections.
57
59 Miscellaneous terms:
60 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 __ = an underscore
69 _s = a space
71 _b = a backslash (\)
73 _q = a single quote (')
75 _Q = a double quote (")
77 _A = all upper case letters
79 _a = all lower case letters
81 _0 = all decimal digits
83 _xhh = the character represented by the two hexadecimal
85 digits hh (which may be upper or lower case)
86 The NUL character must not appear in the string, but it
88 may be included in the set with the _x00 sequence.
89 error A condition which causes par to abort. See the DIAGNOS‐
91 TICS section.
92 IP Input paragraph.
94 OP Output paragraph.
96 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 Types of characters:
104 alphanumeric character
106 An upper case letter, lower case letter, or decimal
107 digit.
108 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 protective character
115 A member of the set of characters defined by the PARPRO‐
116 TECT environment variable and/or the P option.
117 quote character
119 A member of the set of characters defined by the PARQUOTE
120 environment variable and/or the Q option.
121 terminal character
123 A period, question mark, exclamation point, or colon.
124 white character
126 A space, formfeed, newline, carriage return, tab, or ver‐
127 tical tab.
128 Functions:
130 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 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 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 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 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 Types of lines:
180 blank line
182 An empty line, or a line whose first character is not
183 protective and which contains only spaces.
184 protected line
186 An input line whose first character is protective.
187 bodiless line
189 A line which is order k bodiless for some k.
190 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 vacant line
209 A bodiless line whose repeat character is the space.
210 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 Groups of lines:
225 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 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 Types of words:
237 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 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
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 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 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 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 Popset Just like the B option, except that it applies to the set of
277 protective characters.
278 Qopset Just like the B option, except that it applies to the set of
280 quote characters.
281 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 The approximate role of each variable is described here. See the
289 DETAILS section for the rest of the story.
290 The first six parameters, hang, prefix, repeat, suffix, Tab, and width,
292 may be set to any unsigned decimal integer less than 10000.
293 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 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 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 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 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 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 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 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 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 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 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 e[expel] If expel is 1, superfluous lines are withheld from the out‐
360 put. Defaults to 0.
361 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 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 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 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 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 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 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 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 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 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 It is an error if width <= prefix + suffix.
422
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 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 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 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 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 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
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 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 Blank lines in the input are transformed into empty lines in the out‐
465 put.
466 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 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 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 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 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 Let L = width - prefix - suffix.
494 If Report is 0, some words may get chopped up at this point (see R in
496 the OPTIONS section).
497 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 1) No line contains more than L characters.
504 2) If fit is 1, the difference between the lengths of the short‐
506 est and longest lines is as small as possible.
507 3) The shortest line is as long as possible, subject to proper‐
509 ties 1 and 2.
510 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 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 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 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 1) Every line contains exactly L characters.
529 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 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 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 Extra spaces are distributed as uniformly as possible among the
542 inter-word gaps in each line.
543 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 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 If just is 0 and touch is 1, L is changed to be the length of the long‐
553 est line.
554 If suffix is not 0, each line is padded at the end with spaces to bring
556 its length up to L.
557 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 1) If i <= n, the characters are copied from the ones that were
564 removed from the beginning of the nth input line.
565 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 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 Then to each line is appended suffix characters. The characters which
574 are appended to the ith line are chosen as follows:
575 1) If i <= n, the characters are copied from the ones that were
577 removed from the end of the nth input line.
578 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 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 Finally, the lines are printed to the output as the OP.
587
589 If there are no errors, par returns EXIT_SUCCESS (see <stdlib.h>).
590 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 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
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 Original paragraph (note that each line begins with 8 spaces):
610 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 After a greedy algorithm with width = 39:
623 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 After "par 39":
638 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 The line breaks chosen by par are clearly more eye-pleasing.
653 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 " 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 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 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 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 Before:
682 /* 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 After "par 59":
695 /* 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 Or after "par 59f":
706 /* 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 Or after "par 59l":
718 /* 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 Or after "par 59lf":
729 /* 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 Or after "par 59lft0":
741 /* 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 Or after "par 59j":
753 /* 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 Or after "par 59jl":
764 /* 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 Before:
775 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 After "par 52h3":
790 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 Before:
805 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 After "par 59p12l":
818 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 Before:
828 > > 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 After "par 52":
843 > > 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 Before:
857 > 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 After "par 52d":
871 > 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 Before:
884 # 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 After "par 37p13dh":
897 # 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 Before:
918 /*****************************************/
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 After "par 42r":
937 /********************************/
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 Or after "par 42re":
960 /********************************/
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 Before:
981 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 After "par 40q":
997 Joe Public writes:
999 > 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 That wasn't very helpful, Joe.
1013 Jane, just make a link from
1014 uncompress to compress.
1015 Or after "par 40qe":
1017 Joe Public writes:
1019 > 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 That wasn't very helpful, Joe.
1030 Jane, just make a link from
1031 uncompress to compress.
1032 Or after "par 40qi":
1034 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 Or after "par 40qie":
1052 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 Before:
1065 I sure hope there's still room
1067 in Dr. Jones' section of archaeology.
1068 I've heard he's the bestest. [sic]
1069 After "par 50g":
1071 I sure hope there's still room in
1073 Dr. Jones' section of archaeology. I've
1074 heard he's the bestest. [sic]
1075 Or after "par 50gc":
1077 I sure hope there's still room in
1079 Dr. Jones' section of archaeology. I've
1080 heard he's the bestest. [sic]
1081 Before:
1083 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 After "par Q+:+ q":
1093 John writes:
1095 : Mary writes:
1097 :
1098 : + Anastasia writes:
1099 : +
1100 : + > Hi all!
1101 : +
1102 : + Hi Ana!
1103 :
1104 : Hi Ana & Mary!
1105 Please unsubscribe me from alt.hello.
1107 Before:
1109 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 After "par B=._A_a 50bg":
1119 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
1131 par.doc
1132
1134 The guess feature guesses wrong in cases like the following:
1135 I calc'd the approx.
1137 Fermi level to 3 sig. digits.
1138 With guess = 1, par will incorrectly assume that "approx." ends a sen‐
1140 tence. If the input were:
1141 I calc'd the approx. Fermi
1143 level to 3 sig. digits.
1144 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 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 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 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
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 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 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
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 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 amc@cs.berkeley.edu
1202 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 The latest release of Par is available on the Web at:
1208 http://www.cs.berkeley.edu/~amc/Par/
1210 These addresses will change. I'll try to leave forward pointers.
1212Par 1.52 2001-Apr-29 par(1)