Re: Documentation

From: Alexander Schreiber (als_at_usenet.thangorodrim.de)
Date: 10/04/03 

Date: Sat, 4 Oct 2003 14:44:57 +0200

Rayiner Hashem <gtg990h@mail.gatech.edu> wrote:
>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.

Ok for collecting notes, but not the best choice for full
documentation.

>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.

This one is evil. Its a proprietary binary format which requires
expensive software to work on. Your documentation might contain a lot
more than you imagine (editing history for, information about the
machine the documentation was written on) and you can't rely on it
looking the same on another machine, let alone being readable in a few
years be current software.

>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.

Haven't tried this one.

>4) TeX or LaTeX. Not to familier with this one.

LaTeX ist my tool of choice for doing any serious text writing. There
are several tools to convert source code into ready-to-include LaTeX
code.

>5) HTML pages.

Those can be generated from LaTeX, but you have to limit your use of
LaTeX to keep the gap between generated HTML and dvi/pdf small.

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

Sounds like a job for a small Lisp programm iterating over and dumping
the documentation strings. Thats not exactly what I'd call proper
documentation - but admittedly better than nothing.

Regards,
      Alex. 

-- 
"Opportunity is missed by most people because it is dressed in overalls and
 looks like work."                                      -- Thomas A. Edison

Relevant Pages

  • Re: Format building finding wrong hyphen.cfg file
    ... I'm putting together a list of kpsewhich invocations with an explanation ... When you say `LaTeX', what do you mean, exactly? ... A TeX engine with latex.fmt loaded. ... NAME is the abbreviation used in the kpsewhich documentation ...
    (comp.text.tex)
  • Re: Co-developers wanted: document markup language
    ... documentation, or on software documentation. ... "Everyone" says to just use a Unicode editor. ... In LaTeX, you ... semantic markup). ...
    (comp.lang.python)
  • Re: No sound...?
    ... I had the file on a read-only disc image. ... Layout was done by a ... For some jobs with lots of graphics inclusions, LaTeX works out easier. ... All the tools directory contents have their own documentation included ...
    (uk.comp.sys.mac)
  • Re: expl3, xpackages, mhtools and order (tikz, pst-3d)
    ... using TeXLive...so that means my latex has etex extensions enabled (no ... breqn must be loaded AFTER empheq ... Ordinarily I'd suggest contacting the authors but here the principle author of the mh packages is also somewhat involved in expl3 and xpackages. ... Both cases 2) and 3) are dealt with on the very first page of the breqn documentation. ...
    (comp.text.tex)
  • Re: font families in plain tex
    ... let alone separate documentation. ... TeX and LaTeX are developed by different sets of people. ... format), or, that will then could be ... Use LaTeX or ConTeXt. ...
    (comp.text.tex)