Added documentation for lisp and lisp libraries.

src/libdoc/fasdmp.info

@@ -0,0 +1,79 @@
+FASDUMP Documentation  --  Richard L. Bryan (RLB) 23 APR 1975
+
+    FASDUMP is a set of Lisp functions to dump, in
+FASL format, s-expressions to be eval'ed at FASLOAD
+time.  Provision is made for preserving, when desired or
+necessary, the EQness of common subexpressions.
+The calling form is
+   (FASDUMP targetfile noneqlist eqlist fasdumpalist)
+i.e., a SUBR of four arguments.  The args are as follows:
+
+TARGETFILE:  File spec describing destination of
+output data.  If it is an atom, it specifies the first
+filename.  If it is a list, it specifies a UREAD-type file
+spec, with second file name defaulting to FASL.  I guess
+that makes it a FASLOAD-type file spec.
+
+NONEQLIST:  This is a list of forms to be eval'ed at
+FASLOAD time.  These forms are not examined for EQ
+subexpressions, so EQness is not preserved for these forms.
+
+EQLIST:  This is another list of forms to be eval'ed at
+FASLOAD time.  These forms and their subforms are
+effectively interned on an internal obarray so that EQness
+of all subforms in all forms in this list is preserved.
+Subforms which are EQUAL but not EQ are not EQified.
+
+FASDUMPALIST:  This alist provides information to
+convert subforms to something determinable only by evaluation at
+load time.  For example, many Macsyma expressions contain the 
+form (MPLUS SIMP), all occurrences of such form supposedly
+being EQ to (GET 'MPLUS 'MSIMPIND).
+If such forms are dumped without special processing, then all
+such forms upon loading will be EQ to each other, but not to 
+the "real" one.  Thus, when saving a Macsyma expression
+suspected of containing such forms, one member of the list 
+passed as the last arg to FASDUMP would be:
+   (CONS (GET 'MPLUS 'MSIMPIND) '(GET 'MPLUS 'MSIMPIND)).
+
+    It should be noted that the interning process for each form
+in the EQLIST requires making several passes over each
+form, and requires one cons for each unique subexpression plus 
+one cons for each unique subexpression appearing more than once;
+hence EQness preservation can be expensive for large expressions.
+
+    The FASDUMP code lives in MC:RLB%;FASDMP >, and a
+compiled version can be found in MC:MACSYM;FASDMP FASL.
+
+    As an example of FASDUMP usage, consider a function
+to save specified atoms on a specified file.  The following 
+definition, typed off the top of my head and untested, might do
+the job.
+
+;;;SAVE ATOM VALUES AND PROPS WITHOUT EQNESS PRESERVATION:
+;;;USE LIKE (ATOMSAVE <FILESPEC> A1 A2 A3 ...)
+
+(DEFUN ATOMSAVE FEXPR (ARG)
+  (FASDUMP (CAR ARG)
+	   (DO ((FL) (AL (CDR ARG) (CDR AL)))
+	       ((NULL AL) (NREVERSE FL))
+	       ;;SAVE ATOM VALUE, IF ANY
+	       (AND (BOUNDP (CAR AL))
+		    (SETQ FL (CONS (LIST 'SETQ
+					 (CAR AL)
+					 (SYMEVAL (CAR AL)))
+				   FL)))
+	       ;;SAVE ATOM'S PLIST, IF ANY
+	       (DO ((PL (PLIST (CAR AL)) (CDDR PL)))
+		   ((NULL PL))
+		   (SETQ FL (CONS (LIST 'DEFPROP
+					(CAR AL)
+					(CADR PL)
+					(CAR PL))
+				  FL))))
+	   NIL	;DON'T BOTHER WITH EQNESS PRESERVATION
+	   NIL))
+
+Another example of usage can be found in Macsyma's $FASSAVE
+command in MC:JPG;DSKFN >.
+