1par(1) USER COMMANDS par(1)
2
6 par - filter for reformatting paragraphs
7
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
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, 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 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 _S = all space characters
73 _b = a backslash (\)
75 _q = a single quote (')
77 _Q = a double quote (")
79 _A = all upper case letters
81 _a = all lower case letters
83 _@ = all neither-case letters
85 _0 = all decimal digits
87 _xhh = the character represented by the two hexadecimal
89 digits hh (which may be upper or lower case)
90 The NUL character must not appear in the string, but it
92 may be included in the set with the _x00 sequence.
93 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 error A condition which causes par to abort. See the DIAGNOS‐
103 TICS section.
104 IP Input paragraph.
106 OP Output paragraph.
108 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 Types of characters:
116 alphanumeric character
118 An alphabetic character or decimal digit, _A_a_@_0 in
119 charset syntax (see above).
120 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 protective character
127 A member of the set of characters defined by the PARPRO‐
128 TECT environment variable and/or the P option.
129 quote character
131 A member of the set of characters defined by the PARQUOTE
132 environment variable and/or the Q option.
133 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 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 Functions:
147 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 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 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 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 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 Types of lines:
197 blank line
199 An empty line, or a line whose first character is not
200 protective and which contains only spaces.
201 protected line
203 An input line whose first character is protective.
204 bodiless line
206 A line which is order k bodiless for some k.
207 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 vacant line
227 A bodiless line whose repeat character is the space.
228 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 Groups of lines:
243 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 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 Types of words:
255 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 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
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 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 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 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 Popset Just like the B option, except that it applies to the set of
295 protective characters.
296 Qopset Just like the B option, except that it applies to the set of
298 quote characters.
299 Wopset Just like the B option, except that it applies to the set of
301 white characters.
302 Zopset Just like the B option, except that it applies to the set of
304 terminal characters.
305 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 The approximate role of each variable is described here. See the
313 DETAILS section for the rest of the story.
314 The first six parameters, hang, prefix, repeat, suffix, Tab, and width,
316 may be set to any unsigned decimal integer less than 10000.
317 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 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 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 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 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 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 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 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 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 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 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 e[expel] If expel is 1, superfluous lines are withheld from the out‐
384 put. Defaults to 0.
385 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 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 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 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 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 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 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 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 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 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 It is an error if width <= prefix + suffix.
446
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 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 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 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 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 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
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 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 Blank lines in the input are transformed into empty lines in the out‐
490 put.
491 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 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 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 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 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 Let L = width - prefix - suffix.
519 If Report is 0, some words may get chopped up at this point (see R in
521 the OPTIONS section).
522 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 1) No line contains more than L characters.
529 2) If fit is 1, the difference between the lengths of the short‐
531 est and longest lines is as small as possible.
532 3) The shortest line is as long as possible, subject to proper‐
534 ties 1 and 2.
535 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 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 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 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 1) Every line contains exactly L characters.
554 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 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 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 Extra spaces are distributed as uniformly as possible among the
567 inter-word gaps in each line.
568 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 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 If just is 0 and touch is 1, L is changed to be the length of the long‐
578 est line.
579 If suffix is not 0, each line is padded at the end with spaces to bring
581 its length up to L.
582 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 1) If i <= n, the characters are copied from the ones that were
589 removed from the beginning of the nth input line.
590 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 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 Then to each line is appended suffix characters. The characters which
599 are appended to the ith line are chosen as follows:
600 1) If i <= n, the characters are copied from the ones that were
602 removed from the end of the nth input line.
603 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 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 Finally, the lines are printed to the output as the OP.
612
614 If there are no errors, par returns EXIT_SUCCESS (see <stdlib.h>).
615 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 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
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 Original paragraph (note that each line begins with 8 spaces):
635 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 After a greedy algorithm with width = 39:
648 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 After "par 39":
663 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 The line breaks chosen by par are clearly more eye-pleasing.
678 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 " 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 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 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 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 Before:
707 /* 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 After "par 59":
720 /* 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 Or after "par 59f":
731 /* 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 Or after "par 59l":
743 /* 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 Or after "par 59lf":
754 /* 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 Or after "par 59lft0":
766 /* 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 Or after "par 59j":
778 /* 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 Or after "par 59jl":
789 /* 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 Before:
800 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 After "par 52h3":
815 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 Before:
830 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 After "par 59p12l":
843 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 Before:
853 > > 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 After "par 52":
868 > > 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 Before:
882 > 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 After "par 52d":
896 > 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 Before:
909 # 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 After "par 37p13dh":
922 # 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 Before:
943 /*****************************************/
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 After "par 42r":
962 /********************************/
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 Or after "par 42re":
985 /********************************/
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 Before:
1006 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 After "par 40q":
1022 Joe Public writes:
1024 > 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 That wasn't very helpful, Joe.
1038 Jane, just make a link from
1039 uncompress to compress.
1040 Or after "par 40qe":
1042 Joe Public writes:
1044 > 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 That wasn't very helpful, Joe.
1055 Jane, just make a link from
1056 uncompress to compress.
1057 Or after "par 40qi":
1059 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 Or after "par 40qie":
1077 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 Before:
1090 I sure hope there's still room
1092 in Dr. Jones' section of archaeology.
1093 I've heard he's the bestest. [sic]
1094 After "par 50g":
1096 I sure hope there's still room in
1098 Dr. Jones' section of archaeology. I've
1099 heard he's the bestest. [sic]
1100 Or after "par 50gc":
1102 I sure hope there's still room in
1104 Dr. Jones' section of archaeology. I've
1105 heard he's the bestest. [sic]
1106 Before:
1108 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 After "par Q+:+ q":
1118 John writes:
1120 : Mary writes:
1122 :
1123 : + Anastasia writes:
1124 : +
1125 : + > Hi all!
1126 : +
1127 : + Hi Ana!
1128 :
1129 : Hi Ana & Mary!
1130 Please unsubscribe me from alt.hello.
1132 Before:
1134 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 After "par B=._A_a 50bg":
1144 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
1156 par.doc
1157
1159 The guess feature guesses wrong in cases like the following:
1160 I calc'd the approx.
1162 Fermi level to 3 sig. digits.
1163 With guess = 1, par will incorrectly assume that "approx." ends a sen‐
1165 tence. If the input were:
1166 I calc'd the approx. Fermi
1168 level to 3 sig. digits.
1169 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 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 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 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
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 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 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
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 If you find any bugs (in the program or in the documentation), or if
1222 you have any suggestions, please contact me:
1223 http://www.nicemice.net/amc/
1225 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 The latest release of Par is available on the Web at:
1231 http://www.nicemice.net/par/
1233 I don't expect these URLs to change in the forseeable future, but if
1235 they do, I'll try to leave forward pointers.
1236Par 1.53.0 2020-Mar-14 par(1)