COMMENT ⊗   VALID 00006 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	BRIEF DOCUMENTATION FOR BLACKBOARD-LISP PRETTY PRINTING PROGRAM
C00007 00003	ANALYSIS OF VARIABLES IN THE BLACKBOARD PRETTY PRINT PROGRAM.
C00012 00004	PROPERTIES
C00013 00005	ANALYSIS OF CONTROL FLOW:
C00014 00006	ANALYSIS OF ACTION
C00020 ENDMK
C⊗;
BRIEF DOCUMENTATION FOR BLACKBOARD-LISP PRETTY PRINTING PROGRAM

	This program  takes  regular S-expression  Lisp functions  as
source, converts  them to McCarthy's blackboard Lisp (approximately),
and pretty prints them.  Currently there are two modes, PUB and LPT.
The LPT mode puts out plain text with linelength 120.  The PUB mode
puts out code suitable to be pubbed using the pub conventions defined 
in LSP.PUB[LSP,CLT].  These are the conventions used for the CS206 notes.

	The system consists of an init file BBPP.x and a function file
BB.x where x=MCL for running in MACLSP and x=LSP for running in ILISP. 

	To use the system in MACLSP type (eread bbpp mcl (/206 clt))
followed by (ioc q).  If foo is a list of atoms that are functions or
have values then (bblpt foo file) will write blackboard versions of these
functions and variables on file in a form suitable for direct printing
and (bbpub foo file) uses the form suitable for pubbing.  You can
also type (bbmcllpt foo) or (bbmclpub foo) which are the first level functions
and return the corresponding text.  


	To run the system in IL (ILISP) try R IL 55 and
ALLOC Bin Prog Space = at least 1000. It will run out of space when
doing a long list of fns but works otherwise.  To read in the program and perform 
initialization, type

	(DSKIN (206 CLT) (BBPP.LSP))

This  file contains  commands to  read the  BBFCN  file  and to  perform
initialization. To produce pretty printed output execute one of:

	(BBLSPLPT u)
	(BBLSPPUB u)

where the value of u is a list of atoms  which are names of the EXPRs
and  FEXPRs to be  printed.  (The VLAUE property of  the atoms besides
EXPR and FEXPR can also be printed--see below for how.)

	BBTTY and  BBLPT  produce output  formatted for  fixed  width
characters with  line lengths  appropriate for the  TTY and  the line
printer, respectively.   No font shift characters are included in the
output. 


	BBPUB produces output  which can be used as  PUB source text.
It contains PUB control characters for the LSP font and operator macros.

	The output  produced by any of these functions can be written
on a file by using DSKOUT, e.g. 

	(DSKOUT FILNAM (BBLSPPUB FUNS))

If the value of FUNS is a list of function  names, then each function
will be pretty  printed on the file FILNAM.   (See the description of
DSKOUT in the Lisp manual for more details.)


SPECIFYING THE PROPERTIES TO BE PRINTED

	BBPROPS is a  list of  the properties to  be pretty  printed,
currently  (EXPR  FEXPR VALUE).    It  can  be  changed  to  include  other
properties.   Any property other than VALUE  will be printed as if it
is a  function  body.    VALUE properties  will  be  printed  as Lisp
constants. 


The lists PPLISPLPT and PPLISTPUB are used to define the text generated
for all of the special LISP functions and operators.  

The original form of this program used looked up font widths in the
font files and determined the number of characters on a line using this
data.  This could be reinstated for added flexibility, but the current
pubbing conventions seem not to warrant the fuss.
ANALYSIS OF VARIABLES IN THE BLACKBOARD PRETTY PRINT PROGRAM.

	<name>		x<name>list where x = " " denotes a reference
					  x = "*" denotes a set
					  x = "⊗" denotes reference and set
	    <comments>

VARIABLES defined in the BBFCN file "BB.LSP"
 
	BBFCNS		
	BBLIST		(as arg to SETCARLIST)
	BBPROPS		BBPPROPS
	CHARW		⊗BBPUB  BBXGPPUB
	FIN		BBTTYLPT  BBXGPPUB
	HIN		   "	    "
	MAXF		   "        "
	SIN		   "        "
	LINL		   "	 ⊗BBXGPPUB  *BBLPT  *BBTTY  PREX  PRF  PRT
	VALIDPUBCODES	SETUPFONT
	XGPLINL		BBXGPPUB
 
 
