SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from OpenSuSE par-1.52-4.88.i586.rpm

par

Section: USER COMMANDS (1)
Updated: 2001-Apr-29
Index 

NAME

par - filter for reformatting paragraphs 

SYNOPSIS

par
[ help ][ version ][ B opset ][ P opset ][ Q opset ][ h [hang] ][ p [prefix] ][ r [repeat] ][ s [suffix] ][ T [Tab] ][ w [width] ][ b [body] ][ c [cap] ][ d [div] ][ E [Err] ][ e [expel] ][ f [fit] ][ g [guess] ][ j [just] ][ l [last] ][ q [quote] ][ R [Report] ][ t [touch] ]
 

DESCRIPTION

paris a filter which copies its input to its output, changingall white characters (except newlines) to spaces, andreformatting each paragraph. Paragraphs are separatedby protected, blank, and bodiless lines (see theTERMINOLOGYsection for definitions), and optionallydelimited by indentation (see thedoption in theOPTIONSsection).

Each output paragraph is generated from thecorresponding input paragraph as follows:

1) An optional prefix and/or suffix is removed from each input line.

2) The remainder is divided into words (separated by spaces).

3) The words are joined into lines to make an eye-pleasing paragraph.

4) The prefixes and suffixes are reattached.

If there are suffixes, spaces are inserted beforethem so that they all end in the same column. 

QUICK START

paris necessarily complex. For those who wish to useit immediately and understand it later, assign thePARINITenvironment variable the following value:

rTbgqR B=.,?_A_a Q=_s>|

The spaces, question mark, greater-than sign, andvertical bar will probably have to be escaped orquoted to prevent your shell from interpreting them.

The documentation, though precise, is unfortunatelynot well-written for the end-user. Yourbest bet is probably to read quickly theDESCRIPTION,TERMINOLOGY,OPTIONS,andENVIRONMENTsections, then read carefully theEXAMPLESsection, referring back to theOPTIONSandTERMINOLOGYsections as needed.

For the "power user", a full understanding ofparwill require multiple readings of theTERMINOLOGY,OPTIONS,DETAILS,andEXAMPLESsections. 

TERMINOLOGY

Miscellaneous terms:

charset syntax
A way of representing a set of characters as a string.The set includes exactly those characters whichappear in the string, except that the underscore (_)is an escape character. Whenever it appears, itmust begin one of the following escape sequences:

__ = an underscore

_s = a space

_b = a backslash (\)

