lisp-generation-apps-v1

Table of Contents

• 1 Biased review of documentation tools
• 2 Description of Test Setup
• 3 albert
• 4 atdoc
• 5 cl-api
• 6 clod
• 7 declt
• 8 docbrowser
• 9 documentation-template
• 10 gendoc
• 12 manifest
• 13 qbook
• 14 tinaa
• 15 cldoc
• 16 hyperdoc

1 Biased review of documentation tools

• General Discussion
• As of 24 September, 2012, Wikipedia showed 51 different non-lisp document generators. On the same date, Cliki showed 18 lisp documentation tools and I've found 2 more on quicklisp that were not listed in Cliki. For some reason, I decided to compare the lisp documentation tools and put my opinionated comments here. Several no longer seem to be available in world. Others, I could not get to work (either my own fault or bit rot has set in, possibly due to changes in asdf). The last time anyone seemed to look at this issue was back in 2005: See this discussion. This,then, is my probably biased comparison (and wish list). Comments and corrections would be greatly appreciated.
  • I would first note that 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. If you are looking to generate an api of the exported functions, you are going to be looking for something simpler than if you were looking to generate a full manual for on your own software for internal use. Hopefully this review will give you a taste of what is available.
  • 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 program that I am aware of that reads the source code is cldoc. 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 the internal and external api.
  • 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 visualizaions that Doxygen can create. See examples here. 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. That seems like a cross between documentation-template and atdoc in the lisp world. i have not really looked hard at either Doxygen or Sphinx.
  • 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.
• Summary Table
• albert, document-template and hyperdoc are not part of the Summary table below . They are, however, discussed in their own sections below. I could not get Albert to build. I could only get document-template to work after a small editing change. Hyperdoc is sufficiently different that it does not fit well into the comparison.
  • (1) Version 1.0b14 has license terms for BSD, GPL, MIT and LGPL. Version 1.0b13 only has BSD and GPL
  • (2) f -> separate index for functions cl -> classes co -> conditions cs -> constants d -> definitions f -> files g -> generic functions i -> indexes m -> macros mo -> modules pa -> permutations pe -> permutations s -> system sa -> slot-accessors v -> variables
  • (3) is the html or xhtml generated in multiple pages or one giant page?
  • (4) h-> static html, l->latex, i->info, d->docbook,p->pdf,x->xhtml, dh -> dynamic html, texti
  • (5) d-> doc string, s-> slots, m-> direct methods
  • (6) Is there any way to tie the documentation to a testing framework to see if every function has a test?
  • (7) Take text information from external files such as a text summary
  • (8) Shows conditions as functions in the function list. If it is a condition, macro, generic function, there will be a flag to that effect next to the name of the function.
  • (9) You can specify them in the call to the document generator or it will default to what is in the system definition.
  • (10) Single page with sections for constants, variables, classes, conditions, functions and macros which can be folded.
  • (11) The requirement of separate pages needs to be passed to a non-lisp program that manages the texi file. E.g., text2html –split node postmodern.texi
  • (12) Declt only provides limited information here. It only provides the name and the document string, unlike other packages which provide slots, methods, etc.
• Wish List
  • 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.
  • 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
  • It would be nice to generate an appendix page showing statistics on the number of each type of symbol.

2 Description of Test Setup

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.

3 albert

Return to Top Return to Summary Table

• In Quicklisp: No
• Author: Stig Erik Sandoe
• Author Email
• License Info: GPL2
• Software Version
• Homepage: http://albert.sourceforge.net/
• Summary
• Quicklisp does not have albert. Attempts to compile it on my systems generate the following error on both my mac and linux systems: :UTF-8 stream decoding error on #<SB-SYS:FD-STREAM the octet sequence #(248 34 10 32) cannot be decoded.
• Usage
• Generated Information
  • Author:
  • Author Email
  • License Info:
  • Software Version
  • Homepage:
  • Table of Contents
  • Index
  • Organization
  • Designate Target Directory
  • Multipage
  • Export Formats
  • Docbook
  • Show Dependencies
  • Generation Date
  • External Functions
  • Internal Functions
  • Macros
  • Generic Functionse
  • Class Info
  • Slot Accessors
  • Special Variable Values
  • Conditions
  • Package Info
  • General Notes
  • Installation Notes
  • Markup Language
  • Generate UMI
  • Show Uses
  • Show Who Uses
  • Statistics
  • What Calls What
  • Interfaces with Unit Testing?
  • Flags Missing Functions
  • Accept External File Input

