documentation-tools

Unlike document generation tools in other languages, e.g. Doxygen or Sphinx which read source code files, almost all the extant lisp document generation progams do introspection on a running system. The only programs that I am aware of that reads the source code is cldoc and qbook. Regardless of the approach taken, they are all intended to help with the problem of keeping the documentation in sync with the source code. Even if the programmer is one of those types who doesn't provide documentation strings in the code, these applications will at least give you an api.

Some of these programs only provide the external api, I'm referring to those as API-Generators. Others provide at least the option for both the internal and external api. Those are set out in the Full-Manual-Generators section. There are also the Dynamic-Browsers, which may only be possible in lisp. They use a small webserver backend and generate api documentation on the fly for any packages currently loaded in your lisp image.

Time for a small rant. Of course, just having the names and parameters of functions with no hint as to how it all fits together means that some prospective user has to slog through your code to decide if it does what they need. And if you wrote some clever code and did not provide a roadmap, the prospective user is simply going to give up and write their own version. If you want people to use your software, write up some type of explanation and provide a simple example or two. There is at least one package in the quicklisp loadable libraries where the author actually stated that he decided to write his own graphics routines rather than trying to figure out how to use a certain existing graphics library. Communities do not grow unless you give them a reason to come together. Having the greatest code in the world is not sufficient to bring people together to want to use your code. That starts with helping understand (a) how to use your code and (b) why they should want to use your code.

Return to Top

What you would look for in a documentation tool is going to vary, depending on what you want to do.

If you are browsing through what is loaded in quicklisp, then you want a dynamic webserver application that allows you to quickly look at all the different packages currently loaded. So for that you would turn to manifest or docbrowser. (Dynamic Browsers)

If you are looking to generate an api of the exported symbols only, then you are looking at API Exporters such as atdoc, cl-api, or gendoc. This type of output is obviously going to be simpler than the full blown manuals for use by your internal development team.

If you were looking to generate a full manual on a piece of software for internal use then you are looking at programs such as clod, declt, sb-texinfo or tinaa.

There is the whole subject of literate programming, where you really are interweaving the whole story of the whys and wherefores of the program in with the source code and exporting (or "tangling") the source code for compilation. For this purpose, you could look at clweb, LP/Lisp or Org-mode's Babel ability.

Then there are packages that don't quite fit the above. In one corner is Documentation-Template which creates a template that you are expected to flesh out (if you are doing it right). In another corner is qbook which pretty much just prints your source code in a nice format. A third corner is occupied by defdoc with it's "semi-literate programming approach".

Hopefully this review will give you a taste of what is available. Note: I could only get document-template and lispdoc to work after small editing changes.

The first thing that struck me in testing the packages was how difficult this actually is. Running these tools against several packages would trigger errors dealing with one package, warnings against another and a third would generate documentation cleanly. I've tried to include a sample of error messages and the packages that generated them for all the documentation generation applications that I could get working.

One thing I was disappointed in was how so few packages took advantage of getting information from the asdf system. This is likely because so few authors put the information in the asdf file. So, a plea to all authors: please use that asd file fully. It allows for author, maintainer, license (or licence), description and long-description. This would help both documentation generation packages and the entire quicklisp project. Then we can get at them automatically rather than needing those input on the repl. E.g.

