/WORKING DOCUMENTATION GENERATOR
/
/ WRITTEN BY BILL NOWICKI
/ NORTHWESTERN UNIVERSITY
/ COMPUTER SCIENCE RESEARCH LABORATORY
/	MAY, 1976
/	UPDATED: DECMEBER 1, 1976
/
/+GENERAL INFORMATION
/
/	THIS PROGRAM CAN BE USED TO GENERATE A WORKING DOCUMENT
/FROM A SOURCE PROGRAM WHICH FOLLOWS THE RULES FOR COMMENTING
/OUTLINED BELOW.  USUALLY THIS WILL BE A "PAL" SOURCE, ALTHOUGH
/OTHER LANGUAGES MAY BE ADDED IN THE FUTURE.
/THIS IS A "SNOBOL" PROGRAM WRITTEN FOR THE "SNOBOL 8.2" COMPILER
/TO RUN UNDER "OS/8".  
/
/ THE PROGRAM GENERATES COMMANDS FOR THE PROGRAM "RUNOFF"
/(FORMERLY CALLED "PRINTR")
/WHICH ASSUMES ALL INPUT IS IN UPPER CASE. HOWEVER, ANY LOWER CASE
/COMMENTS WILL BE TRANSMITTED IN LOWER CASE.
/THE ONLY MAJOR DRAWBACK IS THAT THE PARAGRAPH DESCRIPTIONS
/FOLLOWING THE /+ FLAG CHARACTER ARE MAPPED INTO 
/UPPER/LOWER CASE IN A NON-INTELLIGENT FASHION.
/TO SEE EXACTLY HOW THIS IS DONE, CONSULT THE "RUNOFF" MANUAL,
/KEEPING IN MIND THAT THE MODE USED IS: "FILL", "JUSTIFY",
/"AUTOPARAGRAPH", "AUTOCAPITALIZE", AND "FLAGCAPITALIZE#_"".
/THIS ESSENTIALLY MEANS THAT ALL SENTANCES MUST END WITH A PERIOD,
/PARAGRAPHS MUST BE SEPARATED BY A BLANK "COMMENT" LINE
/FOLLOWED BY A LINE STARTING WITH TWO SPACES, AND NAMES
/WHICH SHOULD REMAIN IN CAPS SHOULD BE ENCLOSED IN QUOTES.
/IF THIS AUTOMATIC CAPITALIZTION FEATURE IS NOT DESIRED,
/ANSWER THE RUN-TIME QUESTION: ^^AUTO CAPS (Y OR N) ?\\
/WITH AN "N".
/
/ ALL FLAG CHARACTERS MUST BE PRECEEDED BY A
/SLASH AS THE FIRST NON-BLANK CHARACTER IN THE LINE.
/THE FOLOWING IS A TABLE OF THE PRESENT FLAG CHARACTERS
/AND A SHORT DESCRIPTION OF THE EFFECT OF EACH:
/
/=FLAG	NAME				EFFECT
/ +	"PLUS"			^PARAGRAPH DESCRIPTION
/ -	"MINUS"			^SEARCHES FOR NEXT "PLUS"
/ &	"CALLING" "SEQUENCE"	^OUTPUTS COMMENTS AS THEY ARE,
/				 WITH NO FILLING, CASE MAPPING, ETC.
/ #	"ROUTINES" "USED"	^DITTO
/ ;	"LOGIC"			^DITTO
/ *	"GLOBAL" "VARIABLES"	^DITTO
/ =	"TABLE"			^DITTO
/ $	"LOCATIONS"		^DITTO
/ @	"VARIABLES"		^PRINTS OUT EVERYTHING UNTIL THE NEXT
/				 FLAG CHARACTER.
/ !	"ENTRY" "POINTS"	^TREATS FOLLOWING LINES STARTING WITH 
/				"PLUS" AS NAMES OF ENTRY POINTS.
/ "	"TIMING"		^SEPARATE PARAGRAPH IF IN "PLUS" MODE
/ :	"CODE"			^MUST BE ONE OF THESE OR ANOTHER FLAG
/				 CHARACTER AFTER EVERY "PLUS".
/
/-GENERAL INFORMATION
/+STRING CONSTANTS
/
/ THE USER CAN CHANGE THE FLAG CHARACTERS FOR USE WITH
/SOME OTHER LANGUAGE IF DESIRED.
/THE FOLLOWING ARE THE PRESENT SETTINGS:
/@
	T = .A211		/TAB (ASCII 211) MAY WANT TO DEFINE AS
				/THE SEQUENCE .A377 .A211
	SP = " "		/SPACE
	S  = "/"		/COMMENT CHARACTER
	FP  = "+"		/START OF MODULE
	FS  = "&"		/CALLING SEQUENCE
	FS2 = "<"		/OLD FORM FOR CALLING SEQUENCE
	FR  = "#"		/ROUTINES CALLED
	FR2 = ">"		/OLD FORM FOR ROUTINES USED
	FL  = ";"		/LOGIC
	FC  = ":"		/CODE
	FM  = "-"		/MINUS (END OF MODULE)
	FG  = "*"		/GLOBAL VARIABLES
	FV  = "@"		/LOCAL VARIABLES
	FE  = "!"		/ENTRY POINTS
	FT  = "="		/TABULAR DATA
	FD  = "$"		/LOCATIONS USED
