.figure 15
.center;DOC - TEMPLATE DOCUMENT GENERATION
.blank;.center;AUTHOR: W. KORENDYK
.blank;.center;TASK IDENT: 790510
.blank;.center;DOCUMENT VERSIONS
.blank;.center;ASDW\MK790511
.center;ASDDJK790706
.center;
.center;
.center;
.center;
.center;
.center;
.center;
.center;
.blank 6
This document written and supported locally by the staff of
the Atmospheric Sciences Division, Alberta Research Council.
.comment; Reset initial modes and argument values here.
.autoparagraph   ;.comment Paragraph if space/tab in column 1.
.flags capitalize;.comment Capitalize  words beginning with "<". 
.flags hyphenate ;.comment Unhyphenate words beginning with "=".
.period;.comment ; Enable period-2 spaces after period-separator.
.right margin 70
.page
.center;DOC - TEMPLATE DOCUMENT GENERATION
.title;TEMPLATE DOCUMENT GENERATION
.subtitle; 
.skip 2
.center;TABLE OF CONTENTS
.skip 3
.nofill
.tab stops 10,15,17,23,36
	1.0	OVERVIEW
.skip
	2.0	DOC COMMANDS
.blank 1
			2.1	@	indirect input file
			2.2	COMMENT	comment
			2.3	DEFINE	string definition
			2.4	GOTO	branching
			2.5	IF	conditional execution
			2.6	LABEL	label definition
			2.7	MARK	mark current output position
			2.8	PROMPT	terminal output
			2.9	QUERY	logical input
			2.10	SUBSTITUTE	string substitution
			2.11	TERMINAL	terminal input
.skip
	3.0	STRING CONSTANTS
.blank 1
			3.1	Predefined Constants
			3.2	Input Constant
.skip
	4.0	ERROR MESSAGES
.skip
	5.0	EXAMPLES
.blank 1
			5.1	UICDOC.SRC
			5.2	LIBBUG.SRC
.page

.fill
.hl 1 OVERVIEW
	DOC is a locally written RSX-11M CUSP (Commonly Used System Program) to
assist in the generation of documents, using templates to ensure
uniform appearance. Like
all CUSPs, DOC may be initiated in several ways. The common methods
are:
.list
.le
Single DOC command from MCR:
.skip
.indent 7;&>DOC command__string_<CR>
.skip
DOC will execute the command__string, and when complete, will 
return to MCR.
.le
Multiple DOC commands:
.skip
.indent 7;&>DOC_<CR>
.skip
after which an explicit DOC prompt is given:
.skip
.indent 7;^&DOC>\&
.skip
This prompt indicates that DOC is ready to accept a command string.
DOC will execute the command string and return with another DOC>
prompt.
.els
To leave DOC after using method#2 above, the user must enter an end-of-file
instead of a command string following the DOC prompt. This is done by typing
a CTRL/Z (depressing the CTRL and Z keys simultaneously). DOC
will terminate and return to MCR.
.break
The DOC command string is of the form:
.skip
.center;outfile[_=infile]
.skip
where 'outfile' and 'infile' are valid FILES-11 file specifications, 
with default values given in Table 1-1.
.skip 2
.test page 13
.center;Table 1-1
.center;File Specification Default Values
.skip
.nofill
.tab stops 8,18,21,39,42,65,66
.lm 5
-------------------------------------------------------------
|	element	|	#####infile	|	#######outfile	|	
|-----------------------------------------------------------|
|	device	|	SY0:	|	SY0:	|	
|	[UIC]	|	###########[current default UIC]	|	 
|	filename	|	DOC	|	no default	|	
|	filetype	|	SRC	|	RNO	|	
|	version	|	highest numbered	|	next-higher numbered	|	
-------------------------------------------------------------
.skip 1
.fill
.lm 0
The 'outfile' specifies the file to contain the generated document;
the 'infile' specifies the file
which is used as a template in generating the document.
	DOC reads lines from the input file and writes these
lines to the output file, with the exception of those lines which
begin with the character "$" in the first column. This control
character indicates that the line is a##'DOC command record'.

.test page 15
.hl 1 DOC COMMANDS
	Within a DOC command record, the character
