7 February 1989

                             BALCOL (Version 1.01)
              A WordPerfect 5.0 Macro to Produce Two-Column Text
                             with Balanced Columns

                  Rufus S. Hendon (CompuServe ID 73250,2674)


                                 Introduction

     WordPerfect 5.0 has good facilities for formatting text in two columns.
(It is also possible to use three or more columns, but I will talk only about
the case of two columns.)  One feature that is lacking, however, is a simple
way to equalize the lengths of the columns on the last or only page containing
a section of two-column text to allow room for subsequent single-column text on
the same page.  If, on the last page used, there is not enough text to fill a
column, WordPerfect puts all the text in the left column and permits single-
column text to follow on the same page, but there is an unsightly blank space
in the right column.  If there is more text than will fit in the left column,
WordPerfect fills that column to the end of the page and then puts the
remainder of the text in the right column, leaving the rest of that column
blank; single-column text is forced to the next page.

     The preferable treatment, of course, is for the two-column text to be
formatted, on the last or only page of such text, with the two columns
balanced, i.e. with approximately the same number of lines in both columns, in
order to avoid the presence of blank areas on the page and to allow single-
column text to follow on the same page.  It is possible to achieve this effect
manually (I will describe the procedure later), but the process is tedious.

     A friend recently wanted to prepare camera-ready copy of her dissertation
for publication, with the body of the text formatted in dual columns.  I was
helping her with the details, and decided to see if I could devise a macro that
would, to some extent, at least, automate the process of producing two-column
text with balanced columns.  The macro that resulted is described in this memo.
The macro, called BALCOL, is stored in two files named BALCOL.WPM and
BALCOL1.WPM.  You invoke BALCOL from WordPerfect; BALCOL in turn calls upon
BALCOL1 to perform certain tasks.  Both files must be present in the directory
where WordPerfect looks for macros.

     This is an early version of BALCOL (version 1.01).  It does its job
properly on the documents I have used to test it, and hence I would expect it
to work for you also, as long as the documents you apply it to are formatted in
the way to be described.  In developing BALCOL, however, I discovered that
there are many things that can go wrong with a macro this complicated.  It is
therefore quite possible that on certain occasions BALCOL will give unexpected
results or will trash a part of your document.  For this reason you should take
seriously the suggestions for backup procedures given below.  You use BALCOL at
your own risk.

     One reason why I am distributing this early version of the macro is the
hope that some of the macro wizards who participate in the WPSG Forum will be
interested in taking a look at it.  Any suggestions for correcting errors they
spot, making the behavior of the macro more stable, and improving its operation
will be very welcome.  I am therefore making available a more technical
discussion of the macro in a separate memo (BCTECH.TXT).


                    General description of what BALCOL does

     BALCOL is intended for use with documents that consist of sections of text
to be formatted in double columns separated by sections of text to be formatted
in a single column.  The full-width sections interrupting the two-column
sections might, for example, be headings that you want to extend across both
columns, tables too wide to fit in one of the two columns, and the like.  This
memo is an example of such a document, if we assume that the centered headings
such as "General description of what BALCOL does" are to be printed extending
across both columns while the paragraphs of text are to be printed in dual
columns.

     BALCOL allows you to bracket a section of text which it then formats in
double columns, beginning at the current position on the page and using as many
pages as are required to hold the text.  On the last or only page occupied by
the two-column text, the text is divided as evenly as possible between the two
columns.  If the two columns don't take up the entire page, the following piece
of full-width text will begin on the same page, below the two columns.  In most
cases, BALCOL preserves the number of blank lines that originally separated the
double-column section from the full-width section.  There are occasional
lapses, however, that require manual correction, usually the deletion of an
extra blank line.  Other sporadic formatting failures may likewise have to be
repaired by hand.

     On each of the pages occupied by two-column text, BALCOL checks to see if
there are blank lines at the tops of the columns.  If this is the case, it
gives you the opportunity to delete them.


                      The expected format of the document

     BALCOL was designed to operate on documents formatted in this manner:

     (1) The document includes, prior to the first section to be formatted in
double columns, a column definition specifying the type as newspaper, the
number of columns as 2, and whatever column separation or margins you want to
use.  This is essential:  BALCOL won't work if there is no column definition in
effect.  If you use tabs to indent paragraphs that are to be printed in two
columns, you would also want to set tab stops on the basis of the column
definition so that a tab will give the same amount of indentation regardless of
whether the paragraph ends up in the left column or the right column.  Suppose,
for example, that your document has 1" left and right margins and you have set
the distance between columns to 0.25" in the column definition.  WordPerfect
will tell you, when you define the columns, that the left column begins 1" and
the right column 4.37" from the left edge of the paper.  To indent paragraphs
0.25" (which will look better than the usual 0.5"), you would have to have tab
stops set at 1.25" and 4.62".

     (2) Every section to be printed in two columns is separated from the