4 atdoc

Return to Top Return to Summary Table

• In Quicklisp: Yes
• Author: David Lichteblau
• Author Email:
• 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
• Both Mac and Linux Boxes: 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]
  • Both Mac and Linux boxes: 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
  • Author: No
  • Author Email: No
  • License Info: No
  • Software Version: No
  • Homepage: No
  • Table of Contents: No
  • Index: Yes
  • Organization:
  • Designate Target Directory: Yes
  • Multipage: Yes
  • Export Formats: html, tex, info
  • Show Dependencies: No
  • Generation Date: No
  • External Functions: Yes
  • Internal Functions: No
  • Macros: No
  • Generic Functions: No
  • Class Info: Superclass, documented subclasses, slots
  • Slot Accessors: No
  • Special Variable Values: No
  • Conditions: No
  • Package Info: No
  • General Notes: No
  • Installation Notes: No
  • Markup Language: No
  • Generate UMI: No
  • Show Uses: No
  • Show Who Uses: No
  • Statistics: No
  • What Calls What: No
  • Interfaces with Unit Testing? No
  • Flags Missing Functions: No
  • Accept External File Input: No

5 cl-api

Return to TopReturn to 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 both the mac and linux boxes, 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
  • 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: Static html
  • Show Dependencies: No
  • Show Uses: No
  • Show Who Uses: No
  • Generation Date: No
  • External Functions: Yes
  • Internal Functions: No
  • Macros: Yes
  • Generic Functionse: Functions flagged as generic
  • Class Info: Yes
  • Default initargs, slots, the docstring for the class.
  • Slot Accessors: Yes
  • Special Variable Values: Yes
  • Conditions: Yes
  • Package Info: No
  • General Notes:None
  • 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