string following the control character#($), up to the command
terminator#(space or tab), is taken to be a##
'DOC command'. The currently accepted DOC commands are given
in Table 2-1.
.skip 2
.test page 18
.nofill
.center;Table 2-1
.center;DOC Commands
.skip 
.lm 10
.ts 13,25,28,58
-------------------------------------------------
|	Command	|	##########Function	|	
|-----------------------------------------------|
|	@	|	indirect input file	|	
|	COMMENT	|	comment	|	
|	DEFINE	|	string definition	|	
|	GOTO	|	branching	|	
|	IF	|	conditional execution	|	
|	LABEL	|	label definition	|	
|	MARK	|	mark current output position	|	
|	PROMPT	|	terminal output	|	
|	QUERY	|	logical input	|	
|	SUBSTITUTE	|	string substitution	|	
|	TERMINAL	|	terminal input	|	
-------------------------------------------------
.skip 2
.fill
.lm 0
Commands may be abbreviated to a single character. For example,
the command records:
.skip
.indent 10;$PROMPT This line of prompt is output to the terminal.
.indent 10;$P This line of prompt is output to the terminal.
.skip
specify the same action to be performed. DOC recognizes both 
upper- and lower-case commands.
An unrecognized command is assumed to be a COMMEMT, and
causes the entire record to be ignored.
No error or warning message is given.
.blank
The remainder of this section
describes each of the DOC commands.

.tp 10
.hl 2 @ - indirect input file
	The at-sign character (@) indicates that
the text which immediately follows is the specification of the file to which DOC is to
go for further input records.
This indirect file then becomes the##'current input file', and when
the processing of that file is complete, DOC resumes processing
of the previous input file at the record following the Indirect Input File
command record.  The @ character may appear in the first position
in the record; if the command
character is in the first position, it will still be recognized as an Indirect
Input File command record.  Following are some examples of valid Indirect
Input File command records:
.skip 1
.indent 10;$@DM2:[111,2]LEVEL2.SRC
.indent 10;$@Level3
.indent 10;@NEWINPUT.DAT
.skip 1
The defaults for the indirect file specification are the
same as for 'infile'.
The Indirect Input File command accepts string variable substitutions
(see section 2.10).

.tp 10
.hl 2 COMMENT - comment
	Comments allow for the annotation of the input file.
The COMMENT command record neither causes any action by DOC
nor is it written to the output file.
.skip
.indent 10;$COMMENT We can comment our input file so that
.indent 10;$COMMENT if changes become necessary, it will
.indent 10;$C#######be easier to make the modifications.

.tp 10
.hl 2 DEFINE - string definition
	The string variable names 
must be a single alphanumeric character (A to Z, 0 to 9).
Thirty-six string variables may be defined, each
able to contain up to thirty-one characters.
.skip 1
.center;$DEFINE B character__string
.BLANK
The character__string can itself contain string variable 
substitutions#(see section 2.10).
Processing of this command record does not cause anything
to be output to the output file. 
.blank
A number of string variables
are pre-defined by DOC#(see section 2.3), but can be altered 
with the DEFINE command.

.tp 10
.hl 2 GOTO - branching
	The GOTO command causes the processing of the input 
file to resume at the record immediately
following label__name as defined by a LABEL command:
.skip 1
.center;$GOTO label__name
.skip 1
The label__name must be a single alphanumeric word less than sixteen characters in length.
The remainder of the command record is ignored.

.tp 10
.hl 2 IF - conditional execution
	This command allows for the conditional execution of an input file
record, dependent on the value of a logical variable.  The syntax for the 
command record is:
.skip 1
.center;$IF variable__name line__to__execute
.skip 1
If the value of variable__name
#(as defined by a previous Query command) is "true",
the line__to__execute is processed as though it were an input record;
thus the line__to__execute may itself be a DOC command record.  
If the value of variable__name
is "false", the remainder of the IF command record is ignored.
If variable__name
is undefined, it defaults to a value of "false".  Only the first
four characters of variable__name are recognized.
.skip 1

.tp 10
.hl 2 LABEL - label definition
	This command defines a "label" in the input file:
