This subsection describes conventions for creating a text source file for hard-copy documentation. Guidelines for producing on-line HELP files from the same files are discussed in a later subsection.
CE62-00 Creating Text Source Files 7-5
Line Length
In general, it is advisable to keep line Length to a maximum of 79 characters.
In unformatted copy-- such as figures, unformatted tables, or matrix tables--line length must not exceed the page width. Length restrictions are stated in
"Usage Notes" in the discussion of the macros for tabLes and figures.
HELP files must not include lines of greater than 79 characters. This can be accomplished by entering text according to the guidelines stated above and by limiting :HLP macro lines to 79 characters. In generating a HELP file, a warning is issued for records exceeding 79 characters. NOTE: Overstriking counts as two characters (backspace, and the overstrike character), and should be avoided in text that is to appear in HELP files.
Blocking
STEXT assumes that text is blocked. That means that all paragraphs start on the left margin. Lists do too, unless they are lists within lists.
Indentation of list text is accomplished by use of the TEXT control words .INL and .UNL.
Spacing
STEXT produces single spaced output. Macros for headings, tables, and figures cause appropriate spacing: between headings and text, between tables and text, and between figures and text.
The user enters the TEXT control word .SPB between paragraphs. In certain cases, where a blank line is needed but a page break is undesirable, the TEXT control word .SPF can be used. For example, .SPF should be entered in these cases: after a line ending in a colon that introduces a list of items on separate lines, between lines in a table where a page break is inappropriate, and between lines in syntax formats.
Section and Subsection Headings
Documentation files are hierarchically structured. In addition to the section heading, four levels of headings are permitted. Headings created through macros are distinguished typographically (by upper- and lower-case and by underscoring) and by appropriate spacing. STEXT also attaches specific meaning to the heading levels for hard-copy and HELP.
When outlining a new manual, both the hard-copy heads and on-line HELP topics should be considered. For example, all commands of a given processor may appear as level 2 headings with level 4 headings (such as "Format:",
"Parameters:", etc.) subordinate to each command heading; the command names become topics, and "Format", "Parameters", etc. become subtopics for each command. The following discussion of level head macros illustrates this point.
Note: In CP-6 user documentation, the order of level 4 heads for command (and similar) documentation is as follows: Format, Parameters, Description,
Example. This order of presentation produces the most usable HELP facility.
CE62-00 Section and Subsection Headings 7-6
Level 0 Head Macro
Format:
•• :lOH "section name"
Parameters:
section name is the 1-49 character section name.
Description:
This macro creates and formats the section name, and creates an entry in the table of contents (if it is requested at document assembly).
Example:
•• :lOH "User Documentation/HELP"
creates the section name for this section.
Level 1-3 Head Macro
Format:
•• :l{11213}H "[headname][i][{xlhelp_topics [synonym list]}]"
Parameters:
headname is the heading name. headname can be up to 58 characters for level 1, 55 for level 2, and 52 for level 3.
help_topic is the 1-31 character HELP topic name, if other than headname.
help topic must be specified even if the same as headname if a synonym list follows. help topics must not include blanksi for example, lEVEL 1 could be the topic associated with the heading "level 1-3 Head Macro".
-synonym list is a list of 1-31 character synonyms for the HELP topic.
Synonyms must not contain blanks.
Description:
This macro creates and formats the level head, and creates an entry in the table of contents and index, if they are requested at document assembly. The macro also creates a HELP topic unless X is specified.
Example:
•• :l2H "COPY CommandiCOPY C CO COP"
creates COpy Command as a hard-copy heading, COpy as a HELP topic, and C, CO, and COP as HELP synonyms.
CE62-00 level 1-3 Head Macro 7-7
Level 4 Head Macro
Format:
•• :L4H "[headname][;{Xlhelp_subtop;c [synonym list]}]"
Parameters:
headname is the head contents of up to 255 characters.
heLp subtopic is the 1-31 character HELP subtopic name, if other than
headname. heLp subtopic must be specified, even if the same as head name, if a synonym List foLLows. heLp_subtopic names must not incLude bLanks.
synonym List is a List of 1-31 character synonyms for the HELP subtopic.
Synonyms must not incLude bLanks.
Description:
This macro creates and formats the leveL 4 head (or tabLe entry, if the LeveL 4 head faLLs between •• :MAT and •• :END macros). If X is not specified, the macro creates a HELP subtopic, provided the preceding higher LeveL head is a HELP topic. (LeveL 4 headings do not appear in the tabLe of contents.)
$TEXT transforms LeveL 4 headnames, entered in metaLanguage used to described syntax, into useabLe HELP subtopics. These transformations are described Later in this section.
ExampLe:
•• :L4H "ExampLe:"
creates a hard-copy heading and generates the HELP subtopic EXAMPLE.
Usage Notes:
1. If headname exceeds Line width in the output produced, headname is formatted on muLtipLe Lines just as any other text, with Line breaks at bLank characters.
CE62-QQ LeveL 4 Head Macro 7-8
Syntax Formats
Two kinds of syntax formats are used:
• COBOL-oriented syntax formats, used in COBOL, I-D-S/1I and FPl documents.
• General syntax formats, used in all other documents.
Figure 7-1 is an example of a COBOL-oriented syntax format.
OBJECT-COMPUTER [HIS-SERIES-60] lEVEl-66-ASCII
[ {WORDS }]
[, MEMORY SIZE integer {CHARACTERS}]
[ {MODULES }]
[ [ [
[, PROGRAM COllATING SEQUENCE IS
[ [ [ [
{alphabet-name}]
{STANDARD-1 }]
{NATIVE }]
{ASCII }]
{EBCDIC }]
{GBC D }]
{HBCD }]
{JIS }]
Figure 7-1. COBOL-oriented Syntax Format
Notice the brace or bracket on each line of a group, and the alignment of the braces and brackets that enclose the group.
Figure 7-2 is an example of a general syntax format as it appears in a user document. Note that the OR bar is preferred to the vertical stacking of options.
Syntax:
PASSWORD {OlD=oldpassword[,NEW=newpassword]INEW=newpassword}
Figure 7-2. General Syntax Format in a User Document
CE62-00 Syntax Formats 7-9
Tables
TabLes of seven lines or more are appropriate to be formatted as named tables.
All named tables are created through the use of macros.
The table macro allows rapid entry of table text. The following list explains the three table types and when each is useful.
• Matrix - tables consisting of rows and columns. Up to 8 columns of data are permitted. Each row of text is entered as one line, with the #
character as a column separator. Figure 7-3 shows a sample matrix table.
• Formatted 2-column - tables consisting of a table item in the left column and formatted text in the right column. Each item in the first column, entered as a level 4 head, occupies a separate line in the table. Text explaining each item starts on a following line (allowing a wide second column instead of one aligned beyond the longest item in the left column;
this usually results in more compact tables>. Each table item and
accompanying text can be an individually selectable HELP subtopic. Figure 7-4 shows a sample formatted 2-column table.
• Unformatted - tables consisting of text in unformatted mode, i.e., the TEXT control word .FIF followed by text entered exactly as it is to appear in the output. Figure 7-5 shows a sample unformatted table.
Table A-1. ASCII Character Codes
Graphic Octal Decimal Hexadec. Definition
NULL 0'000' 0'000' X'OO' NULL of time fill character SOH 0' 001 ' 0' 001' X' 01 ' Start Of Heading
STX 0'002' 0'002' X'02' Start of Text
ETX 0'003' 0'003' X'03' End of Text
EOT 0'004' 0'004' X'04' End of Transmission
· ·
·
Figure 7-3. Matrix Table
C!62-0G Taeles 7-10
Table 1-2. Set Options Option Meaning
ACCESS=«{ALLlaccountlist})[,controllistJ)
ALL is the control list is to apply to all other accounts.
ACSVEH=(vehiclelist)[,controllistJ)
vehiclelist processors that are to be given access permissions.
controllist one of the following permissions:
DELRECORD
Figure 7-4. Formatted 2-Column Table
•• :MAT "Table 13-1. DELTA .FIF
.spf 2
Directives"
HOUSEKEEPING IEXECUTION ICONTROL
IEXECUTION IMEMORY DISPLAY IMODE IMISC.
Input/Output Control:
COpy
•• : EN D
CE62-QQ
ITRACING 1& MODIFICATION ICONTROLI Procedure
I
I HISTORY*Breakpoint:1 PLUGH*
1 TRACE*
AT* ,
Variable Oriented Directives:
ANLZ RUM
Figure 7-5. Source for Unformatted Table
Tables
END*
HELP*
LIST PROTECT
7-11
Purpose of :MAT Macro
Table macros perform the following functions:
• Insert and center the table title, including blank line spacing.
• Automatically create running titles for continuation pages.
• Provide standard blank line spacing to separate the table from preceding and following text.
• Make logical page breaks.
In addition, these functions are performed for matrix and formatted 2-column tables:
• Insert and position column headings, including blank line spacing.
• Automatically create running headings for continuation pages.
• Perform all the positioning for the columns.
Before the table macros terminate, they always perform an .FIN, an .ALL and an .INL 0 so that the file builder is "reinitialized".
All named tables included in a text source file are delimited by :MAT and :END macro calls as follows:
.~:MAT "detail"
table text
•• : EN D
:MAT Macro
Format:
•• :MAT "title[;col head1[;[#Jn;col head2J ••• J"
Parameters:
title is the 1-61 character table title.
col head1 is the column heading for the first column.
[#In;col head2 specifies the position and column heading for the second column. If # is specified, n is relative to the end of the last column
heading. If # is omitted, n is the absolute column position for the heading.
For example, 35iDescription causes the head to be placed in column 35.
#5iDescription causes the head to be placed 5 positions after the previous column heading. Matrix tables may consist of up to 8 columns; formatted 2-column tables must have only 2 column heads specified.
Description:
This macro labels and lays out a table consisting of the following text (up to the •• :END macro). It also includes the table name in the list of tables and figures in the table of contents (if a table of contents is requested).
CE62-00 :MAT Macro 7-12
Example:
•• :MAT "Table A-1. ASCII Character Codes;Graphic;1I5;Octal;1I6;
Decimal;1I7;Hexadec.;1I7;Definition"
is the macro used to create the matrix table in Figure 7-3. The first line of source text in that table is entered in the source file as follows:
NULLIIQ'QQQ'IID'QQQ'IIX'QQ'IINULL of time fill character
Following is the macro used to create the 2-column formatted table in Figure 7-4:
•• :MAT "Table 1-2. Set Options;Option;15;Meaning"
The first lines of source text in that table are entered in the source file as follows:
•• :L4H "ACCESS=«{ALLlaccountList})[controLList])"
ALLAAAAis the controL List that is to appLy to aLL other accounts •
•• :L4H "ACSVEH=(vehicLelist)[,controLList])"
vehicLeListAAAAprocessors that are to be given access permission •
• spb Q
controlListAAAAone of the foLLowing permissions:
.spf Q
DELRECORD
Note that the text between Level 4 heads is indented (as requested in the :MAT macro) and formatted.
Usage Notes:
1. For matrix tables, text is Left-justfied within the coLumns unless blanks are explicitLy entered (by use of the up-arrow character>. Adjacent pound signs are entered if a field in the matrix is to be left blank.
2. For unformatted tables, no column headings are specified in the :MAT macro. Any column headings must be included with the table text.
3. For matrix tables, the coLumn headings and text (excluding II characters) cannot exceed 76 per line. For unformatted tabLes, each line of table text is limited to 76 characters.
CE62-QQ :MAT Macro 7-13
Figures
Source text fiLes shouLd contain aLL artwork, not bLank space for hand-drawn diagrams. (If desired, better quality artwork can overlay the artwork stored
in the fiLe if camera-ready master copies are being created.)
All figures included in a source text file are delimited by the :FIG and :FND macro calls formatted as follows:
•• :FIG "fig info"
figure
text-•• : F NO
:FIG Macro
Format:
•• :FIG "title[in]"
Parameters:
title is the 1-61 character figure title.
n is the estimated number of lines in the actual figure. If n is not specified, STEXT assumes the figure belongs on a single page.
Description:
This macro labels and Lays out a figure consisting of the foLLowing text (up to the •• :FND macro). It also includes the figure name in the list of tables and figures in the tabLe of contents (if the table of contents is requested).
STEXT uses the following ruLes to determine figure layout:
1. If there is enough room on the current page, the figure is printed.
2. If there is not enough room on the current page, and the figure is less than a single page in length, a break to the next page occurs and the figure is printed.
3. If the figure is longer than a single page, the figure will begin printing on the current page, and all subsequent pages of the figure are printed with a figure titLe at the bottom of each page.
Example:
•• :FIG "Figure 7-3. Matrix Tablei12"
created Figure 7-3 in this section.
Usage Notes:
1. The figure content must be kept within 78 character positions, starting at character position 1.
2. Areas in a figure can be forced to appear together by placing a .BRN above the area to be kept together. For exampLe:
.BRN 10
CE62-00 :FIG Macro 7-14
means the next 10 Lines must appear on the same page. Using an .SPF 0 is expanded symboLs. It is also recommended that consistency be maintained
within sections and, if possibLe, within a document.
Merge
AuxiLiary operation
Punched card
---OnLine storage
Direct arrows
Communications arrows
CE62-00
/ /
, ,
,
,---/
(
\
or
<--+-->
,
v
, . ,
/,
/\
( )
\ /
, .--->
.----+----'
<---- ' , . ,
/, ,
v
/ /\
( ( )
\
- - - -
\ /Figure 7-6. Figure Symbols
Figure Symbols 7-17
Index Entries
There is no Indexes are created on request as part of document assembLy.
Limit to the number of items that can be incLuded in an index.
a manuaL consists of:
The index for
• Automatic entries - aLL LeveL 1, 2, and 3 heads contained in the document f i l e.
• Specified entries - entries selected by the user by entering the :IDX macro.
:IDX Macro
Format:
•• :IDX "term[;subterm)"
Parameters:
term is the term to be entered into the index.
subterm specifies that subterm is to appear in the index subordinate to term.
Description:
This macro creates an index entry. STEXT, on request, produces an
aLphabetized, coLLated index. Upper and Lowercase are considered identical;
the first occurrence of a term wiLL determine how an entry appears in the index. Thus, "ASDF" and "asdf" wiLL be sorted together as "ASDF". SimiLarLy
"abcd" and "ABCD" wilL be sorted together as "abcd".
Plurals and suffixes of a term are not combined with the originaL term. Thus
"Process" and "Processing" do not coLLate together.
ExampLe:
•• :IDX "BUILD Command"
•• :IDX "BUILD Command;EDIT"
•• :IDX "BUILD Command;IBEX"
creates a 2-level index, which could appear as follows for the terms shown above:
BUILD Command - 2-10 EDIT - 3-18
IBEX - 4-20 Usage Notes:
1. The :IDX macro must follow the paragraph to which it refers.
2. When a 2-level index is created by use of subterms, the term should be defined on one :IDX macro without subterms (as shown in the example).
CE62-00 :IDX Macro 7-18
Ending a Section
All source text files must end with the following sequence:
•• :HLP ".BRP"
•• :L1H ";X"
.*
This is the only time that the user is permitted to include a .BRP in a source text file.