[ab] Documentation (was Re: lispbuilder-sdl, done)

[Rudi Schlatte]

On 17.01.2007, at 18:53, Luke Crook wrote:

> Do you know what the CFFI team use to generate their documentation?  
> I like
> their PDF manual.

The source of the cffi manual is in texinfo; I took a quick look and  
they don't seem to use any automated docstring extraction.

Generally, I can recommend texinfo for writing Lisp documentation;  
like all markup languages, it has its good and bad points, but it is  
really simple, has good tool support and the markup language is  
optimized towards documenting Lisp programs, so the shortcuts it  
takes rarely hurt.  Since sbcl went from docbook to texinfo, the  
manual has been kept up-to-date much more consistently.

> Edi Weitz also has a simple documentation generator ( http://weitz.de/
> documentation-template/ ) that runs under Lispworks. It creates  
> documentation
> from the doc strings of exported symbols. I was thinking of hacking  
> cl-markdown
> support into it.

I think that docstring extractors have value because they appeal to  
the hacker mindset ("If I write docstrings, I can reuse them for the  
manual!" / "Whee! Docstrings! The manual is already half-written,  
might as well write some glue text to piece it together...").  So, I  
say go for it!  :)

Cheers,

Rudi