Re: Documentation

From: Thomas F. Bur*** (tfb_at_famine.OCF.Berkeley.EDU)
Date: 10/03/03 

Date: 03 Oct 2003 13:39:05 -0700

Rayiner Hashem <gtg990h@mail.gatech.edu> writes:

> Since people here seem to have a rather unique perspective on development
> tools, I thought I'd ask a question that's been bugging me for awhile. What
> do people here use for code documentation? So far, I can think of the
> following alternatives:
>
> 1) .txt files. I think Linux uses this method.
> 2) Word documents. This one is kind of hard, being a Linux user myself, but
> using a non .doc format makes your documentation rather inaccessible.
> 3) DocBook XML. This is my current format. Its pretty good, but its a pain
> to edit long paragraphs while keeping a nicely indented XML file.
> 4) TeX or LaTeX. Not to familier with this one.
> 5) HTML pages.

I'd recommend LaTeX. It's easy enough to get started using, and
waaaaaaaay better than XML. *TeX's syntax is odd, but XML managed to
out-crap it by a few orders of magnitude. If you want to include code
in your docs, use noweb (a lit programming tool). Using various
tools, you can produce hyperlinked PDFs, and html.

Or, if you want to deliver to MS Word, you can always use OpenOffice. Ick.

> Also, are there any Lisp documentation generators like Doxygen or JavaDoc?

Oh, you're talking about *that* level of documentation? It's easy
enough to write a loop and calls to DOCUMENTATION, to pull this out of
an image, and dump it to a skeleton in whatever system you choose.
Use noweb. 

-- 
           /|_     .-----------------------.                        
         ,'  .\  / | No to Imperialist war |                        
     ,--'    _,'   | Wage class war!       |                        
    /       /      `-----------------------'                        
   (   -.  |                               
   |     ) |                               
  (`-.  '--.)                              
   `. )----'