% VAX-11 Librarian V04-00`n:@sn:&5 EXTRACTOR@sn:1 EXTRACTOR # $EXTRACTOR/qualifiers filenameK This program will scan a code file looking for properly delimitedB blocks of documentation. An example of "proper delimiters" is C+ ROUTINE_NAME/ C embedded formatting flags, and text C- H To run the extractor, define the following symbol (or one like it):+ extract :== $RDCS$EXE:EXTRACTOR  and then type, extract /q ualifiers file-spec K as per directions in write-up. The EXTRACTOR will produce up to fourK types of output. One contains LaTeX formatting commands and can beK processed and then printed on a laser printer. Another contains DSRK commands with level numbers in position so that it can be included inK a help library after processing. A third will also contain DSRK commands, but will not list the level numbers. It is designed forK  printout on a generic or "vanilla" printer. The fourth output optionK is designed for backward compatibility with existing programs whichK contain the +/- block extracting flags, but no embedded formattingK flags. In this case, the extractor will extract the delimited block,K optionally remove the comment delimiters at the beginning of eachK line, and just print the text as is to a file, without any formatting.K Please note that, unless the option is selected to produce only theK PLAIN file (the last desribed above), it is considered an error if theK file does not have embedded formatting flags. Command Line Parameter and Qualifiers:K filename Specifies what file(s) the EXTRACTOR is to work on. If aK file extension is omitted, or is .LIS, the file is assumedK to contain a list of filenames on which the EXTRACTOR is toK operate. Otherwise, the extension m ust be one of the3 recognized set, currently including: .C  .COM  .FOR  .FTN  .H  .MAC  .MAR  .PAS  .Z8K  .Z80  .68K K If filename is omitted entirely the program will create a K temporary file containing the directory listing of theK current default directory, and process any files with% recognized extensions.K /ALPHABETIZE (or /NOALPHABETIZE) Specifies whether separateK extractable blocks which the extractor finds are to beK ordered alphabetically or left in the order they were found.+ /ALPHABETIZE is the default.K /EMBEDDED (or /NOEMBEDDED) If /EMBEDDED is selected, the file isK assumed to have embedded formatting commands. It will beK considered an error if none are found. /NOEMBEDDED may onlyK be selected with PLAIN, HELP, EPIC, or CLIB processingK options; it may not be selected with LATEX, RUNOFF, or anyK combination which includes these. /EMBEDDED is the default;? however, selecting /NOREMOVE forces /NOEMBEDDED .K /LOG (or /NOLOG) This option selects whether information aboutK what headers were processed and what errors were found, etc.K should be saved to file EXTRACTED.LOG. Default is to LOG everything.K /QUIET (or /NOQUIET - DEFAULT) This option selects whetherK information about what headers were processed and whatK errors were found should be printed to the terminal. The(  default is to print them.K /REMOVE (or /NOREMOVE) If /REMOVE is selected, the comment markersK at the start of each line of the header (where appropriate)K are removed from the output text. /NOREMOVE may only beK selected with PLAIN or EPIC processing options; it may notK be selected with LATEX, RUNOFF, HELP, or any combinationK which includes these. /REMOVE is the default if nothing i s selected.K /LEVEL=n Specifies level of documentation blocks to be extracted.K This refers to the number or space which comes after the +K sign in the block delimiters which flag the beginning of a3 new block. Acceptable choices for n:K n where n is between 1 and 9. Space is; interpretted the same as a 1.K n-m n,m both between  1 and 9, inclusive. Example" 3-5.K nTOm n,m both between 1 and 9, inclusive. Example# 3TO5.B (n,m..) List of integers enclosed in parens.K ALL All blocks, which means 1 through 9 and/ includes "space".K /OUTPUT=filename Specifies the file to be written if only oneK type of output file is selec ted. If more than one type ofK output is to be produced (see PROCESSING) this fileK extension is ignored, and default file extensions are used. They are:B filename.HLP help file output, if NOEMBEDDEDK filename.HLPRNO help file output which must be& RUNOFFed5 filename.RNO runoff-able output4 filename.TEX LaTeX-able outp ut/ filename.TXT plain outputK /PROCESSING Specifies what type of output files are to be produced,K and what type of processing must be done on embedded8 commands. Valid options are /PROCESSING=:K PLAIN Documentation block is written as is to a= file, once extracted from code.K RUNOFF Substitutes runoff commands for emmeddedK  formatting commands. Output (file.RNO) must: be RUNOFFed before printing.K HELP Substitutes runoff commands for any embeddedK commands present. Inserts help level numbersK where needed. Output (file.HLP) may need toK be RUNOFFed if embedded commands wereK present. (Embedded commands should be pres ent9 in all newly written code.)K LATEX Substitutes LaTeX commands for embeddedK formatting commands. Output must be LATEXedK before printing (to a laser printer).' (DEFAULT): YES Same as (RUNOFF,HELP,LATEX).@ ALL Same as (RUNOFF,HELP,LATEX,PLAIN).3 CLIB Same as (PLAIN,HELP)., EPIC Same as PLAIN.K A list of options may also be specified within parens, as* /PROCESSING=(LATEX,RUNOFF).K /HELPLEVEL=n Specifies the level number to be output in the helpK text file. Valid only if processing option HELP is selected.K INTERNALLY: Embedded formatting flags recognized by this routine are as follows:K \subnam Signals that the next single word is the: subroutine or function name.K \subcal The text which follows is the normal calling8 sequence for the function.K \subtxt Signals the end of the '\subcal' phrase andK the start of the descriptive text about the5 subroutine or function.K \arglist Begins the list of argument descriptions.G Must be included before any '\argn' flag.K \argn Signals that the next single word is theK argument name. Following the argument name isG the descriptive text about that argument.K \intlist Signals a list 'internal' to the argumentK names. Suggested usage is for listingK possible error returns. Internal lists mayA not be nested as currently defined.K \intn The next single word is the keyword for theK internal list item. Text for the list item2 follows the keyword.K \intlend Required syntax to signify the end of an5 internal list of items.K \arglend Required syntax to signify  the end of an5 internal list of items.E \literal Prints following line exactly as typed.K \literal Prints following lines exactly as typed.K Intended for diagramming. No text may beK included on this line. Diagrams should startK in the first column after any commentK delimiters. (Asterisks in Pascal or C areK assumed to be comments in column 1 or 2.)K Diagrams should be no more than 70 columnsK wide, not counting comment characters. WithinK an arglist width may be 60, and within an* intlist, 45.K \endliteral The end of the literal section. No textB may be included on this line either.ww