Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
par(1)				 USER COMMANDS				par(1)

NAME
       par - filter for	reformatting paragraphs

SYNOPSIS
       par  [ help ] [ version ] [ Bopset ] [ Popset ] [ Qopset	] [ Wopset ]
	    [ Zopset ] [ 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
       par  is	a  filter  which  copies its input to its output, changing all
       white characters	(except	newlines) to  spaces,  and  reformatting  each
       paragraph.   Paragraphs are separated by	protected, blank, and bodiless
       lines (see the TERMINOLOGY section for definitions), and	optionally de-
       limited by indentation (see the d option	in the OPTIONS section).

       Each  output  paragraph is generated from the corresponding input para-
       graph 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 para-
	      graph.

	   4) The prefixes and suffixes	are reattached.

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

QUICK START
       par  is	necessarily complex.  For those	who wish to use	it immediately
       and understand it later,	assign the PARINIT  environment	 variable  the
       following value:

	      rTbgqR B=.,?'_A_a_@ Q=_s>|

       The  spaces, question mark, apostrophe, greater-than sign, and vertical
       bar will	probably have to be escaped or quoted to  prevent  your	 shell
       from interpreting them.

       The  documentation,  though  precise, is	unfortunately not well-written
       for the end-user.  Your best bet	is probably to read  quickly  the  DE-
       SCRIPTION,  TERMINOLOGY,	 OPTIONS,  and ENVIRONMENT sections, then read
       carefully the EXAMPLES section, referring back to the OPTIONS and  TER-
       MINOLOGY	sections as needed.

       For the "power user", a full understanding of par will require multiple
       readings	of the TERMINOLOGY, OPTIONS, DETAILS, and EXAMPLES sections.