/-STRING CONSTANTS
/
/
/+USER INPUT
/	THE PROGRAM FIRST ASKS FOR THE INPUT AND
/OUTPUT FILES. AFTER GETTING 
/TWO GOOD RESPOSES, THE PROGRAM WILL PRINT:
/ ^^AUTO CAPS (Y OR N) ?\\
/ ANSWER THIS QUESTION DEPENDING ON IF IT IS DESIRED
/FOR "RUNOFF" TO DO THE UPPER/LOWER CASE CONVERSIONS.
/THE PROGRAM WILL THEN PRINT:
/ "MODULES" "DOCUMENTED:"
/
/ IT WILL OUTPUT SOME "RUNOFF" COMMANDS TO THE FILE
/AND USE THE FIRST LINE OF INPUT (IF IT IS A COMMENT) AS
/THE TITLE OF THE DOCUMENT.
/THE PROGRAM PASSES DOCUMENTATION THROUGH IN FIVE MAJOR
/MODES WHICH ARE DESCRIBED BELOW.
/
/:CODE:
ASK,	OUTHOLD = "INPUT:"
	.LOOKUP INPUT :F(ASK)
ASKO,	OUTHOLD = "OUTPUT:"
	.ENTER INPUT :F(ASKO)
ASKOP,	OUTHOLD = "AUTO CAPS (Y OR N) ?"
/
	AUTO = INPUT
	AUTO_ "Y"!"N" :F(ASKOP)  	/CHECK FOR VALID RESPONSE
	AUTO_ "Y" ** = "\\"		/SETUP FOR FLAG
	AUTO_ "N" **=			/FORGET ABOUT OTHER GARBAGE
/
/	WE HAVE GOOD FILES, SET UP SOME STUFF
/
	OUTPUT = "MODULES DOCUMENTED:"
	WRITE = ".NF;.UC"
	LINE = READ			/READ THE TITLE LINE
	LINE ** "/" = :F(SETUP)		/IGNORE IF NON-COMMENT
	WRITE = ".CW; ^&" LINE "\&"	/OUTPUT THE UNDERLINED TITLE
	WRITE = ".TITLE " LINE
SETUP,	WRITE = AUTO '.AP;.AC;.FLAG CAPITAlIZE ";.NUMBER 1'	
/
/-USER INPUT
/
/
/+CODE, MINUS, LOOP MODES
/
/	"CODE" MODE IS OBTAINED AT THE BEGINING OF THE FILE,
/AND AFTER ANY /- OR /:.  IN THIS MODE, NOTHING IS OUTPUT
/ALTHOUGH EACH LINE IS SCANNED FOR A /+ IN THE FIRST COLUMN.
/
/:CODE:
CODE,	
MINUS,
LOOP,	LINE = READ :F(EOF)
	LINE_ S FP = :F(LOOP)		/IGNORE EVERYTHING TILL /+
/-CODE, MINUS, LOOP
/
/+PLUS 
/	"PLUS" MODE IS ENTERED AFTER SEEING A SLASH PLUS
/IN COLUMN 1.  THE COMMENTS AFTER A SLASH PLUS
/ARE FIRST SCANNED FOR OTHER FLAG CHARACTERS,
/AND THEN ARE SIMPLY TRANSMITTED TO THE OUTPUT
/FILE.  HOWEVER, THE "RUNOFF" COMMANDS PLACED BEFORE
/THE LINES IMPLY THAT ANYTHING ON THE COMMENT LINE IS
/PART OF A TEXT PARAGRAPH, AND WILL THEREFORE BE
/FILLED AND JUSTIFIED.
/:CODE
PLUS,	OUTPUT = LINE
					/THE FOLOWING MESS OUTPUTS
					/SOME NEEDED RUNOFF COMMANDS
	WRITE = ".TP 8;.B 2;.CW; ^&^^" LINE "\&" AUTO
	WRITE = ".FILL;.P"		/START THE PARAGRAPH
	CAPSYM = ".B 2;.NF;^^"		/RESET THE CAPITALIZE SYMBOL
	COMSYM = S			/RESET THE COMMENT SYMBOL
	TABSYM = T			/TAB CHARACTER
	SPSYM = " "			/SET THE SPACE CHARACTER
