Cody, I set up a Wiki page for the documentation project. http://wiki.alu.org/Gardeners_Documentation
Feel free to go and add any of your findings there. David Aue -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Cody Koeninger Sent: Thursday, December 15, 2005 9:39 PM To: Tending the Lisp Garden Subject: [Gardeners] Report - comparison of documentation tools (long) Here's my more-or-less stream of consciousness notes on installing and using albert and cldoc. Let me know if anyone has an idea on standardized format or location for these kind of things. Comparison of Common Lisp Documentation Tools Albert http://albert.sourceforge.net vs CLDOC http://common-lisp.net/project/cldoc 1. Summary: I like CLDOC more; it's simple and works on existing code without modification. Needs easier installation, and a convention so that the generated docs have a starting point that tells users "look here first". 2. Installation: Albert debian package, [EMAIL PROTECTED]:~$ sudo aptitude install albert just works CL-USER> (require 'albert) compiles w/2 warnings about APISPEC-BASE:DOC being undefined. CLDOC no stable release yet, no asdf-install. tried anon cvs per the website [EMAIL PROTECTED]:~$ cvs -d :pserver:anonymous:[EMAIL PROTECTED]:/project/cldoc/cvsroot co cldoc got a 'no such repository' error. The tarball snapshot downloaded ok, though. [EMAIL PROTECTED]:~$ tar -xvvzf cldoc.tar.gz [EMAIL PROTECTED]:~$ mv cldoc ~/.sbcl/site/ [EMAIL PROTECTED]:~$ cd ~/.sbcl/systems/ [EMAIL PROTECTED]:~/.sbcl/systems$ ln -s ../site/cldoc/src/cldoc.asd CL-USER> (require 'cldoc) compiles, no warnings. 3. Usage: Albert According to the homepage, "Doc-generation isn't supposed to be easy." Uh-oh. First you have to insert preferences into the asdf file, eg if you wanted to run albert to get documentation on cldoc, cldoc.asd would need to be modified as follows: (defsystem :cldoc :name "cldoc" :author "authorname" :version "0.1.7" :licence "GPL" :properties ((#:author-email . "[EMAIL PROTECTED]") (#:date . "Summer 2005") ((#:albert #:output-dir) . "/home/user/.sbcl/site/cldoc/albert-doc/") ((#:albert #:formats) . ("docbook")) ((#:albert #:docbook #:template) . "book") ((#:albert #:docbook #:bgcolor) . "white") ((#:albert #:docbook #:textcolor) . "black")) . . . . based on fiddling with it, it looks like all of the preferences aside from output-dir, formats, and template can safely be omitted. Once the asdf file is modified, then CL-USER> (load "/home/user/.sbcl/site/cldoc/src/cldoc.asd") CL-USER> (albert:document-systems :cldoc) this spits out a bunch of xml files in docbook format. Jade is necessary to generate html from the docbook. I hate jade, but installed it anyway. [EMAIL PROTECTED]:~/.sbcl/site/cldoc/albert-doc$ jade -d /usr/share/albert/albert.dsl -t sgml /usr/share/albert/xml.dcl book.xml Note that this is different from the Albert howto, which suggests /usr/share/albert/data/albert.dsl This spits out a bunch of html; you must copy the css file and icons into the target directory manually. The docstrings are basically extracted as is; the only way I can see to get more mileage out of them is to insert stuff like " . . [EMAIL PROTECTED] does foo . . ." Most tellingly, I cant see a good way to include an example of usage. CLDOC CL-USER> (use-package :cldoc) CL-USER> (extract-documentation 'html "/home/user/projects/automata/doc" '("/home/user/projects/automata/nfa-sim.lisp")) This works as advertised - extracted my previously-written docstrings and spit out html into the target directory, along with a css file. If a project is written with CLDOC in mind, you can format the docstrings with a bit of DWIMmery for bulleted lists, examples of usage, and paragraphs. e.g if your function & docstring looked like (defun greet (first last) "Prints a greeting to a person identified by: - first : first name, eg Peter - last : last name, eg Seibel Example usage: ;;; (greet \"Peter\" \"Seibel\") ;;; => Howdy, Peter Seibel " (format t "Howdy, ~a ~a" first last)) it will result in http://spaceship.com/~cody/cldoc/hello-cldoc.html#_g5081 You can also pass an asdf system instead of a filename. e.g. CL-USER> (extract-documentation 'html "/home/user/.sbcl/site/cldoc/doc/" (asdf:find-system 'cldoc)) will make cl-doc extract its own documentation. 4. Portability: I was able to compile and successfully use cldoc and albert on linux sbcl, clisp, and cmucl. on windows clisp, cldoc compiles ok but has trouble finding cludg.css; once its in the expected place, it works. I think this is because my lispbox installation is broken, i'd appreciate someone else trying to install and use cldoc on windows. Anyone know of a test harness to make this sort of "try everything on 5 distributions" task easier? 5. Bugs: Albert as previously mentioned, the correct path to albert.dsl, at least on ubuntu, does not include /data/ CLDOC The docs imply that the dest-dir argument to extract-documentation can be nil, resulting in docs generated in the same directory as the source files. When I tried this, I got a "nil is not of type string" error. The current stylesheet has boxes for the links onhover; these boxes get broken up if the text is a decent size. I've had issues with some anchor links not working the first time they're clicked on in firefox; anyone else? _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