_q = a single quote (')

_Q = a double quote ()

_A = all upper case letters

_a = all lower case letters

_0 = all decimal digits

_xhh = the character represented by the two hexadecimal digitshh(which may be upper or lower case)

The NUL character must not appear in the string, butit may be included in the set with the _x00 sequence.
error
A condition which causesparto abort. See theDIAGNOSTICSsection.
IP
Input paragraph.
OP
Output paragraph.
parameter
A symbol which may take on unsigned integral values. Thereare several parameters whose values affect the behavior ofpar.Parameters can be assigned valuesusing command line options.

Types of characters:

alphanumeric character
An upper case letter, lower case letter, or decimal digit.
body character
A member of the set of characters defined by thePARBODYenvironment variable (see theENVIRONMENTsection) and/or theBoption (see theOPTIONSsection).
protective character
A member of the set of characters defined by thePARPROTECTenvironment variable and/or thePoption.
quote character
A member of the set of characters defined by thePARQUOTEenvironment variable and/or theQoption.
terminal character
A period, question mark, exclamation point, or colon.
white character
A space, formfeed, newline, carriagereturn, tab, or vertical tab.

Functions:

comprelen
Given a non-empty sequenceSof lines, letcbe their longest common prefix. If the parameterbodyis 0, place a divider just afterthe leading non-body characters inc(at the beginning if there are none). Ifbodyis 1, place the divider just after thelast non-space non-body character inc(at the beginning if there is none), thenadvance the divider over any immediatelyfollowing spaces. The comprelen ofSis the number of characters preceeding the divider.
comsuflen
Given a non-empty sequenceSof lines, letpbe the comprelen ofS.LetTbe the set of lines which result from stripping the firstpcharacters from each line inS.Letcbe the longest common suffix of the lines inT.Ifbodyis 0, place a divider just beforethe trailing non-body characters inc(at the end if there are none), thenadvance the divider over all but the lastof any immediately following spaces. Ifbodyis 1, place the divider just before the firstnon-space non-body character, then back upthe divider over one immediately preceedingspace if there is one. The comsuflen ofSis the number of characters following the divider.
fallback prelen (suflen)
The fallback prelen (suflen) of an IP is: the comprelen(comsuflen) of the IP, if the IP contains at least twolines; otherwise, the comprelen (comsuflen) of theblock containing the IP, if the block contains at leasttwo lines; otherwise, the length of the longer of theprefixes (suffixes) of the bodiless lines just above andbelow the block, if the segment containing the blockhas any bodiless lines; otherwise, 0. (See below forthe definitions of block, segment, and bodiless line.)
augmented fallback prelen
Letfpbe the fallback prelen of an IP. If theIP contains more than one line, or ifquoteis 0, then the augmented fallback prelen of the IP is simplyfp.Otherwise, it isfpplus the number of quote charactersimmediately following the firstfpcharacters of the line.
quoteprefix
The quoteprefix of a line is the longest string of quotecharacters appearing at the beginning of the line, afterthis string has been stripped of any trailing spaces.

Types of lines:

blank line
An empty line, or a line whose first character isnot protective and which contains only spaces.
protected line
An input line whose first character is protective.
bodiless line
A line which is orderkbodiless for somek.
order k bodiless line
There is no such thing as an order 0 bodiless line. SupposeSis a a contiguous subsequence of a segment (see below)containing at least two lines, containing no orderk-1bodiless lines, bounded above and below by orderk-1bodiless lines and/or the beginning/end of the segment. Letpandsbe the comprelen and comsuflen ofS.Any member ofSwhich, if stripped of its firstpand lastscharacters, would be blank (or, if the parameterrepeatis non-zero, would consist of thesame character repeated at leastrepeattimes), is orderkbodiless. The firstpcharacters of the bodiless linecomprise its prefix; the lastscharacters comprise its suffix. The character which repeatsin the middle is called its repeat character. If the middleis empty, the space is taken to be its repeat character.
vacant line
A bodiless line whose repeat character is the space.
superfluous line
Only blank and vacant lines may be superfluous. Ifcontiguous vacant lines lie at the beginning or endof a segment, they are all superfluous. But if theylie between two non-vacant lines within a segment,then all are superfluous except one---the one whichcontains the fewest non-spaces. In case of a tie,the first of the tied lines is chosen. Similarly, ifcontiguous blank lines lie outside of any segmentsat the beginning or end of the input, they are allsuperfluous. But if they lie between two segments and/orprotected lines, then all are superfluous except the first.

Groups of lines:

segment
A contiguous sequence of input lines containing no protectedor blank lines, bounded above and below by protectedlines, blank lines, and/or the beginning/end of the input.
block
A contiguous subsequence of a segment containing nobodiless lines, bounded above and below by bodilesslines and/or the beginning/end of the segment.

Types of words:

capitalized word
If the parametercapis 0, a capitalized word is one which containsat least one alphanumeric character, whose firstalphanumeric character is not a lower case letter. Ifcapis 1, every word is considered a capitalized word. (See thecoption in theOPTIONSsection.)
curious word
A word which contains a terminal charactercsuch that there are no alphanumericcharacters in the word afterc,but there is at least one alphanumericcharacter in the word beforec.
 

OPTIONS

Any command line argument may begin with one minussign (-) which is ignored. Generally, morethan one option may appear in a single commandline argument, but there are exceptions: Thehelp,version,B,P,andQoptions must have whole arguments all to themselves.

help
Causes all remaining arguments to be ignored. Noinput is read. A usage message is printed on theoutput briefly describing the options used bypar.
version
Causes all remaining arguments to be ignored. No inputis read. "par 1.52" is printed on the output. Ofcourse, this will change in future releases of Par.
Bopset
opis a single character, either an equal sign(=), a plus sign (+), or a minus sign (-), andsetis a string using charset syntax. Ifopis an equal sign, the set of body charactersis set to the character set defined byset.Ifopis a plus/minus sign, the characters in the set defined bysetare added/removed to/from the existingset of body characters defined by thePARBODYenvironment variable and any previous B options. Itis okay to add characters that are already in theset or to remove characters that are not in the set.
Popset
Just like theBoption, except that it applies tothe set of protective characters.
Qopset
Just like theBoption, except that it appliesto the set of quote characters.

All remaining options are used to set values ofparameters. Values set by command line options hold for allparagraphs. Unset parameters are given default values. Anyparameters whose default values depend on the IP (namelyprefixandsuffix),if left unset, are recomputed separately for each paragraph.

The approximate role of eachvariable is described here. See theDETAILSsection for the rest of the story.

The first six parameters,hang,prefix,repeat,suffix,Tab,andwidth,may be set to any unsigned decimal integer less than 10000.

h[hang]
Mainly affects the default values ofprefixandsuffix.Defaults to 0. If thehoption is given without a number, thevalue 1 is inferred. (See also thepandsoptions.)
p[prefix]
The firstprefixcharacters of each line of the OP are copied from the firstprefixcharacters of the corresponding lineof the IP. If there are more thanhang+1lines in the IP, the default value is the comprelenof all the lines in the IP except the firsthangof them. Otherwise, the default value is theaugmented fallback prelen of the IP. If thepoption is given without a number,prefixis unset, even if it had been set earlier. (See also thehandqoptions.)
r[repeat]
Ifrepeatis non-zero, bodiless lines have the number ofinstances of their repeat characters increasedor decreased until the length of the line iswidth.The exact value ofrepeataffects the definition of bodilessline. Defaults to 0. If theroption is given without a number, thevalue 3 is inferred. (See also thewoption.)
s[suffix]
The lastsuffixcharacters of each line of the OP are copied from the lastsuffixcharacters of the corresponding lineof the IP. If there are more thanhang+1lines in the IP, the default value is the comsuflenof all the lines of the IP except the firsthangof them. Otherwise, the default value isthe fallback suflen of the IP. If thesoption is given without a number,suffixis unset, even if it had been set earlier. (See also thehoption.)
T[Tab]
Tab characters in the input are expandedto spaces, assuming tab stops everyTabcolumns. Must not be 0. Defaults to 1. If theToption is given without a number, the value 8 is inferred.
w[width]
No line in the OP may contain more thanwidthcharacters, not including the trailingnewlines. Defaults to 72. If thewoption is given without a number, the value 79 is inferred.

The remaining thirteen parameters,body,cap,div,Err,expel,fit,guess,invis,just,last,quote,Report,andtouch,may be set to either 0 or 1. If the number isabsent in the option, the value 1 is inferred.

b[body]
Ifbodyis 1, prefixes may not contain any trailing body characters,and suffixes may not contain any leading body characters.(Actually, the situation is complicated by space characters.See comprelen and comsuflen in the Terminology section.) Ifbodyis 0, prefixes and suffixes may not containany body characters at all. Defaults to 0.
c[cap]
Ifcapis 1, all words are considered capitalized. Thiscurrently affects only the application of thegoption. Defaults to 0.
d[div]
Ifdivis 0, each block becomes an IP. Ifdivis 1, each block is subdivided into IPs as follows: Letpbe the comprelen of the block.Let a line's status be 1 if its(p+1)stcharacter is a space, 0 otherwise. Every line in theblock whose status is the same as the status of thefirst line will begin a new paragraph. Defaults to 0.
E[Err]
IfErris 1, messages to the user (caused by thehelpandversionoptions, or by errors) are sent to the error streaminstead of the output stream. Defaults to 0.
e[expel]
Ifexpelis 1, superfluous lines are withheldfrom the output. Defaults to 0.
f[fit]
Iffitis 1 andjustis 0,partries to make the lines in the OP as nearly thesame length as possible, even if it means makingthe OP narrower. Defaults to 0. (See also thejoption.)
g[guess]
Ifguessis 1, then whenparis choosing line breaks, whenever it encounters a curiousword followed by a capitalized word, it takes one of twospecial actions. If the two words are separated by asingle space in the input, they will be merged into oneword with an embedded non-breaking space. If the two wordsare separated by more than one space, or by a line break,parwill insure that they are separated by two spaces,or by a line break, in the output. Defaults to 0.
i[invis]
Ifinvisis 1, then vacant lines inserted becausequoteis 1 are invisible; that is, they are not output. Ifquoteis 0,invishas no effect. Defaults to 0. (See also theqoption.)
j[just]
Ifjustis 1,parjustifies the OP, inserting spaces between wordsso that all lines in the OP have lengthwidth(except the last, iflastis 0). Defaults to 0. (See also thew,l,andfoptions.)
l[last]
Iflastis 1,partries to make the last line of the OP aboutthe same length as the others. Defaults to 0.
q[quote]
Ifquoteis 1, then before each segmentis scanned for bodiless lines,parsupplies vacant lines between different quotation nestinglevels as follows: For each pair of adjacent lines inthe segment, (scanned from the top down) which havedifferent quoteprefixes, one of two actions is taken. Ifinvisis 0, and either line consists entirely of quotecharacters and spaces (or is empty), that lineis truncated to the longest common prefix of thetwo lines (both are truncated if both qualify).Otherwise, a line consisting of the longest commonprefix of the two lines is inserted between them.quotealso affects the default value ofprefix.Defaults to 0. (See also thepandioptions.)
R[Report]
IfReportis 1, it is considered an error foran input word to contain more thanL =(width -prefix -suffix)characters. Otherwise, suchwords are chopped after eachLthcharacter into shorter words. Defaults to 0.
t[touch]
Has no effect ifsuffixis 0 orjustis 1. Otherwise, iftouchis 0, all lines in the OP have lengthwidth.Iftouchis 1, the length of the lines is decreased until thesuffixes touch the body of the OP. Defaults to the logicalORoffitandlast.(See also thes,j,w,f,andloptions.)

If an argument begins with a number,that number is assumed to belong to apoption if it is 8 or less, and to awoption otherwise.

If the value of any parameter is set morethan once, the last value is used. Whenunset parameters are assigned default values,hangandquoteare assigned beforeprefix,andfitandlastare assigned beforetouch(because of the dependencies).

It is an error ifwidth<=prefix+suffix. 

ENVIRONMENT

PARBODY
Determines the initial set of body characters(which are used for determining comprelensand comsuflens), using charset syntax. IfPARBODYis not set, the set of body characters is initially empty.
PARINIT
If set,parwill read command line options fromPARINITbefore it reads them from the command line.Within the value ofPARINIT,arguments are separated by white characters.
PARPROTECT
Determines the set of protectivecharacters, using charset syntax. IfPARPROTECTis not set, the set of protectivecharacters is initially empty.
PARQUOTE
Determines the set of quotecharacters, using charset syntax. IfPARQUOTEis not set, the set of quote characters initiallycontains only the greater-than sign (>) and the space.

If aNULcharacter appears in the value of an environment variable,it and the rest of the string will not be seen bypar.

Note that thePARINITvariable, together with theB,P,andQoptions, renders the other environment variablesunnecessary. They are included for backward compatibility. 

DETAILS

Lines are terminated by newline characters, but thenewlines are not considered to be included in the lines.If the last character of the input is a non-newline,a newline will be inferred immediately after it (butif the input is empty, no newline will be inferred;the number of input lines will be 0). Thus, theinput can always be viewed as a sequence of lines.

Protected lines are copied unchanged from the input to theoutput. All other input lines, as they are read, have anyNULcharacters removed, and every white character(except newlines) turned into a space.Actually, each tab character is turned intoTab-(n%Tab)spaces, wherenis the number of characters preceeding thetab character on the line (evaluated afterearlier tab characters have been expanded).

Blank lines in the input are transformedinto empty lines in the output.

Ifrepeatis 0, all bodiless lines are vacant, and they are allsimply stripped of trailing spaces before being output. Ifrepeatis not 0, only vacant lines whose suffixes have length0 are treated that way; other bodiless lines havethe number of instances of their repeat charactersincreased or decreased until the length of the line iswidth.

Ifexpelis 1, superfluous lines are not output. Ifquoteandinvisare both 1, there may be invisiblelines; they are not output.

The input is divided into segments, which aredivided into blocks, which are divided intoIPs. The exact process depends on the values ofquoteanddiv(seeqanddin theOPTIONSsection). The remainder of this section describesthe process which is applied independently toeach IP to construct the corresponding OP.

After the values of the parameters are determined (see theOPTIONSsection), the firstprefixcharacters and the lastsuffixcharacters of each input line are removed and remembered.It is an error for any line to contain fewer thanprefix + suffixcharacters.

The remaining text is treated as a sequence ofcharacters, not lines. The text is broken intowords, which are separated by spaces. That is, aword is a maximal sub-sequence of non-spaces. Ifguessis 1, some words might be merged (seegin theOPTIONSsection). The first word includes anyspaces that preceed it on the same line.

LetL=width-prefix-suffix.

IfReportis 0, some words may get chopped up at this point (seeRin theOPTIONSsection).

The words are reassembled, preservingtheir order, into lines. Ifjustis 0, adjacent words within a line are separatedby a single space, (or sometimes two ifguessis 1), and line breaks are chosen so thatthe paragraph satisfies the following properties:

1) No line contains more than Lcharacters.