.skip 1
.center;$LABEL label__name
.skip 1
The label__name must be a single alphanumeric word less than sixteen characters in length.
The remainder of the command record is ignored.

.tp 15
.hl 2 MARK - mark current position in the output file
	This command is used in conjunction with the TERMINAL
command#(section 2.11).
The current position in the output file
is retained on an internal stack, and no other action is taken.
The maximum number of marked
positions retained on the stack is nine. An attempt
to exceed this limit causes the 'oldest' marked position to be lost.
The remainder of the command record is ignored.
.skip
.indent 10;$MARK and retain this position in the output file.

.tp 10
.hl 2 PROMPT - terminal output
	With the PROMPT command the part of the command
record following the command
terminator is output to the user terminal#(TI:),
not to the output file. This enables the DOC template file to
communicate with the user.
.skip
.indent 10;$PROMPT You will now be asked for the name and
.indent 10;$P######address of the person to whom the letter
.indent 10;$P######is to be sent.
.skip
The PROMPT command accepts string variable substitutions#(see section 2.10).

.tp 10
.hl 2 QUERY - logical input
	The QUERY command allows for the user specification of a
logical#(true/false) variable.  The command record is of the form:
.skip 1
.center;$QUERY variable__name [prompt__string]
.blank
Only the first four characters of variable__name are recognized.
The prompt__string is output to the terminal and a
answer is waited for.  If no prompt string is specified, the default prompt
string "[Y/N]?" is output.  The answer given defines the logical value of
variable__name. The valid answers are:
.skip 1
.nofill
.lm +20
Y (or y) _=> Yes (true)
_<ESC>### _=> Yes (true)
N (or n) _=> No  (false)
_<CR>#### _=> No  (false)
.fill
.lm 0
.blank
An invalid answer causes DOC to reprompt with prompt-string until a valid answer is
given.  A CTRL/Z response causes processing of the current input 
file to be terminated.
The QUERY command accepts string variable
substitutions in the prompt string (see section 2.8, 2.10).

.tp 10
.hl 2 SUBSTITUTE - string substitution
	This command must be used for all strings  written to the
output file which
contain a variable name which requires substitution.
String substitution may also be used in some other commands.
The string variable may have been
defined by the DEFINE command#(section 2.3) or already exist as a pre-defined
constant string#(section 3.0).  The variable substitution is indicated by
a percent sign (%) preceding the single-character variable name. 
For example, if the variable W contains:
.skip 1
.center;WEDNESDAY
.skip 1
and the command record is:
.skip 1
.center;$SUBSTITUTE Today is %W
.skip 1
the following record will be written to the output file:
.skip 1
.center;Today is WEDNESDAY
.skip 1
It is also possible to specify portions of the string by using the following
construct:
.skip 1
.center;%A(n,m)
.skip 1
where 1 _=_<n _=_<m _=_<31.  If n is not specified, n_=1 is assumed; if m is not
specified, m_=31 is assumed.
To access the second and third character use:
.skip 1
.center;%A(2,3)
.skip 1
If neither n nor m are specified, the parentheses need not be given, and the
entire string will be assumed.
	A string variable may contain less than 31 characters;
for example, the string variable "W" above only contains nine characters
(WEDNESDAY).  In that case, the remainder of the string is filled with
null characters which are not sent to the output file.
Therefore,
.skip 1
.center;%W(1,22)#=#"WEDNESDAY"
.center;%W(7,8)##=#"DA"
.center;%W(11,16)=#""
.skip 1
	Any number of string variable substitutions may be used in a
single SUBSTITUTE command record, as long as the resulting output record is
less than 512 characters in length. For example, using the predefined
string constants (section 3.0):
.skip
.indent 10;$SUBSTITUTE It is now %T(1,5), %W, %N %D, %Y.
.skip
causes the following to be written to the output file:
.skip
.center;It is now 12:24, WEDNESDAY, MAY 16, 1979.
.skip
If the character following the percent sign is not a valid string variable
name (A to Z, 0 to 9, ?), the percent sign and the
character are included in the output record.

.tp 10
.hl 2 TERMINAL - terminal input
	Following this command, lines are copied from the