PLOOP,	LINE = READ :F(EOF)
SEARCH,
	LINE_ T COMSYM = COMSYM T	/ZAP LEADING TABS
	LINE_ S = :F(PASTST)		/IS IT A GOOD COMMENT ?
	LINE_ FS = :S(CALSEQ)		/& MEANS CALLING SEQUENCE
	LINE_ FS2= :S(CALSEQ)		/OLD FORM OF CALLING SEQUENCE
	LINE_ FR = :S(ROUTIN)		/# ROUTINES CALLED
	LINE_ FR2= :S(ROUTIN)		/OLD FORM FOR ROUTINES USED
	LINE_ FL = :S(LOGIC)		/; LOGIC
	LINE_ FC = :S(CODE)		/: CODE
	LINE_ FM = :S(MINUS)		/- END OF MODULE
	LINE_ FG = :S(GLOBAL)		/* GLOBAL VARIABLES
	LINE_ FV = :S(VARIABL)		/@ VARIABLES
	LINE_ FE = :S(ENTRYS)		/! ENTRY POINTS
	LINE_ FT = :S(TABLE)		/= TABLE
	LINE_ FD = :S(LOCS)		/$ LOCATIONS
	LINE_ FP = :S(PLUS)		/COULD HAVE NESTED /+'S
			:(TABZAP)	
PASTST,	LINE "/" = :S(TABZAP)		/WE WANT ALL COMMENTS
	""_ COMSYM :F(PLOOP)		/SHOULD WE PASS NON-COMMENTS ?
TABZAP,	LINE TABSYM = :S(TABZAP)	/GET RID OF TABS
	LINE_ SPSYM =			/GET RID OF SINGLE SPACES
	WRITE = LINE  :(PLOOP)		/OUTPUT AND CONTINUE
/-PLUS
/
/+CALSEQ, ROUTINES, LOGIC, GLOBAL, TABLE, LOCS
/	"TABLE" MODE IS OBTAINED BY ANY OF THE 
/FOLLOWING FLAG CHARACTERS:  < _# * = ; $.
/IN THIS MODE EVERYTHING IS PUT IN UPPER CASE THROUGH
/"RUNOFF" WITH NO FILLING SO THAT SPACING IS NOT AFFECTED.
/:CODE:
LOCS,
CALSEQ,
ROUTINES,
LOGIC,
GLOBAL,
TABLE,
	COMSYM = S			/WE ONLY WANT COMMENTS
OUTCAP,	WRITE = CAPSYM LINE
	TABSYM = .A232 .A232		/CONTROL Z'S SHOULD NEVER EXIST
	SPSYM = TABSYM			/SAME FOR HERE
	CAPSYM = "" :(PLOOP)		/CONTINUE
/-CALSEQ, ROUTINES, LOGIC, GLOBAL, TABLE
/
/+VARIABLES
/	"VARIABLE" MODE IS OBTAINED BY THE /@ FLAG.
/IN THIS MODE "EVERY" LINE OF INPUT IS SENT TO THE
/OUTPUT FILE, ALTHOUGH SLASHES ARE REMOVED FROM COMMENTS.
/IT IS VERY IMPORTANT THAT ANOTHER FLAG CHARACTER
/IS USED TO GET OUT OF THIS MODE OR THE ENTIRE
/PROGRAM WILL BE SENT TO THE OUTPUT FILE.
/
/:CODE:
VARIABLES,
	COMSYM = ""			/SET TO PRINT OUT EVERYTHING
			:S(OUTCAP)
/
/-VARIABLES
/
/+ENTRYS
/	"ENTRY" MODE IS THE MODE USED TO PROCESS THE
/"/!ENTRY" "POINT" FLAG.  IN THIS MODE FOLLOWING LINES
/STARTING WITH "/+" WILL BE PUT IN CAPS ON THE SAME LINE.
/THE FIRST LINE NOT STARTING WITH "/+" GOES BACK INTO "PLUS"
/MODE.
/:CODE:
ENTRYS,	WRITEH = ".P;^" LINE
ENLOOP,	LINE = READ :F(EOF)
	LINE_ S FP = :F(ENEND)
	WRITE = '"' LINE :(ENLOOP)	/OUTPUT AN ENTRY POINT
/
ENEND,	WRITEH = ".P;" :(SEARCH)	/END OF ENTRY POINTS
/
/-ENTRYS
/
EOF,	.OCLOSE :F(CERROR)
	.ICLOSE
	.EXIT
CERROR,	OUTPUT = "CLOSING ERROR !"
	.EXIT
IOBAD,	OUTPUT = "OUTPUT ERROR !"
	.END
/-EOF