6 clod

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 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.
• Usage
  • (clod:DOCUMENT-PACKAGE 'document-test1 "/home/sabra/quicklisp/local-projects/document-test1/docs/clod/clod.org")
• Installation Notes
• Note: Clod did not load on my macbook.
• Generated Information
  • Author:
  • Author Email
  • License Info:
  • Software Version
  • Homepage:
  • Table of Contents
  • Index
  • Organization
  • Designate Target Directory
  • Multipage
  • Export Formats: Org-mode
  • Show Dependencies
  • Generation Date
  • External Functions
  • Internal Functions
  • Macros
  • Generic Functionse
  • Class Info
  • Slot Accessors
  • Special Variable Values
  • Conditions
  • Package Info
  • General Notes
  • Installation Notes
  • Markup Language
  • Generate UMI
  • Show Uses
  • Show Who Uses
  • Statistics
  • What Calls What
  • Interfaces with Unit Testing?
  • Flags Missing Functions
  • Accept External File Input

7 declt

Return to TopReturn 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
• As the cliki page states: Declt is a Texinfo reference manual generator for ASDF systems.
  • Declt (Documentation Extractor from Common Lisp to Texinfo) extracts and formats documentation from ASDF systems, including the system itself and its components, the packages defined in the system and definitions like constants, special variables, macros, functions, generic functions and methods, conditions, structures and classes.
  • Reference manuals are generated in Texinfo format which can be subsequently converted into info, HTML, DVI, PostScript or PDF. The generated manuals are fully indexed and provide a complete set of cross-references between documentation elements. For instance, files and packages point to the definitions they provide, and those definitions point back to package and file in which they can be found.
  • 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" :LICENSE :BSD :AUTHOR "Marijn Haverbeke" :EMAIL "marijnh@gmail.com" :TEXI-FILE"/Users/sabra/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.
• 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. Currently available types oare :BSD :GPL :MIT :LGPL. Others on demand.
• Software Version: Yes
• Homepage: No
• Table of Contents: Yes
• The main page will show the System, Modules, Files, Packages, Definitions and Index. The actual table of contents
• Index: Yes
• Organization:
• System, Modules, Files, Packages, Definitions and several index
  • The system page gives the name, description, 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 lists the different files in the package.
• Designate Target Directory: Yes
• 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.
• Show Dependencies: Yes
• Declt is the only package to show dependencies. (Other packages show uses.)
• Generation Date: Yes
• External Functions: Yes
• Internal Functions: Yes
• Macros: Yes
• Generic Functions: Yes
• Class Info: Limited
• Slot Accessors: Slot accessors are generic function so they are documented as such.
• Special Variable Name and Values: Yes to Names, No to values
• Conditions: Yes. They are indexed in the Data Types Section
• 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.
• General Notes: No
• Installation Notes: No
• Markup Language: No, but being worked on. Docstrings are properly escaped for texinof and some work is done to isolate paragraphs based on the presence of blank lines.
• Generate UMI: No
• Show Uses: Yes
• Show Who Uses: No
• Statistics: No
• What Calls What: No
• Interfaces with Unit Testing? No
• Flags Missing Functions: No
• Accept External File Input: No

8 docbrowser

Return to TopReturn 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.
  • 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
  • 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 Who Uses: No
  • Generation Date: No
  • External Functions: Yes (shows parameters)
  • Internal Functions: No
  • Macros: Flagged in the list of functions
  • Generic Functions: Flagged in the list of functions
  • Class Info: 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

9 documentation-template

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've seen Dr. Weitz documentation, you know what this looks like.
  • Author: No
  • Author Email: No
  • License Info: No
  • (The generated document makes reference is to a BSD style license, but that is based on Dr. Weitz's normal packages. You must replace this with the correct information.
  • Software Version: No
  • It generates a package version number, but you must replace this with the correct version number.
  • Homepage: No
  • It generates a download shortcut that refers back to weitz.de, so you must replace this with your intended webpage.
  • 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
  • Show Dependencies: No
  • Show Uses: No
  • Show Who Uses: No
  • Generation Date: Yes
  • External Functions: Not broken out from symbol list
  • There is no indication of what functions are internal and what are external. You must do this for yourself in additional editing.
  • Internal Functions: Not broken out from symbol list
  • There is no indication of what functions are internal and what are external. You must do this for yourself in additional editing.
  • Macros: Partly
  • Macros are noted, but every symbol is in one long alphabetized list
  • Generic Functions: Partly
  • Generic functions are noted, but every symbol is in one long alphabetized list. 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 class slots.
  • Special Variable Values: No
  • Variables and any document string are noted, but not the values they may have had when the documentation was generated.
  • Conditions: Partly
  • Conditions are noted, but every symbol is in one long alphabetized list.
  • Package Info: No
  • General Notes: No
  • Installation Notes: No
  • Markup Language: No
  • You are expected to take the finished product and actually add additional content.
  • Generate UMI: No
  • Statistics: No
  • What Calls What: No
  • Interfaces with Unit Testing? No
  • Flags Missing Functions: No
  • Accept External File Input: No

10 gendoc

Return to TopReturn to 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/lisp/document-tools/docs/gendoc/gendocs-postmodern.html" :css "simple.css") (:apiref :postmodern))
• Installation Notes
• 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
  • Single Page static html
  • Show Dependencies: No
  • Show Uses: No
  • Show Who Uses: 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
  • Installation Notes
  • 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

12 manifest

Return to TopReturn 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 show the most complete set of different types of items. 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
  • 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: Mp
  • 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
  • General Notes
  • 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

13 qbook

Return to TopReturn to Summary Table

• In Quicklisp: Yes
• Author: Edward Marco Baringer
• Author Email
• License Info: BSD
• Software Version
• Homepage: http://common-lisp.net/project/bese/qbook.html
• Summary
• Tested: Failed Description: From the asd file: qbook generates HTML (or LaTeX) formatted code listings of Common Lisp source files. Comments in the source code are rendered as HTML paragraphs, text is rendered in <pre> blocks</pre>. Headings are created by preceding the text of the comment with one or more #\*chars.
  • I have not been able to get qbook to work.
• Usage
  • (ql:quickload :qbook)(asdf:oos 'qbook:publish-op :document-test1 :generator (make-instance 'qbook:html-generator :output-directory "/home/sabra/quicklisp/local-projects/document-test1/docs/qbook/" :title "QBook Documentation for Document Test1"))(asdf:oos 'qbook:publish-op :document-test1 :generator (make-instance 'qbook:latex-generator :output-file "/home/sabra/quicklisp/local-projects/document-test1/docs/qbook/qbook.tex" :title "QBook Documentation for Document Test1"))