terminal to the output file.
The remainder of the command record is ignored.
Input from the terminal continues until an end-of-file#(CTRL/Z)
is typed. Lines read from the terminal are not interpreted
as DOC command records, but are immediately written to the output 
file. If there is no input prior to the
end-of-file, the output file is rewound to the last marked 
position#(see section 2.7).
Note that the most recently marked position is always removed by a TERMINAL
command. The remainder of the record following the command character is ignored.
.skip 1
.indent 10;$TERMINAL input will now be accepted at the terminal.

.tp 20
.hl 1 String Constants
.hl 2 Predefined Constants
	When an output file is opened, a number of the string
variables (see sections 2.3, 2.10) are set to contain certain
values:
.skip
.lm +10
.nofill
%T = time of day ("HH:MM:SS.S")
%D = numeric day of month ("16")
%M = numeric month of year ("5")
%Y = numeric year ("1979")
%W = alphabetic day of week ("WEDNESDAY")
%N = alphabetic month of year ("MAY")
%I = program IDENT ("790510")
%O = operating system ("RSX-11M V3.1")
%V = program version ("DOC 790207 (V5.0)")
.lm -10
.fill
.skip
All alphabetic strings are expressed in upper case.
These constants may be redefined using the DEFINE command
(section 2.3).

.tp 15
.hl 2 Input Pseudo-constant
	In addition to the above predefined strings, DOC recognizes
a special string constant: "?". This constant is replaced wih
input read from the terminal. For example:
.skip
.center;$SUBSTITUTE The person at the terminal typed: %?
.skip
will accept input from the terminal and replace the "%?" with the
first 31 characters of the
line that was typed, and write that entire record
to the output file. It is also possible to specify substrings of what
was entered, using the same construct as for string substitutions
(section 2.10). For example, if the command record were:
.skip
.center;$DEFINE A Your name is: %?(2,5)
.skip
and if "Eugene" is typed at the terminal, the string variable A
would contain:
.skip
.center;Your name is: ugen
.skip
	Although the predefined constants can be
redefined using the =DEFINE command (section 2.3), it
is not possible to redefine the input pseudo-constant.

.tp 25
.hl 1 ERROR RECOVERY
	The errors that can result from the normal use of DOC are listed
below with a brief description of what they represent, and what, if anything,
should be done to recover.
.skip 1
.left margin +10
.tp 6
.indent -10
DOC -- OUTPUT FILE SPECIFICATION ERROR
.skip 1
No output filename was specified in the command string. Re-enter command
line specifying output file.
.skip 1
.tp 6
.indent -10
DOC -- *** WARNING ***
.indent -10
MAX LEVEL OF MARK EMBEDDING REACHED
.indent -10
OLDEST MARK DELETED
.skip 1
Maximum level of embedded marks has been exceeded.  At present the maximum
level of embedded marks allowed is nine. If this error occurs
the oldest mark is deleted.
.skip 1
.tp 6
.indent -10
DOC -- *** WARNING ***
.indent -10
MAX LEVEL OF INDIRECTION EXCEEDED
.indent -10
RECORD IN ERROR:##"XXXXXXXXXXX"
.indent -10
FURTHER LEVELS IGNORED
.skip 1
An attempt was made to access an indirect input file that was too deeply
nested.  At present four levels of indirection are allowed.
.skip 1
.tp 6
.indent -10
DOC -- LABEL: "XXXXXX" NOT FOUND
.skip 1
An attempt was made to branch to a label which does not exist
within the current input file. If this
error occurs during the processing of an indirect file, that file is closed,
and processing continues with the file from which it was initiated.
.skip 1
.tp 6
.indent -10
DOC -- LABEL: "XXXXXX" AMBIGUOUS
.skip 1
An attempt was made to branch to a label which has been multiply 
defined within the current input file. If this
error occurs during the processing of an indirect file, that file is closed,
and processing continues with the file from which it was initiated.
.skip 1
.tp 6
.indent -10
DOC -- INVALID STRING VARIABLE SPECIFIED
.indent -10
RECORD IN ERROR: "XXXX"
.skip 1
An attempt was made to define an invalid string variable. Presently the
valid string variables are A to Z and 0 to 9.
.skip 1
.tp 6
.indent -10
DOC -- INVALID PARAMETERS OR DELIMITERS
.indent -10
RECORD IN ERROR: "XXXX"
.skip 1
An invalid parameter or delimiter has been encountered while trying to
perform a string substitution. This may occur because an invalid character
has been encountered or because one or both of the numbers was outside of the
range 1 - 31.
.left margin -10