2) If fitis 1, the difference between the lengths of theshortest and longest lines is as small as possible.

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

4) Let targetbeLiffitis 0, or the length of the longest line iffitis 1. The sum of the squares of the differences betweentargetand the lengths of the lines is as small aspossible, subject to properties 1, 2, and 3.

Iflastis 0, the last line does not count as a line forthe purposes of properties 2, 3, and 4 above.

If all the words fit on a single line, theproperties as worded above don't make muchsense. In that case, no line breaks are inserted.

Ifjustis 1, adjacent words within a line areseparated by one space (or sometimes two ifguessis 1) plus zero or more extra spaces. The value offitis disregarded, and line breaks are chosen so thatthe paragraph satisfies the following properties:

1) Every line contains exactly Lcharacters.

2) The largest inter-word gap is as small aspossible, subject to property 1. (An inter-word gapconsists only of the extra spaces, not the regular spaces.)

3) The sum of the squares of the lengthsof the inter-word gaps is as small aspossible, subject to properties 1 and 2.

Iflastis 0, the last line does not count as a linefor the purposes of property 1, and it doesnot require or contain any extra spaces.

Extra spaces are distributed as uniformly aspossible among the inter-word gaps in each line.

In a justified paragraph, every line mustcontain at least two words, but that's notalways possible to accomplish. If the paragraphcannot be justified, it is considered an error.