following full-width section by at least one blank line.  Applying BALCOL to a
document that fails to satisfy this requirement will introduce errors in the
paragraphing of the subsequent text.

     (3) Blank lines are produced simply by pressing Enter (Return), and hence
consist solely of a Hard Return, without preceding spaces or tabs.  Blank lines
that violate this requirement may cause minor errors in the operation of
BALCOL, since they will not be recognized as blank lines.

     BALCOL will not work on text containing embedded graphics.


                               How to use BALCOL

     In a long document containing many separate sections to be given two-
column format, you will be using BALCOL frequently.  You might therefore find
it convenient to change the name of the file BALCOL.WPM, at least temporarily,
to ALTB.WPM, so that you can use the Alt-B key to invoke the macro.  If you do
this, don't alter the name of BALCOL1.WPM.

     Two-column formatting must be applied to units that are isolated from
other parts of the document by obligatory page breaks.  For short documents,
the entire document may constitute such a unit, in which case the formatting
must be applied to the document as a whole.  In other cases, the document may
be subdivided into parts, such as chapters, that are independent of each other
in the sense that each part is forced to begin on a new page.  Each of these
parts can then be converted to dual-column format separately.  For the sake of
convenience, I will henceforth use the term "document" to refer to the contents
of the file to which dual-column formatting is to be applied; this may be an
entire document (in the more general sense) or an independent unit of a
document of the sort just described.

     The conversion of a document to two-column format should be deferred until
you are absolutely certain that it is in final form as far as content and all
formatting other than the conversion to two columns are concerned.  Until you
reach this point, put the column definition at the beginning of the file but
keep all text in single-column form.  The reason for this is that once the
switch has been made to two columns the document has assumed a frozen state in
which it is no longer easy to make modifications (such as the addition or
deletion of text or a change in the typeface or point size to be used for
printing) that would alter the quantity of text or the way text wraps from one
line to the next.

     When you are ready to do the two-column formatting, make a copy of the
file containing the document.  Let's call the file containing the finished
document in its one-column form "file 1".  The copy is "file 2"; this is the
file to which BALCOL will be applied.  If file 2 gets messed up in the process,
the original text of the document will still be available in file 1.  Also, if,
despite your belief that the text of the document is in its final form, it
later appears that changes have to be made, you will still have a single-column
version of the text in file 1 on which to make the alterations; you can then
make a new file 2 from the modified version of file 1 and redo the two-column
formatting.

     I also strongly recommend that, as you work through file 2 with BALCOL,
you save the current version of file 2 in another file, "file 3", after each
successful conversion of a section of text to double-column format.  Having
this continually updated backup of your work will save you a lot of effort if,
at some point, the conversion of the next section to be processed messes up the
text, either because BALCOL misbehaves or because of some error on your part.
If you have faithfully kept the backup in file 3 current after the conversion
of each section, you can restore the status of file 2 just before the faulty
conversion by retrieving file 3.  You can then retry BALCOL on the section
where things went bad previously or, if you feel that BALCOL was at fault, you
can format and balance this particular section by hand, using the procedure to
be described later.

     If you get through successfully to the end of the file, file 3 and file 2
(after you save it) will be identical, and one of the two can be discarded.

     Two-column formatting must be done on sections in order, working from the
beginning of the text to the end.  If this memo were the document, for
instance, the first section to be processed would consist of the paragraphs
coming between the heading "Introduction" and the heading "General description
of what BALCOL does", if we assume that headings are to be printed as full-
width items stretching across both columns.  Reformatting would then be applied
to the next section, which consists of the paragraphs between the heading
"General description of what BALCOL does" and the heading "The expected format
of the document".  Conversion to dual-column format would continue in this way,
section by section, until the end of the document was reached.

     Here are the steps to follow (it is assumed that BALCOL.WPM has been
renamed to ALTB.WPM, so that BALCOL can be invoked by pressing Alt-B):

     (1) Copy the file to be converted to two-column format, file 1, into a new
file, file 2.

     (2) Start WordPerfect and retrieve file 2.

     (3) Move the cursor to the first line of the next section of text to be
