PCCON Paragraph Formatter (Version 2.2.3)
Last Updated: Jeffrey Knauth
PCCON is a KEDIT macro which allows you to easily format a paragraph. The paragraph must be delimited by blank lines or by top/bottom of file/range lines. Formatting consists of flowing the text to put the proper number of spaces between words, taking punctuation into account. It also means ensuring that each line is the correct length and that each line is appropriately indented from column 1.
PCCON is similar to the KEDIT FLOW command, but has some significant differences and improvements. These are described in a section at the end of this document.
PCCON Variables
Three variables control how PCCON formats a paragraph:
"margin" specifies the rightmost column a line can use. It corresponds to the margins.2 value (right margin) in the KEDIT SET MARGINS command. Of course if a line consists of a single large word which cannot fit within the right margin, it is allowed to flow over that margin. This may not look pretty, but no text is lost.
"hanging indent" specifies how far the first paragraph line is offset from the second and following lines of the paragraph. A hanging indent of 0 means all the lines of the paragraph are aligned in the same column on the left. A positive hanging indent means the first line starts "hanging indent" columns to the left of the second and subsequent lines. A leading "+" in the hanging indent value is ignored; i.e., "+6" is treated as "6". The default hanging indent value is 3, which covers the the very common case of a paragraph starting with a three character overhang, e.g., "1) " or "a) " as the first word and following space. A negative hanging indent means the first line starts "hanging indent" columns to the right of the subsequent lines. Note this use of positive and negative is exactly reversed from the use by the KEDIT SET MARGINS command.
"inset" specifies how far the leftmost text of the paragraph (in any line) is shifted right from column 1. An inset of 0 means the leftmost text is in column 1. The default value is 0. Contrast this with the way KEDIT SET MARGINS specifies the left margin of a paragraph. PCCON uses the leftmost text, whether it is in the first or second line of the paragraph, to calculate inset. SET MARGINS uses the second line (and subsequent lines) of the paragraph, i.e., the bulk of the paragraph, to specify the left margin and doesn't care if the first line is a hanging indent line that may be further left than the rest of the paragraph.
This figure shows how these PCCON and KEDIT variables apply to the following two paragraphs with hanging indents, one positive and one negative.
KEDIT left margin KEDIT right margin
col 1 col 5 col 13 col 80
: : : :
| (80) . | |
| "margin" . | |
*--------------------------------------------------------------*
| . | |
| *---------------(max line length 76)---------------*
| (4) ===================================================| line 1
| "inset" . ======================================== line 2
*----------*. ======================================== line 3
| . (+8) ====== formatted text ============== | .
| . "hanging ======================================== .
| . indent" ==================================== | .
| *----------*====================================== | .
| *--------------------------------------* .
| | (max line length 68) | .
| | | .
| | | .
| | | .
| | | .
| | | .
| | +-- "hanging indent" (-6) | .
| | | | .
| | | col 19 | .
| | | | | .
| | V *---(max line length 62)----* .
| *---------*============================| .
| (12) ======================================== .
| "inset" ===================================== | .
*----------------------*======================================== .
| ====== formatted text ============== | .
| ======================================== .
| =======================================| line n
*--------------------------------------*
(max line length 68)
Paragraph Types
By adjusting the inset and hanging indent values, PCCON makes it very easy to format paragraphs of various types, such as
The following figure illustrates these concepts and the PCCON invocations used to create a succession of paragraphs. (The detailed PCCON syntax is described later in this document.) Note how USESHAPE is used to analyze the shape of a paragraph and to save the learned INSET and HANGIND shape values for use as defaults in subsequent PCCON invocations.
PCCON Invocation
You can assign PCCON invocations with various parameter/option settings to whatever key combinations you want. Below are some examples you might put in your WINPROF.KEX. The first five are the most frequently used.
"MACRO PCCON (USESHAPE" is especially handy if paragraph shapes change frequently in the document you are creating. Just use it on an existing paragraph with the desired shape (per its first two lines) that you now want to use for some other paragraphs. That records the shape of this paragraph for future use with the other paragraphs, as well as reformatting the paragraph. The reformatting may not really be necessary, but is no problem if that paragraph was already fully formatted; reformatting it leaves it unchanged.
If you don't want to use keys for most of these, you can define one key as in the S-C-F10 example below; then type the desired macro invocation on the command line, put the cursor in the target paragraph, and press the key to which you assigned 'cmdline.3(); "SOS SAVE QCMND RESTORE"'. This key will act as if you had defined it to have the command line text assigned. (Thanks to Kent Downs for this technique.)
An example line in WINPROF.KEX might be something like this to have the C-F3 key combination invoke the PCCON macro with the specified parameters: 'DEFINE C-F3 "MACRO PCCON (INSET CP HANGIND 0"' (the ending mark is a double quote followed by a single quote). The keys show in the table are the ones I use, but any others could be used.
| Key | Macro Invocation | Result of Formatting |
|---|---|---|
| C-F1 | PCCON (INSET 0 HANGIND 0 | Format as an ordinary paragraph, left edge in column 1 |
| C-F2 | PCCON | Format as a list item paragraph |
| C-F3 | PCCON (INSET CP HANGIND 0 | Format as a continuation paragraph |
| C-F5 | PCCON (USESHAPE | Format with and save paragraph shape |
| C-F4 | PCCON (CHGMARGIN | Change right margin |
| The following three macros format lines FROM THE CURSOR LINE DOWN thru the rest of the paragraph. | ||
| S-C-F2 | PCCON (CURSOR | Format as a list item paragraph using previously saved shape |
| S-C-F3 | PCCON (CURSOR INSET CP HANGIND 0 | Format as a continuation paragraph using previously saved shape |
| S-C-F5 | PCCON (CURSOR USESHAPE | Format with and save NEW shape from cursor line and next line |
| C-F7 | PCCON (HANGIND 0 | Format as a list paragraph |
| S-C-F1 | PCCON 1 (INSET 0 HANGIND | Split into single word lines |
| C-F6 | PCCON (SENTENCE | Split on sentence ends |
| S-C-F6 | PCCON (PUNCMARK | Split at all punctuation marks |
| S-C-F8 | PCCON (DISPVALS | Display PCCON values |
| The following two entries show some useful actions you can specifiy with a key DEFINE. | ||
| S-C-F4 | "SET MARGINS" margins.1() "72"; "COLMARK 73" | Reset right margin to 72; column marker to 73 |
| S-C-F10 | cmdline.3(); "SOS SAVE QCMND RESTORE" | Execute command line content with the cursor in a file line. |
PCCON Syntax
Help information similar to the following is displayed when "PCCON ?" is issued.
Format: PCCON [margin] [ ( options ]
margin specifies the right margin used to format the paragraph. The default for this parameter is the current margins.2 value, which can be changed by the KEDIT SET MARGINS command or by using "PCCON (CHGMARGIN".
Options:
HANGIND hanging-indent-value Format paragraph using specified hanging indent. A positive value produces a left hanging indent; a negative value produces a right hanging indent. The default is 3.
INSET inset-value | CP Format paragraph using specified inset, where "CP" means "inset = saved inset + saved hanging indent". The default is 0.
USESHAPE Use and save shape of cursor-designated paragraph, where shape means the inset and hanging indent created by the first two lines of the paragraph.
CURSOR Format paragraph starting with cursor-designated line. Lines prior to the cursor-designated line are not changed.
SENTENCE Split paragraph on sentence boundaries.
PUNCMARK Split paragraph on punctuation boundaries.
DISPVALS Display current saved paragraph shape values.
KEDITVALS Derive and save inset and hanging indent values from current KEDIT margins.1 and margins.3 values.
CHGMARGIN Change right margin (KEDIT margins.2 value); the cursor designates the desired right margin.
Example: PCCON 56 (INSET 10 HANGIND 5
This would format the cursor-designated paragraph with a right margin of 56. The first line would start in column 11 (1 + the inset of 10). Subsequent lines would be indented an additional 5 spaces. These values apply only for this PCCON invocation. To make these the default values, you can first use "PCCON (CHGMARGIN" (or KEDIT SET MARGINS) to set the default right margin. Then use "PCCON (USESHAPE" on a paragraph whose first two lines have the desired inset and hanging indent.Using "PCCON (USESHAPE"
"PCCON (USESHAPE" is used to learn the desired shape of a selected paragraph, save those shape characteristics (the derived INSET and HANGIND values) for use on other paragraphs, and then finish formatting the selected paragraph. Note that the right margin value is not learned and saved by "PCCON (USESHAPE"; it must be set separately with "PCCON (CHGMARGIN" or KEDIT SET MARGINS. The selected paragraph does not have to be neatly formatted to begin with. Only the indentation of the first two lines is important; the specific text currently on the lines doesn't matter. For example, here are some before and after paragraphs. "PCCON (USESHAPE" operated on the Example 1 "before" paragraph to produce the Example 1 "after" paragraph. Then the Example 2 "before" paragraph was operated on by just "PCCON" to produce the Example 2 "after" paragraph using the shape characteristics learned when Example 1 was formatted.
----------------------------------- Before -------------------------------------
Example 1: This paragraph
is sufficiently formatted to allow
"PCCON (USESHAPE" to determine its desired shape. Only the
indentations of the first two lines are used to
figure out the correct INSET and HANGIND values
to format the paragraph and to be saved so just
"PCCON" can be used to format other paragraphs to the same shape.
Example 2: Those other
paragraphs can have completely arbitrary placement
of text, including the indentations of their first two lines
because the proper INSET and HANGIND values were saved by the
"PCCON (USESHAPE". Note the margin used is not learned and
saved by "PCCON (USESHAPE"; whatever margin is specified on
"PCCON" or the current default margin will be used.
----------------------------------- After --------------------------------------
Example 1: This paragraph is sufficiently formatted to allow "PCCON
(USESHAPE" to determine its desired shape. Only the
indentations of the first two lines are used to figure out the
correct INSET and HANGIND values to format the paragraph and to
be saved so just "PCCON" can be used to format other paragraphs
to the same shape.
Example 2: Those other paragraphs can have completely arbitrary placement
of text, including the indentations of their first two lines
because the proper INSET and HANGIND values were saved by the
"PCCON (USESHAPE". Note the margin used is not learned and
saved by "PCCON (USESHAPE"; whatever margin is specified on
"PCCON" or the current default margin will be used.
Miscellaneous Items
Here are some other considerations about using PCCON:
- You can format a paragraph with PCCON as many times as you like, in any way you like, without losing any text except extra spaces. If you make a mistake, just format the paragraph again the way you want it.
- Before using PCCON to format a paragraph, be sure to delimit the paragraph with blank lines. PCCON will keep formatting until it finds a blank line or the top or bottom of the file/range. (When the CURSOR option is used, the line above the cursor-designated line is considered to be a blank line.) If you forget to do this paragraph delimiting and accidentally format more than you intended, you can use the KEDIT UNDO command to recover to the pre-format state. Then insert temporary blank lines to delimit the paragraph; next, format the delimited paragraph; finally, remove any extraneous blank lines.
- If you accidentally include text in the right part of a long overhang in positions which you really wanted to be blank, just move the text to the right (or split it to the next line) to get it outside the overhang area. Then format the paragraph again.
- If the overhang of a hanging indent paragraph contains spaces, that exact spacing is preserved. This lets you create list paragraphs with complicated overhangs, e.g., "12/25/99 14:35:01" keeping both spaces between the words.
- If a paragraph contains any excluded (shadow) lines, PCCON will refuse to format that paragraph. This prevents results that are usually undesired because the user had forgotten that some lines were excluded.
- You can add more abbreviations to the ab1, ab2, ab3, etc., variables in the PCCON macro. Abbreviations found in these variables will not be treated as the end of a sentence and thus will not have a second space appended. The abbreviations included are for the most part titles that occur before a proper (capitalized) name. The intent is to have "Mr. Smith" be considered as two ordinary words in a sentence and not consider the "." in "Mr." as a sentence ending full stop with the capitalized "Smith" as the start of the next sentence. Only abbreviations which might often be followed by a capitalized word cause this problem and are included in these variables. Other abbreviations, which are not usually followed by capitalized words, don't have to be in the variables.
- Sometimes when you are editing a paragraph, you want to move a sentence. This usually requires making several splits in the text to isolate the sentence to be moved and to provide a place for it to move to. After the move, you flow the paragraph back together. PCCON provides the SENTENCE option to automatically split a paragraph into its component sentences. The sentences can then be easily moved around before PCCON is invoked to flow the paragraph back together. The PUNCMARK option splits the paragraph into even smaller punctuation-bounded pieces, if the SENTENCE option separation isn't granular enough.
- Sometimes you want to sort the words of a paragraph consisting of a number of adjacent lines, each of which contains one or more single-word items. Ordinarily you would have to split each line into its component words, one per line, and then invoke KEDIT SORT. If instead you use "PCCON 1 (INSET 0 HANGIND 0" on the paragraph, that will split the paragraph into a number of lines with a single word per line. (The margin value of 1 forces the paragraph formatting to start a new line for each word.) You can then invoke KEDIT SORT. Finally (if desired) you can invoke "PCCON (INSET 0 HANGIND 0" to flow the lines back into a compact paragraph using the default right margin.
- PCCON uses the X'FF' character for some special processing. PCCON sometimes substitutes X'FF' for a space character (X'20') to prevent that space's position from being deleted during flow processing. After the flow processing completes, all the X'FF' characters in the paragraph are replaced by normal X'20' space characters. If a X'FF' character, an "umlauted y" ( ), had previously been in the paragraph as normal text, it will get translated to a space and/or be deleted by PCCON processing of that paragraph. If this is a problem, the PCCON rqd_blnk variable can be set to some other character which never shows up in your text.
- The PCCONALL macro formats all the paragraphs of the file being edited. It uses the current values of inset, hanging indent, and margin. To do this formatting, PCCONALL invokes the PCCON macro for each paragraph in the file. Because excluded lines are not permitted for PCCON, the KEDIT ALL command is issued first to display all file lines, including those previously excluded.
- In Version 2.2, I added a warning message when PCCON is used to format a KEDIT Untitled.# file: "YOU SHOULD NAME THIS FILE BEFORE WORKING ON IT!'" The intent is to warn the user not to do much work on such a file since it would be easy to lose that work.
- In version 2.2, I added automatic breaks to start a new line if PCCON encounters a '<a', '(<a', '<span', or '(<span' -- lower case required. This neatens some of HTML coding.
- In version 2.2.1, if the first and only word of a line is just triple-double quotes ("""), the line is treated as an as-is line (see section below). This allows easy formatting of large comment blocks (documentation strings) in Python.
- In version 2.2.2, if a line starts with 'variable-name = """' (without the single quotes) and has no other text, then the line is treated as an as-is line (see section below). This allows a Python programmer to assign variable names to individual documentation strings so specific strings can be accessed later, e.g., for a help display.
"As Is" Lines: How To Bypass Formatting Certain Lines
You may have some special lines that you don't want PCCON to format. You want the surrounding lines of the paragraph to be flowed, but you want the special lines to be left "as is". No inset, hanging indent, or margin processing applies to those lines. Perhaps they contain a table or figure where spacing and alignment is important. PCCON lets you flag such "as is" lines by making the first character of the first word of each "as is" line be a "_". If "_" is undesirable to use for this purpose, you can edit the PCCON "break_char" variable to choose another character. You can also set the "break_char" variable to "" (empty string) to completely disable the "as is" function. Here is a before and after example:
---------------------------------- Before ---------------------------------------
Here is some unformatted text occurring above
a few "as is" lines. You want this text
flowed above those lines,
but you want the "as is" lines left unchanged.
_ ==============================
_ Name Age Score A
_ ------ --- ----- +---------------------+ |
_ Howard 25 6 | | the range of
_ John 17 4 | (example of) | "as is" lines,
_ Mary 19 5 | ( a figure ) | flagged with
_ Charlie 3 12 | | a leading "_"
_ +---------------------+ |
_ V
_ ==============================
Here is some text after the "as is" lines, but
still in the same paragraph. These lines will be flowed after the
"as is" lines.
Note that the "_" in each "as is" line is the first character of
the first word of each such line. It doesn't have to be the only character
in the word (although it is in this example), nor does it have to be
at any particular position in the line. Put it where it looks best,
but before any other text in the line.
----------------------------------- After ----------------------------------------
Here is some unformatted text occurring above a few "as is" lines. You want this
text flowed above those lines, but you want the "as is" lines left unchanged.
_ ==============================
_ Name Age Score A
_ ------ --- ----- +---------------------+ |
_ Howard 25 6 | | the range of
_ John 17 4 | (example of) | "as is" lines,
_ Mary 19 5 | ( a figure ) | flagged with
_ Charlie 3 12 | | a leading "_"
_ +---------------------+ |
_ V
_ ==============================
Here is some text after the "as is" lines, but still in the same paragraph. These
lines will be flowed after the "as is" lines. Note that the "_" in each "as is"
line is the first character of the first word of each such line. It doesn't have
to be the only character in the word (although it is in this example), nor does it
have to be at any particular position in the line. Put it where it looks best,
but before any other text in the line.
If the first word of a line is """ (i.e., just """ followed by a space or the end
of the line), the line is treated as an "as is" line. Such lines can begin and
end a Python long comment block (aka a documentation string). If blank lines
precede and follow such a block, it is then easy to format.
PCCON vs. the KEDIT FLOW Command
As a paragraph formatter, PCCON is analogous to the KEDIT FLOW command. However, there are some significant differences:
- Sometimes FLOW adds an undesired extra space after certain
punctuation, e.g., after an abbreviation which it mistakes for the
end of a sentence. It also adds an extra space after drive
identifiers, e.g., "C:". PCCON corrects some of these problems.
(There is no 100% accurate solution for this because exactly the same
text can be interpreted multiple ways, as shown below.) Here are
some examples of FLOW vs PCCON processing:
Mr. Smith formatted his C: drive accidentally. FLOW often produces extra spaces Dr. Smith formatted his C: drive accidentally. FLOW often produces extra spaces Mr. Smith formatted his C: drive accidentally. PCCON almost always does not Dr. Smith formatted his C: drive accidentally. PCCON almost always does not How Mr. Smith did this is unknown. PCCON almost always does not How Dr. Smith did this is unknown. PCCON cannot avoid this extra space (see below) Step 1: Do this.. PCCON intentionally puts the extra space after this ":" In contrast to FLOW, PCCON manages to avoid adding an extra space after most common honorific abbreviations, e.g., ADM., AMB., CAPT., CHM., COL., CPL., CT., GEN., GOV., LT., SGT., MAJ., PFC., PRES., PROF., PVT., REP., REV., SEC., SEN., SGT., SUPT. However three abbreviatons are ambiguous: CT., DR., and ST., which all can be part of a street name as well as being an honorific. "Go to Whitebud Dr. Brown dogs live there." needs the space and PCCON provides it. "I know Dr. Brown has a practice in Raleigh." should not get an extra space and PCCON does not produce one. However, consider this unavoidable extra space situation: " Young Dr. Brown has a practice in Raleigh. The case of the first character of the word immediately before Dr. is the decision maker. Usually if it is uppercase, that word is part of the street name ending in Dr., but not always. - PCCON leaves the cursor inside the just-formatted paragraph, whereas FLOW always moves the cursor after that paragraph to prepare for formatting the next one. The FLOW cursor movement often causes the just FLOWed paragraph to be scrolled off the screen if that paragraph was near the bottom of the screen. I like to leave the cursor in place because I type, edit, format (flow), edit, type some more, format again, etc., on the same paragraph and don't like having to drag the cursor back to where I was typing every time I do a format with the FLOW command. I definitely don't like having to scroll to get the paragraph visible again so I can continue editing it. In contrast, PCCON takes care to keep the just PCCONed paragraph on the screen with the cursor placed in it near where the cursor was last located, allowing the editing of that paragraph to continue.
- Although most paragraphs are left-aligned in column 1, sometimes
you need to create paragraphs that have a different shape. For
example, the paragraph you are now reading uses a hanging indent.
Also, you might want to inset the whole paragraph a certain amount
from column 1 to provide emphasis or to align it with the indented
text of a previous hanging indent paragraph. The next paragraph is
an example.
With KEDIT's FLOW command, you must first specify the desired shape of a paragraph by using the SET MARGINS command. Whenever you go to a different shape, you must reissue SET MARGINS. With PCCON, specifying a paragraph shape is much easier to do; you do not need to calculate parameters and issue SET MARGINS. PCCON provides a facility to let it learn and remember the desired shape of a paragraph. The remembered PCCON settings are then used as defaults for other paragraphs until you tell PCCON to learn a new shape. PCCON also provides an easy way to create continuation and list paragraphs which align with a previously created hanging indent paragraph.
- If you have named lines in a paragraph using the SET POINT command and subsequently format the paragraph with the FLOW command, all the line names for that paragraph will be deleted. Instead, PCCON preserves line names. Any names for a particular named line will now be associated with the line that ends up containing the first word of the original named line in the paragraph before PCCON was invoked.
- In contrast to FLOW, PCCON does not support the settings of the KEDIT SET FORMAT command. PCCON always doublespaces at the end of a sentence and recognizes only blank lines as paragraph delimiters. Also, PCCON always formats paragraphs with a ragged instead of a justified right edge. Finally, PCCON does not have a target parameter; PCCON formats only a single paragraph which must be designated by the cursor. The PCCONALL macro can be used to format all the paragraphs in a file to the same shape.
- As previously noted, PCCON's use of positive and negative for hanging indents is exactly reversed from the use by the KEDIT SET MARGINS command.