If the number of lines in theresulting paragraph is less thanhang,empty lines are added at the endto bring the number of lines up tohang.

Ifjustis 0 andtouchis 1,Lis changed to be the length of the longest line.

Ifsuffixis not 0, each line is padded at the endwith spaces to bring its length up toL.

To each line is prependedprefixcharacters. Letnbe the number of lines in the IP, letafpbe the augmented fallback prelen of the IP, and letfsbe the fallback suflen of the IP. Thecharacters which are prepended to theithline are chosen as follows:

1) If i<=n,the characters are copied from the onesthat were removed from the beginning of thenthinput line.

2) If i>n>hang,the characters are copied from the ones that wereremoved from the beginning of the last input line.

3) If i>nandn<=hang,the firstmin(afp,prefix)of the characters are copied from the onesthat were removed from the beginning of thelast input line, and the rest are all spaces.

Then to each line is appendedsuffixcharacters. The characters which are appended to theithline are chosen as follows:

1) If i<=n,the characters are copied from the onesthat were removed from the end of thenthinput line.

2) If i>n>hang,the characters are copied from the ones thatwere removed from the end of the last input line.

3) If i>nandn<=hang,the firstmin(fs,suffix)of the characters are copied from the onesthat were removed from the beginning of thelast input line, and the rest are all spaces.