TERMINOLOGY
       Miscellaneous terms:

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

			__ = an	underscore

			_s = a space

			_S = all space characters

			_b = a backslash (\)

			_q = a single quote (')

			_Q = a double quote (")

			_A = all upper case letters

			_a = all lower case letters

			_@ = all neither-case letters

			_0 = all decimal digits

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

		     The  NUL  character must not appear in the	string,	but it
		     may be included in	the set	with the _x00 sequence.

		     The exact meanings	of _S, _A, _a, _@, and _0 are  locale-
		     dependent.	  (Actually, all locales are supposed to agree
		     on	_0, but	not on the others.)  In	the  default  "C"  lo-
		     cale: _S includes only space, formfeed, newline, carriage
		     return, tab, and vertical tab; _A includes	only A through
		     Z;	_a includes only a through z; _@ includes nothing; and
		     _0	includes only 0	through	9.

	      error  A condition which causes par to abort.  See the  DIAGNOS-
		     TICS section.

	      IP     Input paragraph.

	      OP     Output paragraph.

	      parameter
		     A	symbol	which  may  take  on unsigned integral values.
		     There are several parameters whose	values affect the  be-
		     havior  of	 par.  Parameters can be assigned values using
		     command line options.

       Types of	characters:

	      alphanumeric character
		     An	alphabetic character or	 decimal  digit,  _A_a_@_0  in
		     charset syntax (see above).

	      body character
		     A	member of the set of characters	defined	by the PARBODY
		     environment variable (see the ENVIRONMENT section)	and/or
		     the B option (see the OPTIONS section).

	      protective character
		     A member  of the set of characters	defined	by the PARPRO-
		     TECT environment variable and/or the P option.

	      quote character
		     A member of the set of characters defined by the PARQUOTE
		     environment variable and/or the Q option.

	      terminal character
		     A	member	of  the	set of characters defined by the Z op-
		     tion.  Initially, before any Z  options  have  been  pro-
		     cessed,  the set contains period, question	mark, exclama-
		     tion point, and colon.

	      white character
		     A member of the set of characters defined by  the	W  op-
		     tion.   Initially,	 before	 any  W	options	have been pro-
		     cessed, the set contains space, formfeed,	newline,  car-
		     riage return, tab,	and vertical tab.

       Functions:

	      comprelen
		     Given  a  non-empty  sequence  S of lines,	let c be their
		     longest common prefix.  If	the parameter body is 0, place
		     a divider just after the leading non-body characters in c
		     (at the beginning if there	are  none).   If  body	is  1,
		     place  the	divider	just after the last non-space non-body
		     character in c (at	the beginning if there is none),  then
		     advance  the  divider over	any immediately	following spa-
		     ces.  The comprelen of S is the number of characters pre-
		     ceding the	divider.

	      comsuflen
		     Given  a non-empty	sequence S of lines, let p be the com-
		     prelen of S.  Let T be the	set of lines which result from
		     stripping	the  first  p  characters from each line in S.
		     Let c be the longest common suffix	of the lines in	T.  If
		     body  is 0, place a divider just before the trailing non-
		     body characters in	c (at the end if there are none), then
		     advance  the divider over all but the last	of any immedi-
		     ately following spaces.  If body is 1, place the  divider
		     just  before the first non-space non-body character, then
		     back up the divider over one immediately preceding	 space
		     if	 there	is  one.   The comsuflen of S is 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 two
		     lines; otherwise, the comprelen (comsuflen) of the	 block
		     containing	 the  IP,  if  the block contains at least two
		     lines; otherwise, the length of the longer	 of  the  pre-
		     fixes (suffixes) of the bodiless lines just above and be-
		     low the block, if the segment containing  the  block  has
		     any  bodiless  lines;  otherwise,	0.  (See below for the
		     definitions of block, segment, and	bodiless line.)

	      augmented	fallback prelen
		     Let fp be the fallback prelen of an IP.  If the  IP  con-
		     tains more	than one line, or if quote is 0, then the aug-
		     mented fallback prelen of the IP is  simply  fp.	Other-
		     wise,  it is fp plus the number of	quote characters imme-
		     diately following the first fp characters of the line.

	      quoteprefix
		     The quoteprefix of	a line is the longest string of	 quote
		     characters	 appearing at the beginning of the line, after
		     this string has been stripped of any trailing spaces.

       Types of	lines:

	      blank line
		     An	empty line, or a line whose  first  character  is  not
		     protective	and which contains only	spaces.

	      protected	line
		     An	input line whose first character is protective.

	      bodiless line
		     A line which is order k bodiless for some k.

	      order k bodiless line
		     There is no such thing as an order	0 bodiless line.  Sup-
		     pose S is a a contiguous subsequence of  a	 segment  (see
		     below) containing at least	two lines, containing no order
		     k-1 bodiless lines, bounded above and below by order  k-1
		     bodiless  lines  and/or the beginning/end of the segment.
		     Let p and s be the	comprelen and  comsuflen  of  S.   Any
		     member  of	S which, if stripped of	its first p and	last s
		     characters, would be blank	(or, if	the line was  not  in-
		     serted  by	the quote feature  and the parameter repeat is
		     non-zero, would consist of	the same character repeated at
		     least  repeat  times),  is	order k	bodiless.  The first p
		     characters	of the bodiless	line comprise its prefix;  the
		     last  s  characters  comprise  its	suffix.	 The character
		     which repeats in the middle is called its repeat  charac-
		     ter.   If	the  middle is 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.  If  con-
		     tiguous  vacant  lines  lie  at the beginning or end of a
		     segment, they are all superfluous.	 But if	they  lie  be-
		     tween two non-vacant lines	within a segment, then all are
		     superfluous except	one--the one which contains the	fewest
		     non-spaces.   In  case  of	 a  tie, the first of the tied
		     lines is chosen.  Similarly, if  contiguous  blank	 lines
		     lie  outside  of  any segments at the beginning or	end of
		     the input,	they are all superfluous.  But if they lie be-
		     tween  two	 segments and/or protected lines, then all are
		     superfluous except	the first.

       Groups of lines:

	      segment
		     A contiguous sequence of input lines containing  no  pro-
		     tected  or	 blank	lines, bounded above and below by pro-
		     tected lines, blank lines,	and/or	the  beginning/end  of
		     the input.

	      block  A contiguous subsequence of a segment containing no bodi-
		     less lines, bounded above and  below  by  bodiless	 lines
		     and/or the	beginning/end of the segment.

       Types of	words:

	      capitalized word
		     If	 the  parameter	 cap  is  0, a capitalized word	is one
		     which contains at least one alphanumeric character, whose
		     first  alphanumeric character is not a lower case letter.
		     If	cap is 1, every	word is	considered a capitalized word.
		     (See the c	option in the OPTIONS section.)

	      curious word
		     A	word  which  contains a	terminal character c such that
		     there are no alphanumeric characters in the word after c,
		     but  there	 is at least one alphanumeric character	in the
		     word before c.

OPTIONS
       Any command line	argument may begin with	one minus sign	(-)  which  is
       ignored.	  Generally,  more than	one option may appear in a single com-
       mand line argument, but there are exceptions:  The help,	version, B, P,
       and Q options must have whole arguments all to themselves.

       help	 Causes	 all  remaining	 arguments to be ignored.  No input is
		 read.	A usage	message	is printed on the output  briefly  de-
		 scribing the options used by par.

       version	 Causes	 all  remaining	 arguments to be ignored.  No input is
		 read.	"par " followed	by its version number  is  printed  on
		 the output.

       Bopset	 op  is	 a  single character, either an	equal sign (=),	a plus
		 sign (+), or a	minus sign (-),	and  set  is  a	 string	 using
		 charset  syntax.   If	op  is	an equal sign, the set of body
		 characters is set to the character set	defined	by set.	 If op
		 is  a	plus/minus  sign, the characters in the	set defined by
		 set are added/removed to/from the existing set	of body	 char-
		 acters	 defined  by  the PARBODY environment variable and any
		 previous B options.  It is okay to add	 characters  that  are
		 already  in  the  set or to remove characters that are	not in
		 the set.

       Popset	 Just like the B option, except	that it	applies	to the set  of
		 protective characters.

       Qopset	 Just  like the	B option, except that it applies to the	set of
		 quote characters.

       Wopset	 Just like the B option, except	that it	applies	to the set  of
		 white characters.

       Zopset	 Just  like the	B option, except that it applies to the	set of
		 terminal characters.

       All remaining options are used to set values of parameters.  Values set
       by  command line	options	hold for all paragraphs.  Unset	parameters are
       given default values.  Any parameters whose default  values  depend  on
       the  IP (namely prefix and suffix), if left unset, are recomputed sepa-
       rately for each paragraph.

       The approximate role of each variable is	described here.	 See  the  DE-
       TAILS section for the rest of the story.

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

       h[hang]	 Mainly	affects	the default values of prefix and suffix.   De-
		 faults	 to 0.	If the h option	is given without a number, the
		 value 1 is inferred.  (See also the p and s options.)

       p[prefix] The first prefix characters of	each line of the OP are	copied
		 from the first	prefix characters of the corresponding line of
		 the IP.  If there are more than hang+1	lines in the  IP,  the
		 default value is the comprelen	of all the lines in the	IP ex-
		 cept the first	hang of	them.  Otherwise, the default value is
		 the  augmented	fallback prelen	of the IP.  If the p option is
		 given without a number, prefix	is unset, even if it had  been
		 set earlier.  (See also the h and q options.)

       r[repeat] If  repeat is non-zero, bodiless lines	have the number	of in-
		 stances of their repeat characters increased or decreased un-
		 til  the length of the	line is	width.	The exact value	of re-
		 peat affects the definition of	bodiless line.	Defaults to 0.
		 If the	r option is given without a number, the	value 3	is in-
		 ferred.  (See also the	w option.)

       s[suffix] The last suffix characters of each line of the	OP are	copied
		 from  the last	suffix characters of the corresponding line of
		 the IP.  If there are more than hang+1	lines in the  IP,  the
		 default value is the comsuflen	of all the lines of the	IP ex-
		 cept the first	hang of	them.  Otherwise, the default value is
		 the  fallback	suflen	of  the	 IP.  If the s option is given
		 without a number, suffix is unset, even if it	had  been  set
		 earlier.  (See	also the h option.)

       T[Tab]	 Tab  characters in the	input are expanded to spaces, assuming
		 tab stops every Tab columns.  Must not	be 0.  Defaults	to  1.
		 If the	T option is given without a number, the	value 8	is in-
		 ferred.

       w[width]	 No line in the	OP may contain more than width characters, not
		 including  the	 trailing newlines.  Defaults to 72.  If the w
		 option	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, and touch, may be set	to ei-
       ther 0 or 1.  If	the number is absent in	the option, the	value 1	is in-
       ferred.

       b[body]	 If  body  is  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.)   If	 body is 0, prefixes and suffixes may not con-
		 tain any body characters at all.  Defaults to 0.

       c[cap]	 If cap	is 1, all words	are considered capitalized.  This cur-
		 rently	 affects  only	the  application of the	g option.  De-
		 faults	to 0.

       d[div]	 If div	is 0, each block becomes an IP.	 If  div  is  1,  each
		 block	is  subdivided into IPs	as follows:  Let p be the com-
		 prelen	of the block.  Let a line's status be 1	if its (p+1)st
		 character  is	a space, 0 otherwise.  Every line in the block
		 whose status is the same as the status	of the first line will
		 begin a new paragraph.	 Defaults to 0.

       E[Err]	 If  Err  is  1,  messages to the user (caused by the help and
		 version options, or by	errors)	are sent to the	 error	stream
		 instead of the	output stream.	Defaults to 0.

       e[expel]	 If  expel  is 1, superfluous lines are	withheld from the out-
		 put.  Defaults	to 0.

       f[fit]	 If fit	is 1 and just is 0, par	tries to make the lines	in the
		 OP  as	 nearly	 the same length as possible, even if it means
		 making	the OP narrower.  Defaults to 0.  (See also the	j  op-
		 tion.)

       g[guess]	 If  guess  is 1, then when par	is choosing line breaks, when-
		 ever it encounters a curious word followed by	a  capitalized
		 word,	it takes one of	two special actions.  If the two words
		 are separated by a single space in the	input,	they  will  be
		 merged	into one word with an embedded non-breaking space.  If
		 the two words are separated by	more than one space, or	 by  a
		 line  break,  par  will insure	that they are separated	by two
		 spaces, or by a line break, in	the output.  Defaults to 0.

       i[invis]	 If invis is 1,	then vacant lines inserted because quote is  1
		 are  invisible; that is, they are not output.	If quote is 0,
		 invis has no effect.  Defaults	to 0.  (See  also  the	q  op-
		 tion.)

       j[just]	 If  just is 1,	par justifies the OP, inserting	spaces between
		 words so that all lines in the	OP have	length	width  (except
		 the last, if last is 0).  Defaults to 0.  (See	also the w, l,
		 and f options.)

       l[last]	 If last is 1, par tries to make the last line of the OP about
		 the same length as the	others.	 Defaults to 0.

       q[quote]	 If  quote is 1, then before each segment is scanned for bodi-
		 less lines, par supplies vacant lines between different  quo-
		 tation	 nesting levels	as follows:  For each pair of adjacent
		 lines in the segment, (scanned	from the top down) which  have
		 different quoteprefixes, one of two actions is	taken.	If in-
		 vis is	0, and either line consists entirely of	quote  charac-
		 ters  and spaces (or is empty), that line is truncated	to the
		 longest common	prefix of the two lines	(both are truncated if
		 both  qualify).   Otherwise, a	line consisting	of the longest
		 common	prefix of the two  lines  is  inserted	between	 them.
		 quote	also affects the default value of prefix.  Defaults to
		 0.  (See also the p and i options.)

       R[Report] If Report is 1, it is considered an error for an  input  word
		 to  contain  more  than L = (width - prefix - suffix) charac-
		 ters.	Otherwise, such	words are chopped after	each Lth char-
		 acter into shorter words.  Defaults to	0.

       t[touch]	 Has  no  effect  if  suffix is	0 or just is 1.	 Otherwise, if
		 touch is 0, all lines in the OP have length width.  If	 touch
		 is 1, the length of the lines is decreased until the suffixes
		 touch the body	of the OP.  Defaults to	the logical OR of  fit
		 and last.  (See also the s, j,	w, f, and l options.)

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

       If the value of any parameter is	set more than once, the	last value  is
       used.   When  unset  parameters	are  assigned default values, hang and
       quote are assigned before prefix, and fit and last are assigned	before
       touch (because of the dependencies).

       It is an	error if width <= prefix + suffix.

ENVIRONMENT
       PARBODY	 Determines the	initial	set of body characters (which are used
		 for determining comprelens  and  comsuflens),	using  charset
		 syntax.  If PARBODY is	not set, the set of body characters is
		 initially empty.

       PARINIT	 If set, par will read command line options from  PARINIT  be-
		 fore  it  reads them from the command line.  Within the value
		 of PARINIT, arguments are separated by	 the  initial  set  of
		 white characters.

       PARPROTECT
		 Determines  the  set  of protective characters, using charset
		 syntax.  If PARPROTECT	is not	set,  the  set	of  protective
		 characters is initially empty.

       PARQUOTE	 Determines the	set of quote characters, using charset syntax.
		 If PARQUOTE is	not set, the set of quote characters initially
		 contains only the greater-than	sign (>) and the space.

       If  a NUL character appears in the value	of an environment variable, it
       and the rest of the string will not be seen by par.

       Note that the PARINIT variable, together	with the B, P, and Q  options,
       renders the other environment variables unnecessary.  They are included
       for backward compatibility.

DETAILS
       Lines are terminated by newline characters, but the  newlines  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
       (but  if	the input is empty, no newline will be inferred; the number of
       input lines will	be 0).	Thus, the input	can always be viewed as	a  se-
       quence of lines.

       Protected lines are copied unchanged from the input to the output.  All
       other input lines, as they are read, have any NUL  characters  removed,
       and every white character (except newlines) turned into a space.	 Actu-
       ally, each tab character	is turned into Tab - (n	% Tab) spaces, where n
       is  the	number	of  characters preceding the tab character on the line
       (evaluated after	earlier	tab characters have been expanded).

       Blank lines in the input	are transformed	into empty lines in  the  out-
       put.

       If  repeat is 0,	all bodiless lines are vacant, and they	are all	simply
       stripped	of trailing spaces before being	output.	 If repeat is  not  0,
       only  vacant  lines  whose suffixes have	length 0 are treated that way;
       other bodiless lines have the number of instances of their repeat char-
       acters increased	or decreased until the length of the line is width.

       If  expel  is  1, superfluous lines are not output.  If quote and invis
       are both	1, there may be	invisible lines; they are not output.

       The input is divided into segments,  which  are	divided	 into  blocks,
       which are divided into IPs.  The	exact process depends on the values of
       quote and div (see q and	d in the OPTIONS section).  The	 remainder  of
       this  section  describes	 the process which is applied independently to
       each IP to construct the	corresponding OP.

       After the values	of the parameters are determined (see the OPTIONS sec-
       tion),  the  first  prefix characters and the last suffix characters of
       each input line are removed and remembered.  It is  an  error  for  any
       line to contain fewer than prefix + suffix characters.

       The  remaining  text is treated as a sequence of	characters, not	lines.
       The text	is broken into words, which are	separated by spaces.  That is,
       a  word	is  a maximal sub-sequence of non-spaces.  If guess is 1, some
       words might be merged (see g in the OPTIONS section).  The  first  word
       includes	any spaces that	precede	it on the same line.

       Let L = width - prefix -	suffix.

       If  Report  is 0, some words may	get chopped up at this point (see R in
       the OPTIONS section).

       The words are reassembled, preserving their order, into lines.  If just
       is 0, adjacent words within a line are separated	by a single space, (or
       sometimes two if	guess is 1), and line breaks are chosen	 so  that  the
       paragraph satisfies the following properties:

	      1) No line contains more than L characters.

	      2) If fit	is 1, the difference between the lengths of the	short-
		 est and longest lines is as small as possible.

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

	      4) Let  target  be  L  if	fit is 0, or the length	of the longest
		 line if fit is	1.  The	sum of the squares of the  differences
		 between  target  and  the lengths of the lines	is as small as
		 possible, subject to properties 1, 2, and 3.

	    If last is 0, the last line	does not count as a line for the  pur-
	    poses of properties	2, 3, and 4 above.

	    If	all  the  words	fit on a single	line, the properties as	worded
	    above don't	make much sense.  In that case,	no line	breaks are in-
	    serted.

       If  just	 is 1, adjacent	words within a line are	separated by one space
       (or sometimes two if guess is 1)	plus zero or more extra	 spaces.   The
       value  of  fit  is  disregarded,	and line breaks	are chosen so that the
       paragraph satisfies the following properties:

	      1) Every line contains exactly L characters.

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

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

	    If	last is	0, the last line does not count	as a line for the pur-
	    poses of property 1, and it	does not require or contain any	 extra
	    spaces.

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

	    In a justified paragraph, every line must  contain	at  least  two
	    words, but that's not always possible to accomplish.  If the para-
	    graph cannot be justified, it is considered	an error.

       If the number of	lines in the resulting paragraph is  less  than	 hang,
       empty  lines  are  added	 at the	end to bring the number	of lines up to
       hang.

       If just is 0 and	touch is 1, L is changed to be the length of the long-
       est line.

       If suffix is not	0, each	line is	padded at the end with spaces to bring
       its length up to	L.

       To each line is prepended prefix	characters.  Let n be  the  number  of
       lines  in  the  IP, let afp be the augmented fallback prelen of the IP,
       and let fs be the fallback suflen of the	IP.  The characters which  are
       prepended to the	ith line are chosen as follows:

	   1) If i <= n, the characters	are copied from	the ones that were re-
	      moved from the beginning of the nth input	line.

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

	   3) If i > n and n <=	hang, the first	min(afp,prefix)	of the charac-
	      ters are copied from the ones that were removed from the	begin-
	      ning of the last input line, and the rest	are all	spaces.

       Then  to	each line is appended suffix characters.  The characters which
       are appended to the ith line are	chosen as follows:

	   1) If i <= n, the characters	are copied from	the ones that were re-
	      moved from the end of the	nth input line.

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

	   3) If i > n and n <=	hang, the first	min(fs,suffix) of the  charac-
	      ters  are	copied from the	ones that were removed from the	begin-
	      ning of the last 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, par returns EXIT_SUCCESS	(see <stdlib.h>).

       If there	is an error, an	error message will be printed to  the  output,
       and  par	 will  return EXIT_FAILURE.  If	the error is local to a	single
       paragraph, the preceding	paragraphs will	have been  output  before  the
       error was detected.  Line numbers in error messages are local to	the IP
       in which	the error occurred.  All error messages	 begin	with  "par er-
       ror:"  on  a line by itself.  Error messages concerning command line or
       environment variable syntax are accompanied by the same	usage  message
       that the	help option produces.

       Of course, trying to print an error message would be futile if an error
       resulted	from an	output function, so par	doesn't	bother doing any error
       checking	on output functions.