.skip 5
.tp 10
.hl 1 Examples
	The following are two examples of a DOC template file.
Each is designed to assist in the generation of a RUNOFF input
file for a standard EARLUG Library document. The first is used
to generate the standard software package description associated
with each product from the EARLUG Library. The second is used
to generate a bug report for submission to the Library.

.page
.nofill
.hl 2 UICDOC.SRC
_$c This DOC source file is provided to help generate consistent forms
_$c for use by the Edmonton Area RSX-11 Local Users Group (EARLUG).
_$c This form describes the software product which is to be included
_$c into the EARLUG Library, generating a file: UICDOC.RNO which
_$c conforms to the standards set by the EARLUG Library.
_$c 
_.right margin 70
_.page
_.center;EARLUG Library
_.center;Software Packagae Documentation
_$string .center;_\_\_^%w, _^%n %d, %y_^_^
_$prompt The purpose of this is to generate a file UICDOC.RNO which
_$prompt conforms to the standard se up by the EARLUG Library. The
_$p	file generated is to be included with the files of the
_$p	software package. All input is assumed to be in mixed
_$p	upper and lower case; no conversions are made.
_$p
_$p	All library submissions should be sent to:
_$p
_$p	John Clark
_$p	Department of Energy Management
_$p	420A General Services Building
_$p	University of Alberta
_$p	Edmonton, Alberta
_$p	T6G 1B4
_$p
_$p	Ph: (403) 432-2249
_$p
_$query short Do you wish short comments? [Y/N] 
_.skip 3
_Software Package Identification:
_.skip
_$if short $goto 100
_$prompt	You will now be asked for the name of the Software
_$p	Package, the IDENT (of the main module) of the Package,
_$p	and the operating system(s) under which the package
_$p	will function.
_$p
_$label 100
_.left margin +10
_.tab stops 20
_$prompt Name?
_$define p %?
_.index %p
_$string .br;Name:	%p
_$p	IDENT?
_$s	.br;IDENT:	%?
_$s	.br;EARLUG UIC:(will be assigned by the EARLUG Library)
_$p	Operating System?
_$s	.br;Operating System: %?
_.left margin -10
_.skip 2
_Software Package Description:
_$prompt	Please enter a brief description of the software package.
_$p	Terminate input with a CTRL-Z.
_.left margin +5
_.paragraph
_$terminal input
_.left margin -5
_.skip 2
_Required Files:
_$if short $goto 120
_$prompt	The EARLUG distribution standard a minimum of
_$p	three files. The names of those files (or more) are
_$p	specified here so that it is easier to determine if
_$p	an installation has all necessary files for the
_$p	software package.
_$p	Terminate input with a CTRL-Z.
_$label 120
_$prompt	Please list all the required files.
_.nofill
_.left margin +10
_.skip
_$terminal input
_.fill
_.left margin -10
_.left margin +5
_$mark this position
_.skip 2
_.indent -5;Special Hardware Requirements:
_$if short $goto 130
_$prompt	Certain software packages may require hardware which
_$p	may not be available on some systems. These special
_$p	requirements should be specified.
_$label 130
_$prompt	Please indicate all special hardware requirements (eg. 124K
_$p	memory, FPP, EIS, tape drive, 1000. blocks disk space, etc.)
_$p	Terminate input with a CTRL-Z.
_.paragraph
_$terminal input
_$mark this position
_.skip 2
_.indent -5;Limitations and Restrictions (including known bugs):
_$prompt	Please enter all limitations and restrictions of the software
_$p	package, including all known bugs.
_$p	Terminate input with a CTRL-Z.
_.paragraph
_$terminal input
_.left margin -5
_.skip 1
_$prompt Please enter the date of the last modification made
_$p	to the software package.
_$string Last modification made: %?
_.skip
_.nofill
_.left margin +20
_.indent -20;Submitter's name:	#
_$prompt Enter the name and address of the submitter as it should appear
_$p	on an address label.
_$p	Terminate input with a CTRL-Z.
_$terminal input
_.skip
_$prompt	Phone number? (include area code)
_$string Ph: %?
_$mark this position
_.skip
_.indent -20;Author's name (if different than submitter):
_.break
_$prompt Enter the name and address of the author (if different from
_$p	the submitter) as it should appear on an address label.
_$p	Terminate input with a CTRL-Z.
_$terminal input
_.fill
_.skip
_.indent -20;Reviewer's name:	#
_The name and address of the EARLUG reviewer will be
_placed here, and a copy of this form will be returned
_to the submitter.
_.left margin -20