converted to two-column format.  (The first time, this will be the first such
section in the text.  Thereafter it will be the next section in order.)  It
doesn't matter where the cursor is in the line.  (If this memo were the
document, you would, for the first section, put the cursor somewhere in the
first line of the first paragraph, which begins "WordPerfect 5.0 has good
facilities".)

     (4) Press Alt-B.  A small rectangle will appear before the first word in
the line and this message will be shown at the bottom of the screen:

        Move cursor to last line of two-column text, then press Enter.

     (5) Move the cursor to the last line of the section of text to be
reformatted.  (This is the last line of text in the last paragraph in the
section, not the blank line that follows the last paragraph.)  It doesn't
matter just where the cursor is in the last line.  When you have positioned the
cursor, note (for use in step 7) the number of blank lines between this line
and the following full-width item.  Then press Enter (Return).  (For the first
section of this memo, you would put the cursor somewhere in the line
"discussion of the macro in a separate memo (BCTECH.TXT)." and press Enter.)  A
small rectangle will materialize at the end of the line.

     (6) Wait!  BALCOL starts chugging away, and various intermediate forms of
the text of the section will appear on the screen.  If BALCOL discovers that
there are blank lines at the tops of columns, it will, for each case, beep and
ask if you want to delete the line.

     (7) When BALCOL has finished processing the section, the end of the
section, with balanced columns, will be displayed, and the status line at the
bottom of the screen will revert to its usual state, showing the name of the
file you are working on.  Examine the reformatted section carefully, to see if
any manual corrections to what BALCOL has done are needed.  If the section
extends over several pages, page back to the beginning of the section and then
scan it page by page.  Particularly if the text is justified, you will find it
helpful to use the View feature on the Print (Shift-F7) key, since the View
display will reveal any deviations from correct justification.

     (8) If everything looks okay, press Save (F10) to save the current state
of the document in the running backup file, file 3.  (The first time you do
this, WordPerfect will ask you for the name of the file, suggesting the name of
the file you are working on, file 2.  Change this to a different name, for file
3.  Thereafter WordPerfect will suggest the name of file 3; press Enter to
accept this name and then type "y" to authorize WordPerfect to replace the
previous contents of file 3.)  If there is another section to be processed, go
back to step 3.  Otherwise exit from WordPerfect, saving file 2 (make sure to
specify the name of file 2 rather than the name of file 3 when WordPerfect asks
for the name of the file to be saved).  At this point file 2 and file 3 are
identical so one of them can be deleted.

     (9) If, however, you notice formatting mistakes, they must be fixed before
you can proceed to subsequent sections.  Make the necessary corrections and
then go to step 8.

     Errors requiring hand correction are normally confined to the last or only
page occupied by the section.  The commonest mistake is the introduction of an
extra blank line, which must be removed by hand.  BALCOL usually keeps the
number of blank lines separating the end of the two-column section from the
following full-width item the same.  Occasionally, however, it introduces an
extra line, so that, for instance, three blank lines appear where originally
there were only two.  If this is the case, turn Reveal Codes (Alt-F3 or F11)
on, move the cursor to a [HRt] code in the vicinity of the [Col Off] code
between the end of the two-column section and the full-width item, and press
Delete.  Then turn Reveal Codes off.  (It is essential to have Reveal Codes on
when you do this, so that you can avoid deleting the wrong code.  When the
cursor is resting on a blank line, it may be on some code other than [HRt].  If
you don't have Reveal Codes on, you may see the cursor on a blank line and
press Delete, thinking that this will remove the blank line; but if in fact the
cursor is not on a [HRt] code, the results of pressing Delete may be quite
unexpected.)

     The error just described is easy to fix.  There may be occasions, however,
when BALCOL has fouled things up so badly that the only course is to start over
again on this particular section and perform the conversion to dual-column
format with balanced columns by hand.  When this is the case, use Exit (F7),
"n", "n" to get rid of the current, now defective version of file 2 on which
you've been working and then use Retrieve (Shift-F10) to load the backup from
file 3. This restores the document used by WordPerfect to the state it had
before you tried to reformat the section that caused BALCOL to misbehave.
Convert this section using the manual procedure described below.  Then go to
step 8.


           The manual procedure for converting to two-column format
                             with balanced columns

     If you have to process a section of text by hand, this is what to do:

     (1) Move the cursor to the first line of the section and use Home, Home,
Left Arrow to put it at the beginning of the line.  Then press Math/Columns
(Alt-F7), Column On/Off (3) to turn column formatting on.  This inserts a [Col
On] code, and puts the entire document from this point on into dual columns.

     (2) Move the cursor to the last line of the section.  If the last line is