Finally, the lines are printed to the output as the OP. 

DIAGNOSTICS

If there are no errors,parreturnsEXIT_SUCCESS(see<stdlib.h>).

If there is an error, an error messagewill be printed to the output, andparwill returnEXIT_FAILURE.If the error is local to a single paragraph, the preceedingparagraphs will have been output before the errorwas detected. Line numbers in error messages arelocal to the IP in which the error occurred. Allerror messages begin with "par error:" on a lineby itself. Error messages concerning command lineor environment variable syntax are accompanied bythe same usage message that the help option produces.

Of course, trying to print an error message would befutile if an error resulted from an output function, sopardoesn't bother doing any error checking on output functions. 

EXAMPLES

The superiority ofpar'sdynamic programming algorithm over agreedy algorithm (such as the one used byfmt)can be seen in the following example:

Original paragraph (note thateach line begins with 8 spaces):

        We the people of the United States,        in order to form a more perfect union,        establish justice,        insure domestic tranquility,        provide for the common defense,        promote the general welfare,        and secure the blessing of liberty        to ourselves and our posterity,        do ordain and establish the Constitution        of the United States of America.

After a greedy algorithm with width = 39:

        We the people of the United        States, in order to form a more        perfect union, establish        justice, insure domestic        tranquility, provide for the        common defense, promote the        general welfare, and secure the        blessing of liberty to        ourselves and our posterity, do        ordain and establish the        Constitution of the United        States of America.

After"par 39":

        We the people of the United        States, in order to form a        more perfect union, establish        justice, insure domestic        tranquility, provide for the        common defense, promote the        general welfare, and secure        the blessing of liberty to        ourselves and our posterity,        do ordain and establish the        Constitution of the United        States of America.

The line breaks chosen byparare clearly more eye-pleasing.

paris most useful in conjunction with the text-filteringfeatures of an editor, such as the ! commands ofvi.You may wish to add the following lines to your.exrcfile:

        " use Bourne shell for speed:        set shell=/bin/sh        "        " reformat paragraph with no arguments:        map ** {!}par^M}        "        " reformat paragraph with arguments:        map *^V  {!}par

Note that the leading spaces must be removed, and that whatis shown as ^M and ^V really need to be ctrl-M and ctrl-V.Also note that the last map command contains two spacesfollowing the ctrl-V, plus one at the end of the line.

To reformat a simple paragraph delimited by blank lines invi,you can put the cursor anywhere in it and type"**" (star star). If you need to supplyarguments to par, you can type ""(star space) instead, then type the arguments.

The rest of this section is a series ofbefore-and-after pictures showing some typical uses ofpar.In all cases, no environment variables are set.

