What the Macro Will Do
The aim is to write a macro that extracts the main keyword from each section of the help file and writes the results to a new file.
To see what we mean by a "keyword", look at the following section from the help file:
=======================================================
^AUTO_NEW_SCREEN
AUTO_NEW_SCREEN function
---->(AUTO_NEW_SCREEN)---->+------>(ON)----->+---->
| |
`------>(OFF)---->'
The AUTO_NEW_SCREEN function allows you to select ...
.
.
=======================================================
In this example, the section describes the AUTO_NEW_SCREEN function. The keyword is AUTO_NEW_SCREEN, and that's the string we want to write to the output file.
Note that you can search for the keyword in one of two ways:
• Look for a ^character, then take the string after the ^. Or,
• Look for the string command or function. Then take the preceding string.
From a programming point of view, the first method is better. The processor only has to examine a file in a "forwards" direction. Using the second method, the processor has to look "forwards" until it finds command or function, and then look "backwards" to find the preceding string. Let's use the first method.
Now, look at the next example:
=======================================================
^CANCEL ESC STOP INTERRUPT BREAK
^ABORT
^Meview_cancel
CANCEL command
---->(CANCEL)---->
CANCEL cancels the current activity ...
.
.
=======================================================
In this example, ^CANCEL, ^ABORT, and ^Meview_cancel are all preceded by ^, but we only want to include CANCEL in our output file. We don't want to include ABORT or Meview_cancel because these strings refer to other sections of the help file. So, our macro must tell the processor to extract the first string that is preceded by ^ in each section, and ignore the others.
Before discussing our text-handling macro, there is one other point to make. One of the things that our macro must do is search for blanks in lines. In the previous example, ^CANCEL is separated from the next string, ESC, by a blank. We sometimes use blanks to let us know that we are at the end of strings. Now look again at this section from the help file:
=======================================================
^AUTO_NEW_SCREEN
AUTO_NEW_SCREEN function
---->(AUTO_NEW_SCREEN)---->+------>(ON)----->+---->
| |
`------>(OFF)---->'
The AUTO_NEW_SCREEN function allows you to select ...
.
.
=======================================================
The first line of the section is ^AUTO_NEW_SCREEN. It is important to realize that when this line is printed on the screen, the line is padded with blanks. But in the file there are no blanks in this line. Immediately after the final N of AUTO_NEW_SCREEN there is a linefeed character, which is not printed on the screen but appears in the file. The linefeed character has a hexadecimal ASCII value of 0A. If "\n" represents the linefeed character ("\n" is used in the C programming language) then the previous example looks like:
^AUTO_NEW_SCREEN\nAUTO_NEW_SCREEN function\n\n ... (and so on)
Note that "\n" is two characters, but the actual linefeed character is only a single character.