in the right column, use Goto (Ctrl-Home), Right Arrow to switch from the left
column to the right column.  Press End to put the cursor at the end of the
line.  Then press Math/Columns (Alt-F7), Column On/Off (3) to turn column
formatting off.  This inserts a [Col Off] code and returns everything in the
document subsequent to this point to single-column format.

     (3) If the section spans more than one page, go back to the page on which
it starts.  Examine the non-final pages in sequence, checking the two columns,
first the left and then the right, for unwanted blank lines at the top of the
column.  If you find such a line, delete it.

     (4) Go to the last or only page occupied by the section.  If there is a
superfluous blank line at the top of the left column, delete it.  Don't do
anything to the right column at this point.

     (5) Count the number of lines of two-column text on this final page.  Let
n = the number of lines divided by 2, rounded up to the next higher integer if
the result is not an integer.  For example, if there are 46 lines, n = 23; if
thee are 47 lines, n = 24.

     (6) Go to the top of the left column on the final page and move the cursor
down to the nth line of the column.  Move the cursor down to the beginning of
the next line and press Ctrl-Enter to insert Hard Page at that point (between
line n and line n+1).  You will see all the lines after line n move from the
left column to the top of the right column, making the lengths of the two
columns approximately equal.

     (7) If justification is in effect and line n is not the last line of a
paragraph (and hence must be justified when printed), turn Reveal Codes (Alt-F3
or F11) on.  You will see that line n ends with a either a [SRt] (Soft Return)
code or a [HPg] (Hard Page) code; in the former case, there will be a [HPg]
code by itself on the next line.  Position the cursor so that the code at the
end of line n, [SRt] or [HPg], is highlighted.  If the highlighted code is not
preceded by a space, press Spacebar to insert one.  Then type one or more Hard
Spaces (Home, Spacebar).  Each Hard Space will be shown as [ ] in the Reveal
Codes display.  As long as the series of Hard Spaces is shown ahead of the
highlighted code, type another.  Eventually you will see the string of Hard
Spaces drop down to a new line in the Reveal Codes display, followed by [HPg];
the preceding line (line n) will have [SRt] at the end.

     Let's look at a specific example.  Suppose that after step 6 the last line
of the left column on the last page occupied by the section of dual-column text
is this:

        improving its operation.  I am

This is not the end of the paragraph, which continues at the top of the right
column.  Reveal Codes shows this:

        improving its operation.  I am[SRt]
        [HPg]

This makes the line look, to WordPerfect, like the end of a paragraph, since
the [HPg], which like [HRt] causes a break in justification, takes precedence
over the [SRt].  Consequently WordPerfect won't justify the line when it is
printed.  Move the cursor to highlight the [SRt].  Since this isn't preceded by
a space, press Spacebar to insert one.  Then type Hard Spaces (Home, Spacebar)
until a new line is created (don't be bothered if at some point the [SRt]
disappears and is replaced by the [HPg], which moves up to this line).  Let's
say that it takes nine Hard Spaces to accomplish this.  The Reveal Codes
display now looks like this:

        improving its operation.  I am[SRt]
        [ ][ ][ ][ ][ ][ ][ ][ ][ ][HPg]

The line beginning with "improving" no longer looks like a paragraph-final line
to WordPerfect, and so it will be printed with justification.  There is now an
extra line in the left column, but since the word it contains is composed
entirely of Hard Spaces it will look like a blank line when printed.

     (8) Look at the top of the right column on the last or only page occupied
by this two-column section.  If there is an unwanted blank line at the top of
the column, delete it.

     (9) Go to the bottom of the right column and turn Reveal Codes on.  If
there is a [HPg] code immediately preceding or following the [Col Off] code,
delete it.

     (10) Examine the transition from the dual-column text to the following
full-width item (heading or the like).  If the number of blank lines preceding
the full-width item is greater than it originally was, turn the Reveal Codes
display on (if it isn't already on) and delete as many [HRt] codes preceding
the full-width item as necessary to reduce the number of blank lines to the
original value.  Delete only [HRt] codes found on a line in which the [HRt] is
all by itself or is accompanied only by codes that don't generate text.  (Extra
blank lines appear for two reasons.  The first is that WordPerfect tends to
insert a [HRt] along with [Col Off].  The second reason is that the strategem
to force justification of the last line of the left column described in step 7
introduces an additional, apparently blank line.  Deleting [Hrt] codes removes
blank lines to compensate for these introduced lines.)