.; INITIAL MACRO FOR USER'S GUIDES .MAC BEGIN TITLE ^^ .TI #################%1 .PS 66,105 .NORMAL .RMARG .TSET .NORMSP .NJ .FI .NU 0 THIS PAGE IS BLANK .PE .E .; .; LABEL MACROS .; There are three label macros which must be used together. .; The reason for having three is that it is hard to put all .; the label information on one macro call line. .; LAB1 prints the job title, LAB2 prints the subtitle, and .; LAB3 prints the author, date, RCB number and SP number. They .; should be used together, in order, at the start of the table .; of contents page. .; TI is the title, which must be 57 letters. .; ST " " subtitle, " " " 57 " .; NAM is the author's name; 14 letters. .; DAT is the date; 10 letters. .; RCB is the RCB number; 4 digits. .; SP is the SP number; 2 characters (use 1# for SP-1) .; NP is the number of pages in the document; 2 characters .MAC LAB1 TI .SP 1 .FO 5 .NF .NJ .RI 130 .LE 42 # # )BQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;W )B:)C%1)B: )B: : ! .E .; .MAC LAB2 ST .SP 1 .FO 1 .NF .NJ .RI 130 .LE 42 )B:%1: ! .E .; .MAC LAB3 NAM;DAT;RCB;SP;NP .SP 1 .FO 9 .NF .NJ .RI 130 .LE 42 )B!,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,7,,,,,,7,,,,,7,,,,,,," )B: DR'N#%1DATE#%2 .BLDG. .CODE . CLASS : )B!,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,/,,,,,,/,,,,,/,,,,,,," )B: APP'D DATE . 600 . . E : )B!,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,/,,,,,,8,,,,,8,,,,,,," )B: ATOMIC ENERGY OF CANADA .  A-RCB-%3-SP-%4#: )B:  LIMITED .  : )B: CHALK RIVER ONTARIO CANADA  .REV. SHEET 1 OF %5: )BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;$;;;;;;;;;;;;;;;;;;;;S ! .RMARG .NORMAL .E .; .;MODE-SETTING MACROS .; .; These must be adjusted for changes to margins, etc. .; .; Long for normal pages .MAC LONG .PS 60 .RMARG .E .; .; Normal margin .MAC NORMAL .LE 17 .E .; .; Narrow column -- this leaves only 64 columns for typing. .MAC NARROW .LE 25 .E .; .; Normal spacing .MAC NORMSP .SP 1 .E .; .; Normal right margin .MAC RMARG .RI 88 .E .; .; Open right margin for tables .MAC OPEN .RI 104 .E .; .; Standard tab settings -- modified to allow for 2-space .; shift. This ensures same appearence on screen and on .; output. .MAC TSET .TA 17 23 31 39 47 55 63 71 79 87 .E .; .; Fudge tabs for IN -5 with tab broken from text .MAC TFU .TA 17 24 31 .E .; .; LOCAL MACROS .; .; New subsection macro -- equivalent to .PA 0 .MAC SECT TEST .SK 2 .TE %1 .IN 0 .E .; .; New paragraph macro .MAC NP .SK 1 .TE 5 .IN 8 .E .; .; Start of example .MAC SEG CHECK .SK 1 .TE %1 .NF .NARROW .OPEN .E .; .; Print example line at margin -- only for NARROW .MAC EDGE .IN -8 .E .; .; End of example .MAC EEG .NORMAL .RMARG .FI .SK 1 .E .; .; Table entry. N is --, or [n] for numbered list. .MAC TAB N .SK 1 .TE 4 .NARROW .TFU .IN -5 %1 .E .; .; End of table .MAC ENDTAB .NORMAL .TSET .SK 1 .E .BEGIN A-RCB-0065-SP-7###########EXTRAC USER'S GUIDE .LAB1 ###################EXTRAC USER'S GUIDE################### .LAB3 P.D.#McMorran#;#77-12-1##;0065;7#;4# .SECT 8 PURPOSE .NP EXTRAC is an MCR command file which extracts a brief user's guide from the comments of a source program. .SECT 8 METHOD OF USE .NP Comments to be extracted are bracketted by ;++ and ;-- in the program text (where ';' is the appropriate comment flag). EXTRAC will drop the first two characters of each line extracted (unless the second character is a tab) and will place the line in a file. .NP EXTRAC makes extensive use of the indirect MCR facility [1] of RSX-11D V6.2, and it is called with the MCR command @EXTRAC. It begins by listing a part of the user's directory and asking if the extraction program is present. It then creates the command file RNO.CMD, which is used to RUNOFF and HPP the output files, and it creates a file of standard RUNOFF macros. Finally, if the user indicated that the extraction program was not available, it is created. .NP When all is prepared, EXTRAC asks for the file to be processed. This will normally be a program source file, and the name given must include the file type (.FTN, .RAT, or .MAC). If the file is not found, a FORTRAN error message is printed, with a prompt for a new name. The comments between ;++ and ;-- are then combined with the macro file in a file with the same name as the program, but with the type .GDE (for GUIDE). EXTRAC finishes by using RNO.CMD, to print the resulting file. .NP After the file is printed, EXTRAC prompts for another file. Type to exit. To print the file again, the RNO command file may be used directly. It prompts for the name, and then uses RNO and HPP to print it. .SECT 8 RUNOFF MACROS .NP The macros provided by EXTRAC permit the generation of good-looking output with a minimum of clutter in the source file. Used as described, they yield margins of 1 inch top and bottom, 1.5 inches left and 1.25 inches right. They provide a label on the first page and they include features to facilitate the creation of tables and examples. The macros are defined in the following list. .SEG 40 .NORMAL MACRO DESCRIPTION .BEGIN TITLE Initializes the margins and sets the page heading to TITLE. TITLE should not contain leading blanks. .LAB1 TI TI is the first line of the title on the label (57 letters). .LAB2 ST ST is the second line of the title (57 letters). LAB2 is optional. .LAB3 NAM;DAT;RCB;SP;NP Completes the label by adding: NAM -- author's name -- 14 letters DAT -- date -- 10 letters RCB -- RCB number -- 4 digits SP -- SP number -- 2 digits NP -- number of pages -- 2 digits Any of these fixed-length fields may be padded with _# to obtain the specified length. .LONG Sets the normal paper size. LONG should be used on the second page to ensure that the label appears at the bottom of page 1. .NP New paragraph -- includes a test. .SECT TEST Section -- leaves a space, tests for TEST lines. .SEG TEST Start of example -- leaves a space, tests for TEST lines and switches to NOFILL with narrow margins. .EDGE Used during an example to print at the margin. .EEG End of example -- restores to normal. .TAB N Table entry -- sets narrow margin, but prints N with .IN -5. N may be [n], n._#, or --, for references, numbered lists, or plain lists. .ENDTAB Returns to normal after a table. .EEG .LONG .SEG 6 .EDGE The last two lines extracted from the source file should be .PE BLANK PAGE AT END .EEG .SEG 25 .EDGE For example, a typical FORTRAN program may contain SUBROUTINE FRED C++ C .BEGIN A-RCB-9999-SP-1 USER'S GUIDE FOR FRED C .LAB1 THIS IS A 57-LETTER TITLE TO SHOW THAT IT IS EXACTLY 57 C .LAB3 P.D._#McMorran_#;_#77-01-01_#;9999;1_#;3_# C .SECT 8 C PURPOSE C .NP C Text describing this program. C . C . C . C .LONG (once we are on page 2 -- this must be C found empirically) C . C . C . C .PE C BLANK PAGE C-- Program END .EEG .SECT 8 TECHNICAL DETAILS .TAB -- EXTRAC creates several temporary files named X. These are all deleted at exit. .TAB -- The program which performs the extraction does not actually check for comments. It is controlled by lines containing only 3 characters, ending in + or -. Column 2 is ignored for compatibility with LWRCMT [3] which puts a '.' in column 2 of comments which it has processed. .TAB -- Lines of 3 characters or more are extracted beginning with column 3, or with the first tab, if it precedes column 3. Shorter lines are replaced by a single blank. .TAB -- Typing _^Z in response to the error prompt from the program causes it to exit and causes the command processor to terminate with an error. .TAB -- The file EXTRAC.CMD [2] itself contains an extensive example of the use of the above macros since this document was produced by EXTRAC. .TAB -- Note that omitting a ;-- may cause an entire program to be extracted. The solution is obvious. .ENDTAB .SECT 10 REFERENCES .TAB [1] "Indirect MCR User's Guide". CRNL Reactor Control Branch Engineering Document A-RCB-0065-SP-8, December 1977. .TAB [2] "EXTRAC -- User's Guide Generator". CRNL Reactor Control Branch Engineering Document A-RCB-0077-SL-1, December 1977. .TAB [3] "LWRCMT -- Lower Case Comment Conversion Program." CRNL Reactor Control Branch Engineering File RCB-0152. .ENDTAB .PE BLANK PAGE AT END