This is a documentation facility which allows the user to associate
a list of comments with a word, file them and selectively retrieve them.

COMMENT    [PROPERTY]
is the property under which documentation is stored.  It is a list of comments
for the word on whose property list the property resides.  Each comment has an
ID and DECRIPTION as documented in DC and a body, either a string or a file
pointer.  Comments are created by DC and displayed by DOC.

COMMENTS    [FILEPKGCOM, FILEPKGTYPE]
The file package command (COMMENTS * FOOCOMMENTS) or (COMMENTS FOO1 FOO2 ...)
dumps the documentation of the elements of FOOCOMMENTS or of FOO1, FOO2, etc.
The corresponding file package type is also defined.

(DC WORD ID DESCRIPTOR)    [NLAMBDA SPREAD]
DC creates a comment (documentation) for the specified word.  Each word may
have arbitrarily many comments, but only one for a given ID.  When an old ID
is used the comment for that ID is replaced.  WORD and ID should be atomic.
DESCRIPTOR is an arbitrary Lisp object (normally a list) that describes the
comment.  It can be used to decide whether the comment should be printed by
DOC.  Comments are stored under the COMMENT property of WORD.  This can be
edited if you want to delete comments, change their order or change their
descriptor fields.  The text of the comment is stored either as a string
(when it is first typed in) or as a file pointer.  As a default, file pointers
are used whenever possible.  They are created whenever a comment is written
to a file or read from a file.  These defaults may be overridden by setting
the flag DC-DEFINE to store a string read from a file, and DC-RETAIN to keep
a comment as a string when it is written to a file.

The following conventions are suggested for documentation:
   Every file should contain a comment for the file name which at least
lists the other words with documentation in the file.  This is just a way
for a user to find out what documentation exists.  Of course, if you want
to describe the file while you're at it, so much the better.
   It is expected that most words with documentation will have only one
comment, and that doc ought to print it without asking.  Therefore, the
suggested usage (reinforced by the default DOCFILTER function) is that a
comment ID of NIL (which is what you will get if you type "(DC FOO)") 
indicates that the comment should be displayed.  For any other ID, the
default DOCFILTER will ask the user.

(DOC word1 word2 ...)     [NLAMBDA NOSPREAD]
DOC retrieves the documentation for the words specified.  For each comment
(in the order of the COMMENT property) DOC calls (DOCFILTER word id descr)
where the parameters are the same as for DC.  If the result is non-NIL the
comment is printed.  The default DOCFILTER prints its arguments and if the
id is NIL returns T (i.e. print it).  If the id is non-NIL it asks the user
whether to print the comment.  This is meant to reflect the common usage of
DC to give a word only one comment by just doing (DC word).

OriginalFILERDTBL  [VAR]
The comment package alters FILERDTBL.  In particular, it uses <esc> to delimit
comments.  In case you want to read other files that may contain <esc>
followed by 3 blanks followed by newline (or other files that do not conform
to changes made to FILERDTBLE), it is handy to have the original FILERDTBL
around to bind to FILERDTBL.  If OriginalFileRdtbl is not bound when the
comment package is loaded, it is given the value of FILERDTBL.

Problems

At the moment there is no good way to edit the text of a comment.  One hack
that works is to just edit the file with a text editor and then load it
into lisp (which will rewrite the filemap.  In the long run, the best
plan seems to be not to write a text editor but provide an interface to the
editor of your choice.  Unfortunately, there are many text editors with 
different interfaces.  At the moment I'm leaning toward picking a standard
file name (doc.temp or some such), writing the comments to it, calling the
editor of your choice with subsys and then reading the file back in with
DC-DEFINE set to T.  This means that the user must load the file and save
it in addition to editing.  Any suggestions are welcome.

At the moment the comment package contains a sleazy hack which enables comments
to be copied onto a .COM file by TCOMPL.  (The comment is transformed by a
readmacro into an EVAL@COMPILE.)  This is certainly not the "right" solution,
but it works (for now).

LOADFNS seems to work all right for comments - remember that the pattern you
want is (DC <word> ...).  GETDEF and friends seem to work reasonably well
(which is utterly amazing), but of course they tend to return comment
pointers.  This is what you want e.g. for editdef - it lets you reorder the
comments, change their attributes etc.  (One problem is that GETDEF from a
file tends to get other definitions besides the one you wanted.  This is due
to GETDEF's limited understanding of where to find definitions of types it
doesn't know.)

The use of file pointers tends to lead to problems when MAKEFILE bombs out.
If you ctl-D out of MAKEFILE, the comments will be correct, but you may have
to do something to make the files accessible.  In particular, you should
close the file you were making, and undelete its former version if necessary.
Otherwise, the file pointers will point to files that can't be found.  After
that you can redo the MAKEFILE.

DonC (Don Cohen) @ ISIF