Before:

        /*   We the people of the United States, */        /* in order to form a more perfect union, */        /* establish justice, */        /* insure domestic tranquility, */        /* provide for the common defense, */        /* promote the general welfare, */        /* and secure the blessing of liberty */        /* to ourselves and our posterity, */        /* do ordain and establish the Constitution */        /* of the United States of America. */

After"par 59":

        /*   We the people of the United States, in      */        /* order to form a more perfect union, establish */        /* justice, insure domestic tranquility, provide */        /* for the common defense, promote the general   */        /* welfare, and secure the blessing of liberty   */        /* to ourselves and our posterity, do ordain     */        /* and establish the Constitution of the United  */        /* States of America.                            */

Or after"par 59f":

        /*   We the people of the United States,  */        /* in order to form a more perfect union, */        /* establish justice, insure domestic     */        /* tranquility, provide for the common    */        /* defense, promote the general welfare,  */        /* and secure the blessing of liberty to  */        /* ourselves and our posterity, do ordain */        /* and establish the Constitution of the  */        /* United States of America.              */

Or after"par 59l":

        /*   We the people of the United States, in      */        /* order to form a more perfect union, establish */        /* justice, insure domestic tranquility,         */        /* provide for the common defense, promote       */        /* the general welfare, and secure the           */        /* blessing of liberty to ourselves and our      */        /* posterity, do ordain and establish the        */        /* Constitution of the United States of America. */

Or after"par 59lf":

        /*   We the people of the United States,  */        /* in order to form a more perfect union, */        /* establish justice, insure domestic     */        /* tranquility, provide for the common    */        /* defense, promote the general welfare,  */        /* and secure the blessing of liberty     */        /* to ourselves and our posterity, do     */        /* ordain and establish the Constitution  */        /* of the United States of America.       */

Or after"par 59lft0":

        /*   We the people of the United States,         */        /* in order to form a more perfect union,        */        /* establish justice, insure domestic            */        /* tranquility, provide for the common           */        /* defense, promote the general welfare,         */        /* and secure the blessing of liberty            */        /* to ourselves and our posterity, do            */        /* ordain and establish the Constitution         */        /* of the United States of America.              */

Or after"par 59j":

        /*   We  the people  of  the  United States,  in */        /* order to form a more perfect union, establish */        /* justice, insure domestic tranquility, provide */        /* for the  common defense, promote  the general */        /* welfare, and  secure the blessing  of liberty */        /* to ourselves and our posterity, do ordain and */        /* establish  the  Constitution  of  the  United */        /* States of America.                            */

Or after"par 59jl":

        /*   We  the   people  of  the   United  States, */        /* in   order    to   form   a    more   perfect */        /* union,  establish  justice,  insure  domestic */        /* tranquility, provide for  the common defense, */        /* promote  the  general   welfare,  and  secure */        /* the  blessing  of  liberty to  ourselves  and */        /* our  posterity, do  ordain and  establish the */        /* Constitution of the United States of America. */

Before:

        Preamble      We the people of the United States,        to the US     in order to form        Constitution  a more perfect union,                      establish justice,                      insure domestic tranquility,                      provide for the common defense,                      promote the general welfare,                      and secure the blessing of liberty                      to ourselves and our posterity,                      do ordain and establish                      the Constitution                      of the United States of America.

After"par 52h3":

        Preamble      We the people of the United        to the US     States, in order to form a        Constitution  more perfect union, establish                      justice, insure domestic                      tranquility, provide for the                      common defense, promote the                      general welfare, and secure                      the blessing of liberty to                      ourselves and our posterity,                      do ordain and establish the                      Constitution of the United                      States of America.

Before:

         1  We the people of the United States,         2  in order to form a more perfect union,         3  establish justice,         4  insure domestic tranquility,         5  provide for the common defense,         6  promote the general welfare,         7  and secure the blessing of liberty         8  to ourselves and our posterity,         9  do ordain and establish the Constitution        10  of the United States of America.

After"par 59p12l":

         1  We the people of the United States, in order to         2  form a more perfect union, establish justice,         3  insure domestic tranquility, provide for the         4  common defense, promote the general welfare,         5  and secure the blessing of liberty to ourselves         6  and our posterity, do ordain and establish the         7  Constitution of the United States of America.

Before:

        > > We the people        > > of the United States,        > > in order to form a more perfect union,        > > establish justice,        > > ensure domestic tranquility,        > > provide for the common defense,        >        > Promote the general welfare,        > and secure the blessing of liberty        > to ourselves and our posterity,        > do ordain and establish        > the Constitution of the United States of America.