(ignore-errors (asdf:system-author (asdf:find-system 'cl-api)))
"Andrea Chiumenti"

How do the lisp document generation programs compare to Doxygen or Sphinx? So far I haven't seen the dependency visualizations that Doxygen can create. See examples here. It is certainly possible to generate these in lisp. See Ryan Davis' blog note Visualizing call graphs in lisp using swank and graphviz. In the Python world, Sphinx seems to create a framework that you are expected to complete by writing reStructuredText documents. Example links can be found here. Certainly cl-docutils gives you access to lisp tools for reStructuredText.

I would be remiss if I did not mention http://www.lispdoc.com/. It is not a documentation generator, but allows you to search various Common Lisp documents and libraries for terms or symbols. albert and hyperdoc are not part of the Summary tables below . They are, however, discussed in their own sections below. I could not get Albert to build. Hyperdoc is sufficiently different that it does not fit well into the comparison.

Return to Top

• Author, Maintainer, Version, License, Generation Date
  It is one thing if you are just browsing through the api to use something for your own program, but I think that the package should show author, maintainer (possibly more valuable than the author), version, license and generation date information if available.

• Multipage Generation
  Some of the packages generate a single html page. Generating a 7 MB html page may work for some people, but personally, something that big should be broken into manageable pieces. Indicate wish lists: e.g. clod needs to break things out into separate pages. Error handling needs to indicate where in the program the error was triggered.

• Class inheritance
  Report class inheritance items in an appendix?

• Component Dependencies
  Report on the component dependencies. Yes, this duplicates looking at the asd file, but now you have it with the rest of the documentation too.
  • Discuss visualizing inheritance, call graphs, etc
    http://ryepup.unwashedmeme.com/blog/2012/01/03/visualizing-call-graphs-in-lisp-using-swank-and-graphviz/ https://github.com/AccelerationNet/static-analysis/blob/master/static-analysis.lisp

• Automatic incorporation of text pages
  It would be nice to allow incorporation of external text pages, anything from the typical README or TODO or COPYING or LICENSE to more extended introductions, and more detailed discussion of the application. Allowing incorporation of external text pages would also allow incorporation of use examples into the documentation.

  At this point, the only package that seems to do that is gendoc.

• Document Shadowing
  It would be nice to flag whenever an application has to shadow another package it is using.

• Coverage Models
  At one point there was a suggestion of some work being done on coverage models from a testing standpoint. See. e.g., http://www.cs.cmu.edu/afs/cs.cmu.edu/project/ai-repository/ai/lang/lisp/code/testing/cover/0.html Coverage? Is there any work being done in this area and, from the standpoint of using automatic documentation generation on internal development, any way of connection a document generation application to testing coverage validation? See test frameworks.

• Nice but merely trivia
  The packages that generated html did not generate valid xhtml. Yes, you could run tidy against each result, but it would be nice if the code was cleaned up a little more.

  It would be nice to generate an appendix page showing statistics on the number of each type of symbol. Or lines of code or …. yes, merely trivial stuff.

Return to Top Testing was done on sbcl version 1.0.58 running on (a) linux kernel version 3.4.0 and (b) mac os snow leopard.

Several packages were tested. These included hunchentoot, postmodern, cl-postgres, cl-who, the document generation packages themselves and an additional test package consisting of 22 files with 1207 total symbols, including 7 exported symbols (2 functions, 1 class, 2 macros, 1 generic function, 1 variable), As internal symbols, it has 7 classes, 41 variables, 16 generic functions, 24 macros and 417 internal functions. Did you notice that the numbers do not add up? I believe those are unbound variables. So much for the trivia list for statistics.

Return to Top Return to Summary Table

• In Quicklisp: Yes
  

• Author: Elias Martenson
  

• Author Email
  

• License Info: BSD-3 Clause
  

• Software Version
  

• Homepage: http://code.google.com/p/docbrowser/
  

• Summary
  Notes: This is a dynamic webserver based package, like Manifest, generating only dynamic html. It only shows the exported symbols. Docbrowser has an issue with packages such as cl+ssl that have plus sign in the name. 

  Note that reloading the index page of all packages currently loaded does not refresh, so if you have subsequently loaded a package, it will not show up in the index list. It will be accessible, however.

  The webpage generated for a package shows tabs for functions, classes and variables. The functions tab lists all exported functions, It will note whether it is a function, a generic function, or macro, but there is no separate index for each of those types.

• Usage
  

  (ql:quickload :docbrowser)
  (docbrowser:start-docserver 8084)
  or whatever port you want to use. The default is 8080
  

• Installation Notes
  

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	No
  Index:	Yes - Functions, Classes, Variables	Organization	Tabs for Functions, Classes, Variables
  Designate Target Directory:	N/A	Multipage:	Only split by functions, classes and variables
  Export Formats	Dynamic html	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	N/A
  External Functions:	Yes (Show parameters)	Internal Functions:	No
  Macros:	Flagged in the list of functions	Generic Functions:	Flagged in the list of functions. Clicking on the function name will take you to the source code page in the browser.
  Class Info:	Yes, Slots, Specialized by	Slot Accessors:	Yes, in the list of slots in each class description
  Special Variable Values:	Yes	Conditions:	Flagged in the list of functions
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

Return to Top Return to Summary Table

• In Quicklisp: Yes
  

• Author: Peter Seibel
  

• Author Email
  

• License Info: MIT?
  

• Software Version
  

• Homepage
  Video: http://www.youtube.com/watch?v=COEgRaf6acU

• Summary
  Manifest shows the most complete set of different types of items, but strangely does not show parameters. While most packages satisfy themselves with exported functions, variables and macros, Manifest provides additional information on generic functions, slot accessors, classes, conditions, constants, used by and uses.

  From the README file: Manifest is a system for semi-automatically documenting Common Lisp packages. (A manifest tells you what's in a package. Also this system makes manifest a bunch of information that is actually present in a Lisp system.) The basic premise is that every exported symbol in a package should be documented.

  To check it out, after loading the system, evaluate (start) and point your browser at the URL it returns.

• Wish List
  
  • Link from each package page back to the index of packages.
    
  • Author, license, version information
    Obviously, this is only to the extent possible. If the author did not provide the information in the asd file, it will not be available.
  • Indexes
    

• Usage
  

  (ql:quickload :manifest)
  (manifest:START)
  

  It will return a url with a localhost:portno. Just open your browser to that portnumber: e.g. localhost:49434

• Installation Notes
  Easy installation and running.

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	No
  Index:	No	Organization	Nickname, Functions, Macros, Generic Functions, Slot Accessors, Variables, Classes, Conditions, Uses
  Designate Target Directory:	Dynamic Webpage	Multipage:	No
  Export Formats	Dynamic Webpage	Show Dependencies:	No
  Show Uses:	Yes	Show Used By:	Yes
  Generation Date:	N/A
  External Functions:	Yes (Does not show parameters)	Internal Functions:	Yes (Does not show parameters)
  Macros:	Yes	Generic Functions:	Yes
  Class Info:	Yes	Slot Accessors:	Yes
  Special Variable Values:	No	Conditions:	Yes
  Package Info:	No	General Notes:	No
  Installation Notes:	N/A	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  Return to Top

Return to Top Return to API Generator Summary Table

• In Quicklisp: Yes
  

• Author: David Lichteblau
  

• Author Email: david@lichteblau.com
  

• License Info: X11 Style
  

• Software Version
  

• Homepage: http://www.lichteblau.com/atdoc/doc/
  

• Summary
  Atdoc generates documentation for Common Lisp packages. It extracts documention strings written using a custom markup language and generates HTML pages, TeX documents, and Info files. As a result, you really have to use the markup language in all your document strings in order to get full use of the package.

  Note that while atdoc has an argument for including-internal-symbols-p, I could not get it to actually generate pages for internal symbols.

• Usage
  

  (ql:quickload :atdoc)
  (atdoc:generate-html-documentation '(:document-test1) 
                                       "/home/sabra/quicklisp/local-projects/document-test1/docs/atdoc/" 
                                       :index-title "Test Doc1 ATDOC" 
                                       :heading "Test Doc1 ATDOC" :single-page-p nil 
                                       :include-internal-symbols-p t)
  
  (atdoc:generate-html-documentation '(:document-test1) 
                                       "/home/sabra/quicklisp/local-projects/document-test1/docs/atdoc/" 
                                       :include-internal-symbols-p t 
                                       :heading "ATDOC Documentation
                                       Generator Test" :index-title
                                       "Documentation Generator Test
                                       Index" 
                                       :single-page-p nil 
                                       :include-slot-definitions-p t)
  

  Note the above did not generate the non-exported symbols

  NOTE ATDOC for latex and info did not allow the above keywords

  (atdoc:generate-latex-documentation '(:document-test1) 
                                      "/home/sabra/quicklisp/local-projects/document-test1/docs/atdoc/"
                                      :include-slot-definitions-p t)
  
  

• Installation Notes
  

• Error Items
  Mac Box: When trying to generate docs for postmodern, I got the following error message:

  There is no applicable method for the generic function #<STANDARD-GENERIC-FUNCTION SB-MOP:FINALIZE-INHERITANCE (5)> when called with arguments (#<BUILT-IN-CLASS REAL>). [Condition of type SIMPLE-ERROR]

  Mac box: When trying to generate docs for hunchentoot, cl-who, I got the following error message:

  Evaluation aborted on #<SIMPLE-ERROR "unexpected closing brace" {1002EA0863}>

  Running atdoc against tinaa generated the following warning:

  WARNING: unsupported DOCUMENTATION: type T for object of type SB-PCL::CONDITION-DIRECT-SLOT-DEFINITION

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	No
  Index:	Yes Index is alphabetical, noting whether the exported symbol is a variable, class for function. Flags undocumented functions in red	Organization
  Designate Target Directory:	Yes	Multipage:	Yes
  Export Formats	html,tex,info	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	No
  External Functions:	Yes (Show parameters)	Internal Functions:	No
  Macros:	No	Generic Functions:	No
  Class Info:	Superclass, documented subclasses, slots	Slot Accessors:	Yes
  Special Variable Values:	No	Conditions:	No
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  Note. This generates valid html, not valid xhtml.

Return to Top Return to API Generator Summary Table

• In Quicklisp :Yes
  

• Author: Andrea Chiumenti
  

• Author Email
  

• License Info: BSD
  

• Software Version
  

• Homepage: http://common-lisp.net/project/cl-api/
  

• Summary
  cl-api only generates the strings for the exported symbols. A single page was generated for each package, with separate sections for constants, variables, classes, functions, and macros. The html page generated allows you to collapse each of those sections.

• Usage
  

  (ql:quickload :cl-api)
  (cl-api:api-gen :document-test1 #P"/home/sabra/quicklisp/local-projects/document-test1/docs/cl-api/")
  Generation complete:
  "/home/sabra/quicklisp/local-projects/document-test1/docs/cl-api/document-test1.html"
  

• Installation Notes
  

• Error Messages:
  On my mac box, running cl-api against postmodern generated the following error message:

  There is no applicable method for the generic function #<STANDARD-GENERIC-FUNCTION SB-MOP:FINALIZE-INHERITANCE (5)> when called with arguments (#<BUILT-IN-CLASS REAL>). [Condition of type SIMPLE-ERROR]

  Running it against cl-postgres generated the following warning:

  WARNING: unsupported DOCUMENTATION: type T for object of type SB-PCL::CONDITION-DIRECT-SLOT-DEFINITION

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	No (Collapsible Sections on a single html page)
  Index:	No	Organization	Constants, Variables, Classes, Conditions, Functions, Macros
  Designate Target Directory:	Yes	Multipage:	No
  Export Formats	html (not valid xhtml)	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	No
  External Functions:	Yes (Show parameters)	Internal Functions:	No
  Macros:	Yes	Generic Functions:	Functions flagged as generic
  Class Info:	parent class, Default initargs, slots, the docstring for the class.	Slot Accessors:	Yes
  Special Variable Values:	Yes	Conditions:	Yes
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

Return to Top Return to API Generator Summary Table (AKA cl-gendoc)

• In Quicklisp: Yes
  

• Author : Ryan Pavlik
  

• Author Email
  

• License Info: LLGPL, BSD
  

• Software Version: 1.0
  

• Homepage https://github.com/rpav/cl-gendoc
  

• Summary
  Description: This is a simple but flexible modular document generator for Common Lisp. What I like about this one is its ability to import other written documents, not just the document strings in the source code.

• Usage
  

  (ql:quickload :cl-gendoc)
  (gendoc (:output-filename "docs.html"
           :css "simple.css")
    (:mdf "intro.md")
    (:mdf "details.md")
    (:apiref :some-package :another-package)
    (:mdf "closing.md"))
  
  (gendoc:gendoc 
    (:output-filename "/Users/sabra/data/lisp/document-tools/docs/gendoc/gendocs-postmodern.html"
     :css "simple.css")
     (:apiref :postmodern))
  

• Installation Notes
  

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	No
  Index:	No	Organization	Special Variables, Functions, Macros
  Designate Target Directory:	Yes	Multipage:	No
  Export Formats	html (not valid xhtml)	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	No
  External Functions:	Yes (Shows parameters)	Internal Functions:	No
  Macros:	Yes, if external	Generic Functions:	No
  Class Info:	No	Slot Accessors:	No
  Special Variable Values:	No	Conditions:	No
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	Yes

Return to Top Return to API Generator Summary Table

• In Quicklisp: No
  

• Author: Sven Van Caekenberghe, Pascal J. Bourguignon
  

• Author Email
  

• License Info: LLGPL
  

• Software Version
  

• Homepage
  https://gitorious.org/com-informatimago/com-informatimago/trees/master/lispdoc

• Summary
  Tested: Yes

  lispdoc generates html documentation for exported symbols based on their documentation strings. It is not included in Quicklisp but Pascal Bourguignon pointed me to his fork.

  I did have to make one editing change, noted below, in order for it to run against all my test packages.

• Usage
  Unable to run against several applications without a modification

  (lispdoc-html "/home/sabra/projects/lisp-doc/document-tools/docs/lispdoc/" 
                (list 'hunchentoot) :title "Hunchentoot")
  

• Error Notes
  Trying to run against postmodern, hunchentoot and several other packages using the following call

  (lispdoc-html "/home/sabra/projects/lisp-doc/document-tools/docs/lispdoc/" 
                (list 'hunchentoot) :title "Hunchentoot")
  

  triggered error messages stating: The bounding indices 0 and 1 are bad for a sequence of length 0. [Condition of type SB-KERNEL:BOUNDING-INDICES-BAD-ERROR]

  • Fix per Pascal J. Bourguignon:
    actual bug is in: package-navigation-menu
    This function generates a link for a parent package list, assuming hierarchical packages names with components separated by dots.  For packages at the root (without dots in their names), it should not generate a parent link.  The solution is to replace (when parent …)
    with (when parent-path …)
    
    
    (when parent-path
  (list (list parent (format nil "Up: ~A" (shorten parent)))))

• Installation Notes
  

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	No
  Index:	Yes Alphabetical Symbol and Permuted Symbol Indexes. Each index has its own page.	Organization	Alphabetical, with separate indexes
  Designate Target Directory:	Yes	Multipage:	Separate Index pages only
  Export Formats	html (not valid xhtml)	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	No
  External Functions:	Yes (Shows parameters)	Internal Functions:	No
  Macros:	Yes, Symbols which are macros are flagged as such	Generic Functions:	Yes Symbols which are generic are flagged as such
  Class Info:	Yes, class precedence list and class init args	Slot Accessors:	No
  Special Variable Values:	yes, shows initial values	Conditions:	Symbols which are conditions are flagged as such
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  A permuted index includes each n-word entry up to n times, at points corresponding to the use of each word in the entry as the sort key. For example, a symbol FOO-BAR would occur twice, once under FOO and BAR. This allows you to use any word in th symbol's name to search for that symbol.

Return to Top Return to Summary Table

• In Quicklisp: No
  

• Author: Iban Hatchondo
  

• Author Email:
  

• License Info: LLGPL
  

• Software Version: 2005
  

• Homepage: http://common-lisp.net/viewvc/cldoc/cldoc/
  

• Summary
  Cldoc calls asdf to find the source code, and then reads the source code to pull the document strings rather than otherwise introspecting into the system. The last revision in the version control system seem to be in January 2006.

• Installation Notes
  First you need to get it. It does not have a quicklisp available installation. You need to pull it from the cvs into your desired location.

  cvs -z3 -d :pserver:anonymous:anonymous@common-lisp.net:/project/cldoc/cvsroot co .
  

  The source code is now going to be in a cldor/src directory, so you may want to move the source code to some location more in keeping with your procedures and where your lisp expects to find new packages. Then:

• Usage
  

  (ql:quickload :cldoc)
  
  (cldoc:extract-documentation 
        'cludg:html 
        "/home/sabra/projects/lisp-doc/document-tools/docs/cldoc/" 
       (asdf:find-system :hunchentoot) 
        :table-of-contents-title "Hunchentoot by Cldoc")
  

  Notice the asdf:find-system call.

  Unfortunately, running it against hunchentoot generates an error message about The variable http-moved-temporarily is unbound. [Condition of type unbound-variable]

  On the other hand, running it against postmodern was successful.

  (cldoc:extract-documentation 
        'cludg:html 
        "/home/sabra/projects/lisp-doc/document-tools/docs/cldoc/" 
       (asdf:find-system :postmodern) 
        :table-of-contents-title "Postmodern by Cldoc")
  

  This will generate an index.html file which lists separate html files for each source code file and an alphabetical index.

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	Yes, name of source-code files
  Index:	alphabetical	Organization	file,class,method,function,macro
  Designate Target Directory:	Yes	Multipage:	Yes
  Export Formats	html (See below)	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	Yes
  External Functions:	Yes, but not noted as external	Internal Functions:	Yes but not noted as internal
  Macros:	Yes (shows params)	Generic Functions:	Yes, flagged as generic, methods are explicitly set out separately
  Class Info:	Parents, initarg,accessors	Slot Accessors:	Yes, in class summary
  Special Variable Values:	Name only	Conditions:	No
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  • Export Formats
    The generated html would have been good xhtml 1.0 Strict except for Missing xmlns attribute for element html. The value should be: http://www.w3.org/1999/xhtml

Return to Top Return to Summary Table

• In Quicklisp
  

• Author
  

• Author Email
  

• License Info
  

• Software Version
  

• Homepage
  https://bitbucket.org/eeeickythump/clod/ http://lists.gnu.org/archive/html/emacs-orgmode/2010-03/msg00043.html

• Summary
  Clod generates a single emacs org-mode file, which can be gigantic and does take a substantial amount of time for org-mode in emacs to parse and export. In fact, my midsized test package triggered out of space errors for some regex function in org-mode when I tried to generate a pdf version of the documentation. Running it on hunchentoot generated a 306k org file with a resulting 736k xhtml file.

• Usage
  

  (clod:DOCUMENT-PACKAGE 'hunchentoot "/home/sabra/projects/lisp-doc/document-tools/docs/clod/hunchentoot.org")
  

• Installation Notes
  Note: Clod did not load on my macbook. It did load on my linux box.

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	class,variable,macro,functions
  Index:	No	Organization	External classes,constants, variables,macros,functions,internal classes, constants,variables,macros,functions,alphabetical index
  Designate Target Directory:		Multipage:	No
  Export Formats	org-mode	Show Dependencies:	No
  Show Uses:	Yes	Show Used By:	Yes
  Generation Date:	Yes
  External Functions:	Yes (Shows parameters)	Internal Functions:	Yes
  Macros:	Yes	Generic Functions:	Yes
  Class Info:	parent, precedence list,direct subclasses, description, direct slots, indirect slots,	Slot Accessors:	initial value, initargs
  Special Variable Values:	Yes	Conditions:	Not noted as such
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

Return to Top [[Full-Manual-Generators][Return to Summary Table]

• In Quicklisp: Yes
  

• Author: Didier Verna
  

• Author Email
  

• License Info: GPL
  

• Software Version
  

• Homepage: http://www.lrde.epita.fr/~didier/software/lisp/misc.php
  

• Summary
  

  Declt has now made it to 1.0 release.

  A lot of things have changed since the previous version, sometimes in a backward-incompatible way. Many more items are documented (including, as you have recently seen, method combinations). In addition to the reference manual, generated by Declt itself, there is now a real user manual.

  Declt is SBCL-only, requires ASDF 3 and Texinfo 4 but generates code that is compatible with Texinfo 5. Also, beware, I've deleted the old repository and moved the project to GitHub. Below is a more precise description of what Declt currently does.

  Declt (pronounce "dec'let") is a reference manual generator for Common Lisp libraries. It works by loading an ASDF system and introspecting its contents. The generated documentation contains the description for the system itself and its components (modules and files), the packages defined in that system and the definitions found in those packages.

  Exported and internal definitions are listed separately. This allows the reader to have a quick view on the library's public API. Within each section, definitions are sorted lexicographically.

  In addition to ASDF system components and packages, Declt documents the following definitions: constants, special variables, symbol macros, macros, setf expanders, compiler macros, functions (including setf ones), generic functions and methods (including setf ones), method combinations, conditions, structures, classes and types.

  The generated documentation includes every possible bit of information that introspecting can provide: documentation strings, lambda lists (including qualifiers and specializers where appropriate), slots (including type, allocation and initialization arguments), definition source file etc.

  Every documented item provides a full set of cross-references to related items: ASDF component dependencies, parents and children, classes direct methods, super and subclasses, slot readers and writers, setf expanders access and update functions etc.

  Finally, Declt produces exhaustive and multiple-entry indexes for every documented item.

  Reference manuals are generated in Texinfo format (compatible, but not requiring Texinfo 5). From there it is possible to produce readable / printable output in info, HTML, PDF, DVI and PostScript with tools such as makeinfo, texi2dvi or texi2pdf.

  The Declt reference manual is the primary example of documentation generated by Declt itself.

  Because declt generates texi files, you are required to use programs like texi2pdf or texi2html to generate other formats.

• Usage
  

  (ql:quickload :com.dvlsoft.declt)
  (com.dvlsoft.declt:declt 'postmodern :VERSION "201209091" :AUTHOR "Marijn Haverbeke" :EMAIL "marijnh@gmail.com"  :TEXI-FILE
  "/Users/sabra/data/lisp/document-tools/docs/declt/postmodern.texi")
  

  You would then need to run something else such as:

  texi2html --split node postmodern.texi
  

  In order to generate the document format you really want. Version 1.0b14 also provides a :DECLT-NOTICE keyword argument that gives you control on the "automatically generated by Declt" notice that appears in the reference manuals.

• Installation Notes
  No problems

• Error Notes
  I did have a couple of error messages running declt on hunchentoot and cl-postgres. Those seem to be fixed in the version 1.0b14.

• Generated Information
  

  Generated Information

  Author:	Yes You can specify them in the call to the document generator or it will default to what is in the system definition	Author Email:	Yes You can specify them in the call to the document generator or it will default to what is in the system definition
  License Info:	Yes if defined in the call to declt. :BSD :GPL :MIT :LGPL	Software Version:	Yes, but must be explicitly stated
  Homepage:	No	Table of Contents:	System, Module, Files, Packages, Definitions, and Indexes
  Index:	Yes	Organization	See below
  Designate Target Directory:	Yes	Multipage:	Yes, See Below
  Export Formats	Texi. See Below	Show Dependencies:	Yes
  Show Uses:	No	Show Used By:	No
  Generation Date:	Yes
  External Functions:	Yes (Shows parameters) states package and source code filename	Internal Functions:	Yes (Shows parameters) states package and source code filename
  Macros:	Yes (Shows parameters) states package and source code filename	Generic Functions:	Yes (Shows parameters) states package and source code filename
  Class Info:	Limited states package and source code filename	Slot Accessors:	Yes documented as generic functions
  Special Variable Values:	Yes to names, no to values	Conditions:	Yes, They are indexed in the Data Types Section
  Package Info:	Yes	General Notes:	No
  Installation Notes:	No	Markup Language:	No, but being worked on
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  • Organization:
    System, Modules, Files, Packages, Definitions and several index

    The system page gives the name, desription, dependencies (the only program that shows dependencies), the source directory, and the installation directory. I don't yet see a difference between the source directory and the installation directory.

    The modules page gives the name of separate modules in the package. Each module has its own page which lists its location and its component files.

    The files page index lists the different files in the package. Each separate page for each file shows the parent module, the location, the exported definitions, the internal definitions, and links to those. The link to the source code file location did not always work.

    Each symbol lists the package and file that the source code is in.

  • Multipage: Yes*
    Note that you are passing that argument to texi2html or text2pdf outside of lisp. For example, texi2html –split node postmodern.texi
  • Export Formats: Texi
    You then need to run other programs to convert from texi format to your desired format (e.g. pdf, html, info). Note that some of those conversion programs convert to html, but not valid xhtml
  • Show Dependencies: Yes
    Declt is the only package to show dependencies. (Other packages show uses.)
  • Package Info: Yes
    For example, the package info for postmodern noted both postmodern and postmodern-system. Postmodern-system was noted as using common-lisp and asdf. Postmodern was noted as using cl-postgres, closer-common-lisp and s-sql.

Return to Top Return to Summary Table

• In Quicklisp: Yes
  

• Author: Dr. Edmund Weitz
  

• Author Email
  

• License Info :BSD
  

• Software Version
  

• Homepage: http://weitz.de/documentation-template/
  

• Summary
  Tested: Failed. However, manually going into document-template/output.lisp and changing "escape-string-iso-8859" to "cl-who:escape-string-iso-8859-1" fixed the initial problem.

• Usage
  

  (ql:quickload :documentation-template)
  (documentation-template:create-template
  'document-test1 :target #p"/home/sabra/quicklisp/local-projects/document-test1/docs/documentation-template/document-test1.xhtml" :subtitle
  "Document Tool Testing"  )
  

  throws an error about: The function DOCUMENTATION-TEMPLATE::ESCAPE-STRING-ISO-8859 is undefined.

  As noted in the summary, this can be fixed, but preferably should be fixed upstream.

• Installation Notes
  Required Editing to the source code: Manually go into document-template/output.lisp and change "escape-string-iso-8859" to "cl-who:escape-string-iso-8859-1".

• Generated Information
  If you have seen Dr. Weitz documentation, you know what this looks like.

  Generated Information

  Author:	No	Author Email:	No
  License Info:	Defaults to BSD. You must edit	Software Version:	Defaults to 0.1 You must edit
  Homepage:	Defaults to Dr. Weitz page. You must edit.	Table of Contents:	Yes (Alphabetical listing of all symbols)
  Index:	No	Organization	Basically a dictionary of all symbols in the package
  Designate Target Directory:	Yes	Multipage:	No
  Export Formats	single page html (not valid xhtml)	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	Yes
  External Functions:	Yes (Shows parameters) Not broken out from rest of symbol list. No indication of external or internal	Internal Functions:	Yes (Shows parameters) Not broken out from rest of symbol list. No indication of external or internal
  Macros:	Yes Not broken out from rest of symbol list. No indication of external or internal	Generic Functions:	Yes Generic functions names and document strings are followed by the defined methods for that generic function and their specified argument types.
  Class Info:	Partly Symbols in the symbol list which are classes are noted as such, but it does not indicate slots, accessors or other items connected to that class.	Slot Accessors:	No. Accessors to conditions are noted, but not accessors to classes
  Special Variable Values:	Names yes, values no	Conditions:	Yes, but just with all the other functions
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

Return to Top Return to Summary Table

• In Quicklisp: No
  

• Author: Nikodemus Siivola
  

• Author Email
  

• License Info
  

• Software Version
  

• Homepage:http://nikodemus.github.com/sb-texinfo/
  

• Summary
  Converts docstrings for inclusion in a texinfo manual. The texinfo manual can be edited prior to inclusion of the docstrings or post-inclusion. It can then itself be exported to html, pdf or info formats.

• Usage
  To get the source

  git clone git://github.com/nikodemus/sb-texinfo.git
  

  Then create the includes and generate the base package for e.g., hunchentoot, with just the docstrings:

  (generate-includes
  "/home/sabra/quicklisp/local-projects/sb-texinfo/doc/include/"
  (list :hunchentoot) :base-package :hunchentoot)
  
  (document-package :hunchentoot :output-file
  "/home/sabra/quicklisp/local-projects/sb-texinfo/doc/hunchentoot.texinfo")
  

  Make sure that the style.css file is where you want it, then run your favorite texi export programs. E.g.

  makeinfo --html --no-split --css-include=style.css
  makeinfo --no-split huchentoot.texinfo
  texi2dvi hunchentoot.texinfo
  pdftex hunchentoot.texinfo
  

• Installation Notes
  

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	Introduction, Dictionary, Function Index, Variable Index, Type Index
  Index:	Function Index, Variable Index, Type Index	Organization	Introduction, Dictionary, Function Index, Variable Index, Type Index
  Designate Target Directory:	Yes	Multipage:	Depends on conversion program used from texinfo
  Export Formats	texinfo. See below	Show Dependencies:	No
  Show Uses:	No	Show Used By:	No
  Generation Date:	No
  External Functions:	Yes (Shows parameters) no indication as to what function is internal and what function is external	Internal Functions:	Yes (Shows parameters) no indication as to what function is internal and what function is external
  Macros:	Yes Macros are labeled as such, but simply included with the other functions and methods	Generic Functions:	Yes labeled as such, but simply included with the other functions and methods
  Class Info:	class precedence list, slots, docstrings	Slot Accessors:	Yes
  Special Variable Values:	Names only	Conditions:	Yes Conditions are labeled but not broken out separately other than as a listing in the Type Index together with classes.
  Package Info:	No	General Notes:	Only what is in the asdf file
  Installation Notes:	No	Markup Language:	Texinfo
  Generate UMI:	No	Statistics:	No
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  • Export Formats: texinfo
    Texinfo can be converted into other formats, e.g. pdf, html. Note that some of the conversion tools generate valid html but not valid xhtml.

Return to Top Return to Summary Table

• In Quicklisp: Yes
  

• Author: Gary Warren King
  

• Author Email: gwking@metabang.com
  

• License Info: MIT
  

• Software Version
  

• Homepage: http://common-lisp.net/project/tinaa/
  

• Summary
  With its indexes and table of contents, Tinaa is possibly the easiest package in terms of actually finding things from the standpoint of different categories of items. Tinaa has the second most complete set of different types of items (second only to Manifest). While most packages satisfy themselves with exported functions, variables and macros, Tinaa provides additional information on generic functions, slot accessors, classes, conditions and uses.

  As a minor item of interest, Tinaa provides a count of the number of total symbols and number of exported symbols, but does not break those statistics down into the specific types of symbols.

  Tinaa has a separate page for each symbol, with both table of contents and separate indexes for class, conditions, variable, function, macro, symbol, and permuted. Tinaa can show just external symbols or external and internal symbols.

  Tinaa does not note the name of the author, the license type or the description of the package on the index page.

  • Wish List
    
    • Specify Author, license, version information.
      
    • Accept additional text files and a user-specified css file.
      
    • Show which packages use this package (used-by)
      

• Usage
  

  (ql:quickload :tinaa)
  (tinaa:document-system 'package 'document-test1  
                         "/path/to/desired/directory/")
  

• Installation Notes
  

• Error Messages
  Running Tinaa against cl-postgres generated the following warning:

  WARNING: unsupported DOCUMENTATION: type T for object of type SB-PCL::CONDITION-DIRECT-SLOT-DEFINITION

• Generated Information
  

  Generated Information

  Author:	No	Author Email:	No
  License Info:	No	Software Version:	No
  Homepage:	No	Table of Contents:	Yes
  Index:	Class, Variable, Function, Macro, Symbol, Permuted	Organization	Class, Variable, Function, Macro
  Designate Target Directory:	Yes	Multipage:	No
  Export Formats	html (not valid xhtml)	Show Dependencies:	No
  Show Uses:	Yes	Show Used By:	No
  Generation Date:	Yes
  External Functions:	Yes The individual page for each function shows parameters. The parameters are not shown on the table of contents or index pages	Internal Functions:	Yes The individual page for each function shows parameters. The parameters are not shown on the table of contents or index pages
  Macros:	Yes	Generic Functions:	Yes Shows the number of methods and the inputs for those methods
  Class Info:	Yes default initargs, slots, direct method and other methods and whether it a metaclass for other classes	Slot Accessors:	Yes
  Special Variable Values:	Yes	Conditions:	Yes. But not inherited conditions. See Below
  Package Info:	No	General Notes:	No
  Installation Notes:	No	Markup Language:	No
  Generate UMI:	No	Statistics:	Yes - # Total Symbols, # External Symbols
  What Calls What:	No	Interfaces with Unit Testing?	No
  Flags Missing Functions:	No	Accept External File Input:	No

  • Index: Yes -
    Indexes by Class, Variable, Function, Macro, Symbol and Permuted Symbol Indexes A permuted index includes each n-word entry up to n times, at points corresponding to the use of each word in the entry as the sort key. For example, a symbol FOO-BAR would occur twice, once under FOO and BAR. This allows you to use any word in th symbol's name to search for that symbol.
  • Conditions: Yes - But not always
    Tinaa did not show the database-connection-error, database-error or sql-error in postmodern. It did show those errors in cl-postgres which is used by postmodern.

Return to Top Return to Summary Table

• Author: Alex Plotnick
  

• Homepages: http://pages.cs.brandeis.edu/~plotnick/clweb/
  https://github.com/plotnick/CLWEB

  git clone git://github.com/plotnick/clweb.git
  

Return to Top Return to Summary Table

• Author: Roy Turner
  

• Homepages: http://context.umcs.maine.edu/software/LPLisp/ (Work only with Allegro?)
  http://www.umcs.maine.edu/research/features/lit-prog-lisp.html

Return to Top Return to Summary Table

• Homepage: Defdoc slideshow
  

Return to Top Return to Summary Table

• Homepage: http://orgmode.org
  

• Sample of using orgmode for literate programming (R not lisp)