VARIABLES initialized by BBINIT
 
	BBNAME		⊗BBINIT
	    used to see if init has already been done. If so BBNAME must be set to
	    NIL in order to reinitialize.

	FONTARRAYS	*BBINIT  CLEARFONTS ⊗READFONT
	    a list of array pointers used for fontwidth arrays
	    initially: NIL

	FONTSYMBOLS	*BBINIT  ⊗CLEARFONTS  *SETUPFONT
	    a list of symbolic font selectors that have been FONTed
	    used to prevent duplicate definitions
	    initially: NIL  symbols have the form BB<symb> where <symb> is arg to FONT

	FONTPROPS	*BBINIT  BBTTYLPT BBXGPPUB ⊗CLEARFONTS  ⊗XA
	    a list of items of the form (<lisp atom>.<font symbol>)
	    initially: NIL

	CARBBLIST 	*BBINIT  ⊗CLEARBB  *SETCARLIST
	    initially: NIL


VAIRABLES initiallized by CLEARFONTS and hence by BBINIT


	XGP		see below
	    initially: NIL

	PUBFONTS	BBPUB  *CLEARFONTS  ⊗SETUPFONT
	    a list of items of the form (<pub switch> <xgp switch>)*(<font filename>)
		<font file name> has form (<ppn> (<fontname>.FNT))
	    initially: NIL

	FONTLIST	*CLEARFONTS  ⊗SETUPFONT
	    a list of items of the form (<font file name>.<pointer to font width array>)
	    initially: NIL

	LCFONTS		*CLEARFONTS  ⊗LCASE  XA
	    a list of font select symbols implying lower case
	    initially: NIL

	XGPFONT		*CLEARFONTS  ⊗SETUPFONT
	    initially: NIL

	FREEFONTARRAYS	*CLEARFONTS  ⊗SETUPFONT
	    a list of fontarray pointers not in use
	    initially: =FONTARRAYS
 
 
Other global VARIABLES
 
	FINDENT		*BBTTYLPT  *BBXGPPUB  PRF
	HINDENT		*BBTTYLPT  *BBXGPPUB  PREX  PRT
	SINDENT		*BBTTYLPT  *BBXGPPUB  PREH  PRF  PRT
	FMAX		*BBTTYLPT  *BBXGPPUB  PREX
	PUB		*BBPUB  *BBTTYLPT  *BBXGP  *BBXGPPUB  BBQUOTE  NEWLINE
			PRINXX  XA
	    a mode switch

	XGP		BBPROP ⊗BBTTYLPT ⊗BBXGPPUB  *CLEARFONTS  FSIZE  NEWLINE
			PRINXX  XA
	    a mode switch  

	CURFONT		*BBXGP  ⊗PRINXX

	SELECTCHAR	*BBPUB  *BBXGP  PRINXX
	    the font switch control character
	    % for PUB, ↓ for XGP

	LISPSCAN	*SETSLASHES  SCANPUSH
	    list of values initially in readtable, used to restore readtable

	PROGSCAN	*SETSLASHES  SCANPOP
	    same as LISPSCAN, not used

	%SCANSETFLAG% 	*SETSLASHES
	    gets subr prop of SCANPUSH (which is nil in uncompiled version), is not used

	FONTSYMS	*BBXGP
	    list of valid pubcodes, not used
PROPERTIES
 
 
	CARBB		gBBEX  sSETCARLIST  rCLEARBB
	    property of LISP atoms occurring as cars of elements of CARBBLIST
	    values are printing fn names

	FONT		sSETUPFONT  gXA	 rCLEARFONTS
	   property of FONTSYMBOLS 
	   values are of the form (<font width array pointer>.(<pub switch>.<xgp switch>))


	<symb>		sXA  gXA  rBBTTYLPT  rBBXGPPUB  rCLEARFONTS
	    where <symb> ε {BBSYM BBBOLD BBVAR BBCONST}
	    properties of atoms to be printed
	    FONTPROPS is a list of atom.prop pairs where prop is defined for atom
	    values are of the form (<printwidth> <font switch> . <ppname of atom>)
ANALYSIS OF CONTROL FLOW:
 
