carm> 
carm> Hello everyone,
carm> Does anyone have a solution (a la Java) whereby a program or script
carm> reads a lisp source code file and produces programmer documentation?
carm> The format of the doc could be html or rtf....
carm> 
carm> Perhaps something like this:
carm> 
carm> 
carm> <module-name at ;;;;> Infrastructure
carm> <module-description at ;;;;> This is the infrastructure module, it provides ....
carm> 
carm> ;;; @function foo
carm> ;;; @author john doe
carm> (defun foo (arg-1)
carm>  "foo takes an argument and returns it back to you"
carm>  <special-code at ;;> Notice we don't check the argument type
carm>   arg-1)

I've built an Emacs Lisp "package" that does something like what you want, and
I'd be happy for you to use it.  You can get it from:
    http://cdps.umcs.maine.edu/Public/LispDoc/
The README file is below.  If you use it, drop me a line so I can add you to a
mailing list for updates, etc.
   --Roy
----
11:05 - Fri Oct 24, 1997 -rmt- (Roy Turner, <umcs.maine.edu) at rmt>
---------------------------------------------------------------

This directory contains version 1.0 of my Lisp documentation Emacs "package",
and I use that term loosely.  This package allows you to easily document
functions, methods, classes, and so forth while you are writing/editing them
in Emacs.  In most cases, Emacs will extract salient parts of the definition
(e.g., the argument list) for you and insert it in comments.  These
standardized comments can then later be extracted (by Emacs Lisp functions
also supplied) to form valid LaTeX descriptions of the function, etc.

This package was developed for our local use at the University of Maine in the
Cooperative Distributed Problem Solving research group
(http://cdps.umcs.maine.edu), so it is not as robust as it could be.  As time
permits, I will work on it.  HOWEVER, THIS IS NOT SUPPORTED CODE -- take it and
use it "as is".

After ungzipping and untarring the files, you will have:
   o lisp-documentation.el -- the Emacs Lisp file containing the definitions
     of the documentation functions
   o extract-comments.el -- The Emacs Lisp file containing functions to
     extract the comments from a Common Lisp file, convert them to LaTeX, and
     write them to a LaTeX file (NOTE: this has not been tested lately, and it
     may not work with some of the newer comment forms)
   o documentation.lisp: 
   o doc.tex, comments.tex: documentation (such as it is) for this package --
     this probably has not kept pace with the way lisp-documentation.el
     actually works -- sorry about that! (I'll try to fix it in future.)
   o doc.ps: a PostScript version of the above
   o documentation.sty: a LaTeX style file for use with the LaTeX file created
     by extract-comments
   o header.tex, trailer.tex: pieces of LaTeX code that can go before and
     after the comment .tex file to make a complete LaTeX document
   o xxxxx.template: these files are comment templates for functions
     (function.template), macros (macro.template), etc.  You can change these
     to suit your own purposes, or add new ones for new purposes -- if you do
     the latter, however, you'll need to make corresponding changes in
     lisp-documentation.el. 


To complete installation:
   o In lisp-documentation.el: change variable "lisp-doc-directory" to point
     to where the templates are installed.
   o Edit header.tex to have the documentstyle macro point to where the
     documentation.sty file resides
   o Make sure that this directory is on your Emacs load-path

To use:
   o Either load the library directly (M-x load-library lisp-documentation) or
     set up autoloads for the major functions "doc", "insert-header",
     "doc-help", and "doc-patch".
   o To insert a header: M-x insert-header
   o To insert a patch's documentation: M-x doc-patch
   o To document a function, macro, etc.: 
       o position the cursor on the (defxxxx line
       o M-x doc
       o NOTE: the documentation expects some parts of a definition to be
         complete for some kinds of documentation -- for example, before
         documenting a CLOS class using doc, you must define the instance
         variables.  Trial and error or looking at the code in
         lisp-documentation.el will be useful here, but most of the time, it's
         pretty intuitive.

For help: M-x doc-help (which also occurs on first loading the stuff)

If you want to be added to a mailing list of users of this (for announcements
of future versions, e.g.), send me mail <umcs.maine.edu). at (rmt>
-------
Roy M. Turner, Assistant Professor () E-mail: <umcs.maine.edu at rmt>               
Department of Computer Science     () WWW:    http://cdps.umcs.maine.edu/~rmt  
5752 Neville Hall                  () Phone:  (207)581-3909                    
University of Maine                () FAX:    (207)581-4977                    
Orono, ME 04469-5752               () I use Lisp because I know C, C++, Ada,...