35.17. $formParagraph

$formParagraph returns a “filled” form of a STRING s, i.e., a STRING containing the same sequence of words as s with as many words as possible on each line subject to the constraint that no line be longer than a specified maximum number of characters.

“Blank characters” are blank, tab, end-of-page, carriage return, and linefeed. A “word” is a sequence of non-blank characters. Lines are formed from the words in s (retaining the order of the words); words in the output are separated from each other by a single blank character, except as noted below.

The first line starts with firstLineIndent MAX 0 blanks. Subsequent lines start with - firstLineIndent MAX 0 blanks. Thus, if firstLineIndent is less than zero, all but the first line are indented.

Output lines (counting indentation) is allowed to have at most rightMargin characters. Each line contains as many words as can fit. If a word is longer than a line is allowed to be, it is put on a line by itself. The lines are separated by eol characters. The last line does not end with eol.

If not specified, rightMargin defaults to 72.

If append is set in ctrlBits, the “two-blank heuristic” is used:

• If two consecutive words occupy the same line,

• And the first word ends in a period,

• And the second word does not start with a lowercase letter,

• Then the two words are separated by two blanks rather than one blank (this may result in the second word being pushed onto the next line).

The first character of ctrlChars is an alias for space that is used to force two words to be on the same line. For example, if the first character in ctrlChars is '@' then United@States results in United States being on the same line. If the first character of ctrlChars is space (or ctrlChars is empty), then there is no space alias.

The second character of ctrlChars is an alias for period that is used to circumvent the two-blank heuristic in a specific instance. For example, if the second character in ctrlChars is '%', then for the STRING "Richard M% Nixon", $formParagraph replaces the '%' with '.' and puts one space before Nixon, whereas for the STRING "Richard M. Nixon", $formParagraph would have put two spaces before Nixon. If the second character of ctrlChars is space (or ctrlChars is shorter than two characters), then there is no period alias.

The behavior is undefined if the space alias and the period alias are the same (non-blank) character.

If strArea is specified, it denotes the area into which $formParagraph's result should be formed. If no area is specified, the default area is used.