TOP LEVEL FUNCTIONS
 
	BBINIT		CLEARBB
	CARLIST		SETCARLIST
	LCASE
	FONT		SETUPFONT
	CLEARFONTS 	also called by CLEARBB

	BBLPT		BBTTYLPT
	BBPUB		BBXGPPUB
	BBTTY		BBTTYLPT
	BBXGP		BBXGPPUB
ANALYSIS OF ACTION
 
LEVEL 1.

BB[LPT | TTY] takes a list of names or s-expressions as argument, 
	sets linelength and passes argument to BBTTYLPT.

BB[XGP | PUB] takes a list of names or s-expressions as argument, sets SELECTCHAR 
	and PUB.  
		BBPUB runs SETSLASHES to modify the readtable and prints out PUB 
	commands for defining fonts, setting parameters, declaring macros, etc.  
	The argument is passed to BBXGPPUB.
		BBPUB restores readtable by running SCANPUSH.

BB[TTYLPT | XGPPUB] takes a list of names or s-expressions as argument. 
	The variables LINELENGTH, SINDENT, FINDENT, HINDENT, FMAX, and
	CURFONT( in the XGPPUB case only) are initialized.  If the XGP
	is of wrong parity the FONTPROPS are cleared. Finally XGP and
	PUB(in the TTYLPT case only) are set.  BBPPROPS is applied to 
	element of the argument list.  Before exiting, the linelength is 
	reset.
 
 
LEVEL 2.

BBPPROPS takes a name or sexpression as argument. 
	if name then apply BBPPROP to (<name> <prop> (GET <name> <prop>))
		for each prop on BBPROPS
	if s-exp apply  BBPPROP to (NIL NIL <s-exp>)
 
BBPPROP takes as arguments (<name> <prop> <s-exp>)
	if n s-exp then NIL
	if n prop then apply PREX to ((BBEX <s-exp>) 0 0)
	if prop = VALUE then apply PREX to ((BBVALDEF <name> (d <s-exp>)) 0 0)
	if (prop is EXPR or FEXPR) apply PREX to 
		((BBFUNDEF <name> <args> <body>) 0 0)
		where <args> = (cadr <s-exp>) and <body> = (cddr <s-exp>)
 
 
LEVEL 3.
 
Define the data structure BBE as follows:

	BasicBBE ← (<length> <font> <bb-exp>)
	BBXE J (<length>  'X  <list of BasicBBE's>)
	BBE ← BBXE | (<length>  <nonX-type>  <list of BBE's>)
	<nonX-type> ← 'E | 'H | 'A | 'B | 'U | 'F | 'T 

The function XA constructs a BasicBBE for each (<font symb> <at>) pair encountered
	and stores it on the <font symb> property of <at>.  The pair is also
	cons'ed onto the FONTPROPS list inorder to allow clearing of these
	props when a new problem is started.  XA then returns the BasicBBE.

The function MAK constructs a BBE from a type and a list of BBE's by summing up
	the length of the BBE's on the list and consing that and the type onto 
	the list.

PREX	takes as arguments a BBE, a parameter IM,
		and a parameter R giving the length of the expression to the
		right of BBE.
 	if length+current position+R is less than allowed line length then 
		return SIMPLEPRINT of BBE
	otherwise depending on the type pass BBE to one of the functions:
		PREH, PRA, PRF, PRT, or PRINX
	
	called by: BBPROP, PRA, PREH, PRF, and PRT.

BBEX 	takes as argument an internal form S-expression, E, and returns
		(# . the corresponding BBE). 
	if at(E) then <144 'X  (XA E if E distingushed lisp atom the 'BBCONST 
					else 'BBVAR)
	if at(a E) then if one of the special functions apply the carbb function
		for (a E) to (d E) and any carbb args, otherwise apply BBFUN
		to (a E) and (BBARGS (d E))=the list of BBE's obtained by
		aplying BBEX to each element of (d E).
	if (aa E)=λ then apply BBLAMBDA to (da E) and (BBARGS (d E))
	otherwise apply BBFUN to 'APPLY$ and (BBARGS E).

	called by BBCOND, BBELSE, BBPROP, and self via BBARGS.

BBVALDEF	
	takes as argument an atom, NAME, and a value, VAL and returns the same
	as taking cdr of the BBE for (SETQ NAME <'QUOTE VAL>)

BBFUNDEF