.page
.hl 2 LIBBUG.SRC
_$c This DOC source file is provided to help generate consistent forms
_$c for use by the Edmonton Area RSX-11 Local Users Group (EARLUG).
_$c This form is used to report bugs that were encountered while
_$c using a program received from EARLUG.
_$c 
_.right margin 70
_.page
_.center;EARLUG Library
_.center;Software Bug Report
_$string .center;_\_\_^%w, _^%n %d, %y_^_^
_$prompt The purpose of this is to generate a file LIBBUG.RNO which
_$prompt describes a bug that was encountered in the usage of a EARLUG
_$prompt package.
_$p	
_$p	Please submit all bug reports to:
_$p
_$p	John Clark
_$p	Department of Energy Management
_$p	420A General Services Building
_$p	University of Alberta
_$p	Edmonton, Alberta
_$p	T6G 1B4
_$p
_$p	Ph: (403) 432-2249
_$p	
_$p	
_$p	All input is assumed to be in mixed
_$p	upper and lower case; no conversions are made.
_$p
_.nofill
_.left margin +20
_.skip 3
_.indent -20
_Submitted by:
_$p	Enter the name and adress of the submitter as it should appear
_$p	on an adress label.  Please terminate input with a _^Z.
_$p	
_$terminal input
_.skip
_$p Phone number? (include area code)
_$s Ph: %?
_.fill
_.justify
_.left margin 10
_.skip 2
_.indent -10
_Software Package Description:
_.skip
_$p	You will now be asked for the name of the Software Package,
_$p	the IDENT (of the main module) of the Package, and the
_$p	EARLUG UIC.
_$p	
_.tab stops 20
_$p Name?
_$s	.br;Name:	%?
_$p IDENT?
_$s	.br;IDENT:	%?
_$p EARLUG UIC?
_$s	.br;UIC:	%?
_.skip 2
_.indent -10
_CPU and relevant peripherals used:
_$p  Please enter a brief description of the CPU and other
_$p relevant peripherals used.
_$p Terminate input with a _^Z.
_$p	
_.paragraph
_$terminal input
_.skip 2
_$p Operating system and Version?
_.indent -10
_$s Operating system and Version:  %?
_.skip 2
_$p Now enter the bug description (and its reoccurance, if any)
_$p Terminate input with a _^Z.
_$p   
_.indent -10
_Bug description (including repeatability, if any):
_.paragraph
_$terminal input
_.skip 2
_$mark this position
_.skip 2
_.indent -10
_Suggested Solution:
_$p Please enter your suggestions for the solution of this problem.
_$p Input should be terminated with a _^Z. If you have no solutions
_$p merely enter a _^Z
_.paragraph
_$terminal input
_$mark this position
_.skip 2
_.indent -10
_Other comments on this program:
_.paragraph
_$p Enter any other comments you might have about this program.
_$p Terminate input with a _^Z.  If you don't have any comments
_$p just enter a _^Z.
_$p   
_$terminal input
_$mark this position
_.skip 2
_.indent -10
_Enhancements you think would be nice:
_.paragraph
_$p Enter any suggestions you have for the enhancement of the program,
_$p terminated by a _^Z. If you have no suggestions merely enter a
_$p _^Z.
_$p   
_$terminal input