• Installation Notes
• Installation was not a problem, usage was.
• Error Notes
• On my test package, the First error message:
  • No initial heading in #P"/home/sabra/quicklisp/local-projects/document-test1/document-test1.asd"
• .
  • Looking at the source code, Headings are created by preceding the text of the comment with one or more #\* chars
  • Ok. So put a comment line preceded by *
  • That generated an error:
  • There is no applicable method for the generic function #<STANDARD-GENERIC-FUNCTION START-POSITION (1)> when called with arguments (*).
• Running qbook on itself on both mac and linux boxes generated the following errors:
  • STYLE-WARNING: redefining ITERATE:GENERATE in DEFGENERIC STYLE-WARNING: redefining BOOK-INDEXES-SORTED (#<STANDARD-CLASS BOOK>) in DEFMETHOD STYLE-WARNING: redefining ALL-CODE-PARTS (#<STANDARD-CLASS BOOK>) in DEFMETHOD STYLE-WARNING: redefining PERMUTATED-GLOBAL-INDEX (#<STANDARD-CLASS BOOK>) in DEFMETHOD STYLE-WARNING: redefining IT.BESE.QBOOK::COMPARE-DESCRIPTOR-NAMES in DEFUN
  • and ending with the following error message:
    • The value NIL is not of type VECTOR. [Condition of type TYPE-ERROR] Restarts: 0: [RETRY] Retry #<STANDARD-CLASS IT.BESE.QBOOK:PUBLISH-OP> on #<SYSTEM "qbook">. 1: [ACCEPT] Continue, treating #<STANDARD-CLASS IT.BESE.QBOOK:PUBLISH-OP> on #<SYSTEM "qbook"> as having been successful. 2: [*ABORT] Return to SLIME's top level. 3: [ABORT] Abort thread (#<THREAD "new-repl-thread" RUNNING {1009AB9B83}>) Backtrace: 0: (IT.BESE.QBOOK::SUBSEQ-FIRST-SENTENCE NIL 180) 1: ((SB-PCL::FAST-METHOD IT.BESE.QBOOK::WRITE-CODE-DESCRIPTOR :AROUND (IT.BESE.QBOOK::DESCRIPTOR T)) ..) 2: (IT.BESE.QBOOK::WRITE-CODE #<IT.BESE.QBOOK::CODE-PART "(defclass ..." {100C3497C3}> #<unavailable argument>) 3: (IT.BESE.QBOOK::PUBLISH ..) 4: (IT.BESE.QBOOK::GENERATE-SECTION ..) 5: ((SB-PCL::FAST-METHOD ITERATE:GENERATE (T IT.BESE.QBOOK:HTML-GENERATOR)) ..) 6: ((SB-PCL::EMF ASDF:PERFORM) #<unavailable argument> #<unavailable argument> #<IT.BESE.QBOOK:PUBLISH-OP (:GENERATOR #) {10033486A3}> #<ASDF:SYSTEM "qbook">) 7: ((SB-PCL::FAST-METHOD ASDF::PERFORM-WITH-RESTARTS :AROUND (T T)) ..) 8: ((LAMBDA () :IN ASDF::PERFORM-PLAN))
  • It generated the index page, but stopped with the above error before generating anything else.
• Generated Information
  • Author:
  • Author Email
  • License Info:
  • Software Version
  • Homepage:
  • Table of Contents
  • Index
  • Organization
  • Designate Target Directory
  • Multipage
  • Export Formats
  • Docbook
  • Show Dependencies
  • Generation Date
  • External Functions
  • Internal Functions
  • Macros
  • Generic Functionse
  • Class Info
  • Slot Accessors
  • Special Variable Values
  • Conditions
  • Package Info
  • General Notes
  • Installation Notes
  • Markup Language
  • Generate UMI
  • Show Uses
  • Show Who Uses
  • Statistics
  • What Calls What
  • Interfaces with Unit Testing?
  • Flags Missing Functions
  • Accept External File Input

14 tinaa

Return to Top Return to Summary Table

• In Quicklisp: Yes
• Author: Gary Warren King
• Author Email:
• 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
  • Author: No
  • Author Email: No
  • License Info: No
  • Software Version: No
  • Homepage: No
  • Table of Contents: Yes
  • Index: Yes - Class, Variable, Function, Macro, Symbol, Permuted
  • Organization: Class, Variable, Function, Generic Function, Macro
  • Designate Target Directory
  • Multipage: Yes
  • Export Formats: Static Html
  • Show Dependencies: No
  • Show Uses: Yes
  • Show Who Uses: 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 Functionse: Yes
  • Shows the number of methods and the inputs for those methods
  • Class Info: Yes
  • Shows default initargs, slots, direct method and other methods and whether it a metaclass for other classes.
  • Slot Accessors
  • Special Variable Values: Yes
  • 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.
  • Package Info: No
  • General Notes
  • Installation Notes
  • 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

15 cldoc

Return to TopReturn 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
• It appears to read the source code to pull the document strings rather than introspecting into the system. The last revision in the version control system seem to be in January 2006. It was not tested.
• Usage
• It seems to require that you pass a list of all the files to cldoc as well as create some specific handlers for macros. See, e.g. from the README file:
  • (in-package :cldoc);; Special cldoc handler(cldoc::define-descriptor-handler DEFINE-STRING-PURGER (form)"string purger"(setf (car form) 'cldoc::define-string-purger)(values nil :restart (list (let ((*print-case* :upcase))(macroexpand-1 form)))))(cldoc::define-descriptor-handler DEFINE-LAMBDA-LIST-PURGER (form)"lambda purger"(setf (car form) 'cldoc::define-lambda-list-purger)(values nil :restart (list (let ((*print-case* :upcase))(macroexpand-1 form)))));; Extract doc.(cldoc:extract-documentation 'cldoc:html \"docu\" '("package.lisp""cludg.lisp""cache-system.lisp""string-parser.lisp""html.lisp"):table-of-contents-title"Common Lisp Universal Documentation Generator")
• Installation Notes
• It does not have a single downloaded file. You need to pull it from the cvs.
• Generated Information
  • Author:
  • Author Email
  • License Info:
  • Software Version
  • Homepage:
  • Table of Contents
  • Index
  • Organization
  • Designate Target Directory
  • Multipage
  • Export Formats
  • Static html
  • Show Dependencies
  • Generation Date
  • External Functions
  • Internal Functions
  • Macros
  • Generic Functionse
  • Class Info
  • Slot Accessors
  • Special Variable Values
  • Conditions
  • Package Info
  • General Notes
  • Installation Notes
  • Markup Language
  • Generate UMI
  • Show Uses
  • Show Who Uses
  • Statistics
  • What Calls What
  • Interfaces with Unit Testing?
  • Flags Missing Functions
  • Accept External File Input

16 hyperdoc

Return to TopReturn to Summary Table

• In Quicklisp: No
• Author: Tobias C Ritweiler
• Author Email
• License Info
• Software Version
• Homepage: http://common-lisp.net/project/hyperdoc/
• Summary
• Not tested - per the website it is not considered to be released yet. The description of hyperdoc on the website is:
  • Hyperdoc is a hypertext documentation support system for Common Lisp, licensed under a MIT-style license. Basically, it takes a symbol and outputs a URL to that symbol's documentation.
  • It's supposed to be used a) by Common Lisp development environments to provide arbitrary documentation look up on key press, and b) by library authors to make their library's documentation conveniently available to users of their library.
• Usage
• Installation Notes
• Generated Information
  • Author:
  • Author Email
  • License Info:
  • Software Version
  • Homepage:
  • Table of Contents
  • Index
  • Organization
  • Designate Target Directory
  • Multipage
  • Export Formats
  • Show Dependencies
  • Generation Date
  • External Functions
  • Internal Functions
  • Macros
  • Generic Functionse
  • Class Info
  • Slot Accessors
  • Special Variable Values
  • Conditions
  • Package Info
  • General Notes
  • Installation Notes
  • Markup Language
  • Generate UMI
  • Show Uses
  • Show Who Uses
  • Statistics
  • What Calls What
  • Interfaces with Unit Testing?
  • Flags Missing Functions
  • Accept External File Input

Date: 2012-09-24 19:46:20 PDT