After"par 52":

        > > We the people of the United States, in        > > order to form a more perfect union,        > > establish justice, ensure domestic        > > tranquility, provide for the common        > > defense,        >        > Promote the general welfare, and secure        > the blessing of liberty to ourselves and        > our posterity, do ordain and establish        > the Constitution of the United States of        > America.

Before:

        >   We the people        > of the United States,        > in order to form a more perfect union,        > establish justice,        > ensure domestic tranquility,        > provide for the common defense,        >   Promote the general welfare,        > and secure the blessing of liberty        > to ourselves and our posterity,        > do ordain and establish        > the Constitution of the United States of America.

After"par 52d":

        >   We the people of the United States,        > in order to form a more perfect union,        > establish justice, ensure domestic        > tranquility, provide for the common        > defense,        >   Promote the general welfare, and secure        > the blessing of liberty to ourselves and        > our posterity, do ordain and establish        > the Constitution of the United States of        > America.

Before:

        # 1. We the people of the United States.        # 2. In order to form a more perfect union.        # 3. Establish justice, ensure domestic        #    tranquility.        # 4. Provide for the common defense        # 5. Promote the general welfare.        # 6. And secure the blessing of liberty        #    to ourselves and our posterity.        # 7. Do ordain and establish the Constitution.        # 8. Of the United States of America.

After"par 37p13dh":

        # 1. We the people of the        #    United States.        # 2. In order to form a more        #    perfect union.        # 3. Establish justice,        #    ensure domestic        #    tranquility.        # 4. Provide for the common        #    defense        # 5. Promote the general        #    welfare.        # 6. And secure the blessing        #    of liberty to ourselves        #    and our posterity.        # 7. Do ordain and establish        #    the Constitution.        # 8. Of the United States of        #    America.

Before:

        /*****************************************/        /*   We the people of the United States, */        /* in order to form a more perfect union, */        /* establish justice, insure domestic    */        /* tranquility,                          */        /*                                       */        /*                                       */        /*   [ provide for the common defense, ] */        /*   [ promote the general welfare,    ] */        /*   [ and secure the blessing of liberty ] */        /*   [ to ourselves and our posterity, ] */        /*   [                                 ] */        /*                                       */        /* do ordain and establish the Constitution */        /* of the United States of America.       */        /******************************************/

After"par 42r":

        /********************************/        /*   We the people of the       */        /* United States, in order to   */        /* form a more perfect union,   */        /* establish justice, insure    */        /* domestic tranquility,        */        /*                              */        /*                              */        /*   [ provide for the common ] */        /*   [ defense, promote the   ] */        /*   [ general welfare, and   ] */        /*   [ secure the blessing of ] */        /*   [ liberty to ourselves   ] */        /*   [ and our posterity,     ] */        /*   [                        ] */        /*                              */        /* do ordain and establish the  */        /* Constitution of the United   */        /* States of America.           */        /********************************/

Or after"par 42re":

        /********************************/        /*   We the people of the       */        /* United States, in order to   */        /* form a more perfect union,   */        /* establish justice, insure    */        /* domestic tranquility,        */        /*                              */        /*   [ provide for the common ] */        /*   [ defense, promote the   ] */        /*   [ general welfare, and   ] */        /*   [ secure the blessing of ] */        /*   [ liberty to ourselves   ] */        /*   [ and our posterity,     ] */        /*                              */        /* do ordain and establish the  */        /* Constitution of the United   */        /* States of America.           */        /********************************/

Before:

        Joe Public writes:        > Jane Doe writes:        > >        > >        > > I can't find the source for uncompress.        > Oh no, not again!!!        >        >        > Isn't there a FAQ for this?        >        >        That wasn't very helpful, Joe. Jane,        just make a link from uncompress to compress.

After"par 40q":

        Joe Public writes:        > Jane Doe writes:        >        >        > > I can't find the source for        > > uncompress.        >        > Oh no, not again!!!        >        >        > Isn't there a FAQ for this?        >        That wasn't very helpful, Joe.        Jane, just make a link from        uncompress to compress.

Or after"par 40qe":

        Joe Public writes:        > Jane Doe writes:        >        > > I can't find the source for        > > uncompress.        >        > Oh no, not again!!!        >        > Isn't there a FAQ for this?        That wasn't very helpful, Joe.        Jane, just make a link from        uncompress to compress.

Or after"par 40qi":

        Joe Public writes:        > Jane Doe writes:        > >        > >        > > I can't find the source for        > > uncompress.        > Oh no, not again!!!        >        >        > Isn't there a FAQ for this?        >        >        That wasn't very helpful, Joe.        Jane, just make a link from        uncompress to compress.

