Gordon McComb
Automation

Document Construction Kit

A Macro for Fast and Easy Document Assembly

In this document:

Looking for a way to automate the construction of standard documents like contracts, sales sheets, or customer letters, but don't want to spend lots of time and energy creating fancy macro or merge systems? The "Document Construction Kit" macro, explained here, might just be your ticket to document assembly nirvana. The macro is easy to use, and doesn't require any customization or editing.


The Concept of Document Construction Kit

The idea behind the Document Construction Kit is that all the prompts and content for creating an assembled document are provided in a main "boilerplate" file. The macro processes this file from start to finish, prompting you to specify the snips or paragraphs of text you wish to insert. You can insert a single word at a time, or entire paragraphs.

No special tools are required to create a boilerplate file for use with the Document Construction Kit. The prompts for inserting text, and the text you wish to insert, are both stored in the boilerplate file. This file can also contain "standard" text and formatting that you want to always appear in the output document.

Creating an Insertion Prompt

The first order of business is to create a prompt for inserting text at a specified spot in the document. This is done merely by placing the prompt where you want the inserted text to go, and enclosing the prompt in << and >> characters. These characters act as "gates" to surround the prompt text, which can be up to about 512 characters in length. This prompt text can include all printable characters and hard returns, but not other formatting codes like tabs.

Here is an example of text used as a prompt. Note the formatting (with hard returns created by pressing the Enter key), and the reminders of the paragraph names that can be selected here: "Para1," "Para2," or "Para3."

<<Type the name of the first paragraph you want to insert:
Para1
Para2
Para3>>

When you run the Document Construction Kit macro the prompt appears in a box, like this:

 

Creating Insertion Text

The Para1, Para2, and Para3 prompts refer to names of phrases (single words, sentences, paragraphs, etc.). These phrases are defined at the bottom of the document using selection bookmarks (we'll call these phrases "insertion text"). For this example, there are three phrases to choose from, each defined with selection bookmarks, at the end of the document.

Selection bookmarks are created by following these steps (assuming WordPerfect 8 or later):

  • Select the text you want to define as a phrase or paragraph.
  • Choose Tools, Bookmark.
  • Choose Create, and give the bookmark a name, such as Para1. Make sure the Selected Bookmark option is selected, so that a "selection" (as opposed to "single-point") bookmark is created.
  • Choose OK.

You may add as many bookmarked phrases as you wish, but put them all at the end of the document.

One final housekeeping chore: Place a single-point bookmark immediately preceding the first phrase, and call it Paragraphs. Here's how some bookmarked paragraphs might appear in your document, with Reveal Codes turned on.


Using the Document Construction Kit Macro

With the boilerplate document created (all the prompts and insertion text added) you're ready to use the Document Construction Kit macro. The macro, shown in Listing 1 at the end of this article, is also provided in ready-to-go .WCM file format here [constkit.wcm]. You may either copy the macro from Listing 1 (remember to save it as a macro by turning on the Macro Feature bar by choosing Tools, Macro, Macro Toolbar, and give it a .WCM extension), or download the constkit.wcm file. Place the constkit.wcm macro in your regular macros directory.

You may also download a sample boilerplate document here [constkit.wpd]. Use this document for testing purposes, and to experiment with various formats and prompts for use with the Document Construction Kit macro.

With the boilerplate document you wish to use on screen, run the Document Construction Kit macro by following these steps.

  • Choose Tools, Macro, Play (or press Alt+F10).
  • Type constkit, and press Enter.

At the prompt enter the bookmark name of whatever phrase you wish to insert (e.g., Para1 or Para 3). You can now see why it's a good idea to include the name(s) of the phrases you want to choose from in the text insertion prompt. Providing the names to use -- the names can be single characters or whole words -- makes it easier for others to use the system.

How to Avoid Overwriting Your Boilerplate Files

You'll probably want to use the Document Construction Kit macro on a copy of the boilerplate document you wish to use. That way you won't accidentally save the changes and wreck your original. One easy way of creating a copy of the boilerplate document is to use File Insert:

  • If the current document is not already blank, click the new Blank Document icon in WordPerfect's main toolbar
  • Choose Insert, File.
  • Enter the name of the boilerplate document you wish to use (or locate it in the dialog box).
  • Choose Insert.

You may wish to record a macro for the above steps so that you can quickly retrieve a boilerplate document. If you wish, you may add the following line at the end of the recorded macro to automatically run the Document Construction Kit macro:

Chain (?PathMacros + "constkit.wcm")

Note: Because the Document Construction Kit macro relies on bookmarks you cannot use WordPerfect's merge feature to insert the boilerplate text. When merging WordPerfect automatically strips all bookmarks from the original form document.

Feel free to create as many boilerplate documents as you wish. The constkit.wcm Document Construction Kit macro can be used on an unlimited number of boilerplate documents.

Listing 1 -- constkit.wcm

// constkit.wcm
// Document Construction Kit
// Gordon McComb, http://gmccomb.com/

//==============================================
PosDocVeryTop()
NotFound (Off!) 
SearchWordForms (No!)
SearchWrap (No!)
SearchFindWholeWordsOnly (No!)
Cancel (Off!)
Repeat 
	GetInput()
	If (?NotFound) 
		Break 
	Endif
Until (?NotFound)
OnError (NoParagraphsBookmark)
BookmarkFind ("Paragraphs")
OnError()
SelectMode (On!)
PosDocBottom ()
DeleteCharNext ()
Return

//==============================================
Label (GetInput)
OnError (BadDoc)
SelectMode (Off!)
MatchPositionBefore ()
SearchString ("<<") 
SearchNext (Regular!)
If (?NotFound) 
	Return 
EndIf
SearchString (">>") 
MatchExtendSelection () 
SearchNext (Regular!)
OnError ()
Test=?SelectedText 
EditCut()
SelectMode (Off!) 
Display (On!) 
Redisplay ()
Answer=""
GetString (Answer;SubStr (Test; 3; StrPos (Test; ">>")-3))
If (Answer=0) 
	Quit 
EndIf
Display (Off!) 
QuickmarkSet () 
Error (Off!)
BookmarkBlock (Answer) 
If (ErrorNumber=0)
	EditCopy ()
	SelectMode (Off!) 
	QuickmarkFind () 
	EditPaste ()
EndIf
Error (On!)
Return

//==============================================
Label (NoParagraphsBookmark)
MessageBox (; "Error"; "There is no 'Paragraphs' bookmark in this document. 
	This bookmark is required to define the start of the boilerplate text you 
	wish to insert."; IconStop!)
Quit

//==============================================
Label (BadDoc)
MessageBox (; "Error"; "There was an error attempting to process this document."; 
	IconStop!)
Quit