EXAMPLES
       The  superiority	 of  par's dynamic programming algorithm over a	greedy
       algorithm (such as the one used by fmt) can be seen  in	the  following
       example:

       Original	paragraph (note	that each 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 by par are clearly more eye-pleasing.

       par  is	most useful in conjunction with	the text-filtering features of
       an editor, such as the !	commands of vi.	 You may wish to add the  fol-
       lowing lines to your .exrc file:

	  " 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 what is shown as
       ^M and ^V really	need to	be ctrl-M and ctrl-V.  Also note that the last
       map  command  contains two spaces following the ctrl-V, plus one	at the
       end of the line.

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

       The rest	of this	section	is a series of before-and-after	pictures show-
       ing some	typical	uses of	par.  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
       The guess feature guesses wrong in cases	like the following:

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

       With guess = 1, par will	incorrectly assume that	"approx."  ends	a sen-
       tence.  If the input were:

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

       then par	would refuse to	put a line break between "approx." and "Fermi"
       in  the	output,	 mainly	to avoid creating the first situation (in case
       the paragraph were to be	fed back through par again).  This  non-break-
       ing  space  policy  does	come in	handy for cases	like "Mr. Johnson" and
       "Jan. 1", though.

       The guess feature only goes one way.  par can  preserve	wide  sentence
       breaks in a paragraph, or remove	them, but it can't insert them if they
       aren't already in the input.

       If you use tabs,	you may	not like the way par handles (or doesn't  han-
       dle)  them.  It expands them into spaces.  I didn't let par output tabs
       because tabs don't make sense.  Not everyone's terminal	has  the  same
       tab  settings, so text files containing tabs are	sometimes mangled.  In
       fact, almost every text file containing tabs gets  mangled  when	 some-
       thing is	inserted at the	beginning of each line (when quoting e-mail or
       commenting out a	section	of a shell script, for example), making	them a
       pain  to	 edit.	In my opinion, the world would be a nicer place	if ev-
       eryone stopped using tabs, so I'm doing my part by not letting par out-
       put them.  (Thanks to Eric Stuebe for showing me	the light about	tabs.)

       There is	currently no way for the length	of the output prefix to	differ
       from the	length of the input prefix.  Ditto for the suffix.  I may con-
       sider adding this capability in a future	release, but right 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  one	narrow
       task:  reformat	a  single paragraph that might have a border on	either
       side.  It was pretty clean back then.  Over the next three  months,  it
       very  rapidly  expanded	to  handle multiple paragraphs,	offer more op-
       tions, and take better guesses, at the cost of becoming extremely  com-
       plex,  and very unclean.	 It is nowhere near the	optimal	design for the
       larger task it now tries	to address.  Its only redeeming	 features  are
       that it is extremely useful (I find it indispensable), extremely	porta-
       ble, and	very stable since version 1.41 released	on 1993-Oct-31.

       Back in 1993 I had very little experience at writing documentation  for
       users,  so  the documentation for Par became rather nightmarish.	 There
       is no separation	between	how-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 redesign a	new, clean so-
       lution from scratch.  I don't know when I might get enough free time to
       start on	such a project.	 Text files may	be obsolete by then.

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

       If you find any bugs (in	the program or in the  documentation),	or  if
       you have	any suggestions, please	contact	me:

	      http://www.nicemice.net/amc/

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

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

	      http://www.nicemice.net/par/

       I  don't	 expect	 these URLs to change in the forseeable	future,	but if
       they do,	I'll try to leave forward pointers.

Par 1.53.0			  2020-Mar-14				par(1)

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=par&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help