Or after"par 40qie":

        Joe Public writes:        > Jane Doe writes:        > > I can't find the source for        > > uncompress.        > Oh no, not again!!!        >        > Isn't there a FAQ for this?        That wasn't very helpful, Joe.        Jane, just make a link from        uncompress to compress.

Before:

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

After"par 50g":

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

Or after"par 50gc":

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

Before:

        John writes:        : Mary writes:        : + Anastasia writes:        : + > Hi all!        : + Hi Ana!        : Hi Ana & Mary!        Please unsubscribe me from alt.hello.

After"par Q+:+ q":

        John writes:        : Mary writes:        :        : + Anastasia writes:        : +        : + > Hi all!        : +        : + Hi Ana!        :        : Hi Ana & Mary!        Please unsubscribe me from alt.hello.

Before:

        amc> The b option was added primarily to deal with        amc> this new style of quotation        amc> which became popular after Par 1.41 was released.        amc>        amc> Par still pays attention to body characters.        amc> Par should not mistake "Par" for part of the prefix.        amc> Par should not mistake "." for a suffix.

After"par B=._A_a 50bg":

        amc> The b option was added primarily to        amc> deal with this new style of quotation        amc> which became popular after Par 1.41        amc> was released.        amc>        amc> Par still pays attention to body        amc> characters.  Par should not mistake        amc> "Par" for part of the prefix.  Par        amc> should not mistake "." for a suffix.
 

SEE ALSO

par.doc 

LIMITATIONS

Theguessfeature guesses wrong in cases like the following:

        I calc'd the approx.        Fermi level to 3 sig. digits.

Withguess= 1,parwill incorrectly assume that "approx."ends a sentence. If the input were:

        I calc'd the approx. Fermi        level to 3 sig. digits.

thenparwould refuse to put a line break between"approx." and "Fermi" in the output,mainly to avoid creating the first situation (incase the paragraph were to be fed back throughparagain). This non-breaking space policy does come in handyfor cases like "Mr. Johnson" and "Jan. 1", though.

Theguessfeature only goes one way.parcan preserve wide sentence breaks in aparagraph, or remove them, but it can't insertthem if they aren't already in the input.

If you use tabs, you may not like the wayparhandles (or doesn't handle) them. Itexpands them into spaces. I didn't letparoutput tabs because tabs don't make sense. Not everyone'sterminal has the same tab settings, so text files containingtabs are sometimes mangled. In fact, almost every text filecontaining tabs gets mangled when something is inserted at thebeginning of each line (when quoting e-mail or commenting outa section of a shell script, for example), making them a painto edit. In my opinion, the world would be a nicer place ifeveryone stopped using tabs, so I'm doing my part by not lettingparoutput them. (Thanks to Eric Stuebe for showing me thelight about tabs.)

There is currently no way for the length of theoutput prefix to differ from the length of theinput prefix. Ditto for the suffix. I may consideradding this capability in a future release, butright now I'm not sure how I'd want it to work. 

APOLOGIES

Par began in July 1993 as a small program designed to do onenarrow task: reformat a single paragraph that might have aborder on either side. It was pretty clean back then. Overthe next three months, it very rapidly expanded to handlemultiple paragraphs, offer more options, and take betterguesses, at the cost of becoming extremely complex, and veryunclean. It is nowhere near the optimal design for the largertask it now tries to address. Its only redeeming featuresare that it is extremely useful (I find it indispensable),extremely portable, and very stable (between the releaseof version 1.41 on 1993-Oct-31 and the release of version1.52 on 2001-Apr-29, no incorrect behavior was reported).

Back in 1993 I had very little experience at writingdocumentation for users, so the documentation for Parbecame rather nightmarish. There is no separation betweenhow-it-works (which is painfully complex) and how-to-use-it(which is fairly simple, if you can ever figure it out).

Someday I ought to reexamine the problem, and redesigna new, clean solution from scratch. I don't knowwhen I might get enough free time to start on sucha project. Text files may be obsolete by then. 

BUGS

If I knew of any bugs, I wouldn't release the package. Ofcourse, there may be bugs that I haven't yet discovered.

If you find any bugs (in the program orin the documentation), or if you haveany suggestions, please send e-mail to:

amcAATTcs.berkeley.edu

When reporting a bug, please include the exact input andcommand line options used, and the version number ofpar,so that I can reproduce it.

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

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

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


 

Index

NAME
SYNOPSIS
DESCRIPTION
QUICK START
TERMINOLOGY
OPTIONS
ENVIRONMENT
DETAILS
DIAGNOSTICS
EXAMPLES
SEE ALSO
LIMITATIONS
APOLOGIES
BUGS

This document was created byman2html,using the manual pages.