This section leads you through an example of a source file-consisting of long help text only-that can be processed by the Help Utility to generate a help book.
The Help Utility gives you a great deal of flexibility in the structure and composition of a source file. Although this example does not cover every allowable construct, it can help familiarize you with the commands and the correct way to use them.
The first step is to make a file. If you make your file of type TEXT, you can be certain the record length of your file is compatible with the Help Utility. In the Command and Edit (CANOE) message control system (MCS) you can make a new TEXT file by entering the following:
MAKE <source file title> TEXT
For example, you could enter MAKE SAMPLE/SOURCE/FlLE TEXT. From there, you would proceed to writing your help text and correctly entering the embedded commands in the text. You can create the file in CANOE or in the A Series Editor, if the Editor utility is available to you.
If you were to use the Help Utility to process the sample file, the section numbers, section titles, and structural relationships that result would be those indicated in the following outline:
1 Introduction
2 An Example of a Related Topic 2.1 Subtopics
2.2 Another Subtopic
2.2.1 A Level 3 Section
3 A Few Words about Formatting 4 The Last Section
Keep in mind that the section numbers appear along with the section title only in structured help books. The section numbers are shown here as examples of the way section numbers are tied to help book structure when the ORGANIZATION STRUCTURED option is in effect. The section titles are indented to reflect the structural relationships of the corresponding sections of text.
Sample Source File
Everything that appears between the two horizontal lines in Example 4-1 is included in the source file. If you would like to, you can enter the lines of the file exactly as they appear in Example 4-1. When you run the Help Utility on the resulting CANDE or Editor file, you create a help book.
.BOOK FILETITLE A/SAMPLE/BOOK .LANGUAGE ENGLISH
.ORGANIZATION STRUCTURED
• AUTONUMBER
.SECTION 1 "Introduction"
.KEYWORD Introduction *Getting Started*
The first thing to note is that each command begins with a period (.) in the leftmost position (column 1) of the line. Remember the command rules: all commands must begin with a period (.) in the leftmost position (column 1) of the line, only one command can appear on each line, and at least one blank space must come between the command itself and any command items that follow it.
In this sample source file, blank lines appear before and after each set of commands. Putting blank lines in like this is entirely optional. It is done here for the purpose of making the commands stand out more. If blank lines appear in your source file, they will also appear when your help text is displayed.
This sample file begins with the commands .BOOK FILETITLE A/SAMPLE/BOOK and .LANGUAGE ENGLISH, so when the Help Utility is run on this source file, the help book created will be titled
BOOK/A/SAMPLE/BOOK/ENGLISH
The LANGUAGE command is unnecessary in this example, because anytime the LANGUAGE command does not appear in a source file, the Help Utility automatically assigns ENGLISH as the language of the help book.
The third command, .ORGANIZATION STRUCTURED, means that in the help book, the parent topic, related topic, and subtopic relationships will exist among sections of text.
The fourth command, . AUTONUMBER, puts automatic numbering of sections into effect. That way, the Help Utility will number sections for you at the level you indicate in the SECTION command.
Example 4-1. Sample Source File (cont.)
Sample Source File
The first SECTION command in this example is .SECTION 1 Introduction. Because the AUTONUMBER command is in effect, the 1 in the SECTION command is a level number, not a section number.
When the Help Utility is run on this source file, this section of text will have the section number 1 assigned to it. Remember that section numbers serve only as a means of defining the structural relationships among sections of text when the ORGANIZATION option is STRUCTURED.
This section will have the keywords Introduction and Getting Started associated with it. What this means is that a user can employ the keyword Introduction or the keyword Getting Started to call up this section of text. Either keyword can be entered in any mixture of uppercase and lowercase letters, as long as the keyword is correctly spelled .
. SECTION 1 "An Example of a Related Topic"
.KEYWORD related *parent of 2.1 & 2.2*
This section of text will have the section number 2 assigned to it. The first section, Introduction, and this section, An Example of a Related Topic, are related topics. They are both numbered at level 1 .
. SECTION 2 "Subtopics"
.KEYWORD *level 2 section* subtopic1
The level number in the SECTION command for this section makes it a subtopic of the previous section, An Example of a Related Topic. This section will have the number 2.1 assigned to it .
. SECTION 2 "Another Subtopic"
.KEYWORD *another level 2 section* subtopic2
The section number 2.2 will be assigned to this section of text. This section is also a subtopic of An Example of a Related Topic. It is a related topic of Subtopics .
. SECTION 3 "A Level 3 Section"
.KEYWORD *level 3 section* *section 2.2.1*
The section number 2.2.1 will be assigned to this section. It is a subtopic of Another Subtopic. This section has no related topics, because there are no other sections with the same parent. From here the sample file goes on to another subject, and section numbering moves up to level 1 to indicate this change.
Example 4-1. Sample Source File (cont.)
Samp'le Source File
.SECTION 1 "A Few Words about Formatting"
.KEYWORD formatting
The section number assigned by the Help Utility to this section will be 3. The subject of this section is the formatting of your help book.
Remember that the format of your help book is precisely the format of the source file you used to create the help book. This means that if you enter text in your source file
like this, it will come out looking like this when it
is displayed for the user.
So you want to be careful about the way you type the help text in your source file.
If you have the Editor Utility available to you, then you may want to use the Editor PARAGRAPH command when you are writing your source file. The PARAGRAPH command lets you set the left and right margins and, if you like, right-justify your text. (This means the right end of each line terminates in the same
column, as do the lines in this manual.)
For complete descriptions of text-formatting commands available in the Editor, refer to the information on the PARAGRAPH command, the SHIFT command, and the ENTER command in the A Series Editor Operations Guide .
. SECTION 1 liThe Last Section"
.KEYWORD end
The section number 4 will be assigned to this section. It marks the end of the sample source file. The next step after a source file is created is to process that source file with the Help Utility. Directions for 'processing a source file with the utility are given in Section 5, "Running the Help Utility."
Example 4-1. Sample Source File