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.
Also, are there any Lisp documentation generators like Doxygen or JavaDoc?
Rayiner Hashem <·······@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! |
/ / `-----------------------'
( -. |
| ) |
(`-. '--.)
`. )----'
···@famine.OCF.Berkeley.EDU (Thomas F. Burdick) writes:
> 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
A simple way of including Lisp code in your LaTeX documents is to use
the listings package:
\usepackage{latexsym,color,listings}
\lstset{
language=Lisp,
basicstyle=\scriptsize\ttfamily,
keywordstyle={},
commentstyle={},
stringstyle={}}
\begin{document}
Include line 13-21 from the file dsp.cl.
\begin{figure}[hf]
\lstinputlisting[first=13,last=21]{dsp.cl}
\caption{\label{fig:brutefdft}Simple CL DFT implementation}
\end{figure}
... bla bla bla ...
--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?
> 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.
Cool.
> 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.
Like like to have documentation at both levels. I find little point in
documenting tiny details in the high-level docs, which can easily get
out of sync, and don't like to put high level stuff in the comments
themselves, because that's a really poor medium for writing.
Rayiner Hashem <·······@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
Hello,
I really like the program "lyx" for editing Latex files. It shows me the
important things like the words, diagrams and citations and none of the
nitty little details like font, style and justification. Once the words
are correct it can generate PDF, HTML, PostScript etc.
--dennis
···@usenet.thangorodrim.de (Alexander Schreiber) writes:
> Rayiner Hashem <·······@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.
I can't even rely on my document looking the same from the time I save
it, close down Word, and start up Word again to re-edit the document.
Grr. (Textbox placement and transparency issues, if anyone cares.)
Of course, I could just keep Word open indefinitely, which I'd do if
it were a Unix application, but Word (and Windows, for that matter)
make this inconvenient in a few ways.
(snippage)
--
Rob St. Amant
http://www4.ncsu.edu/~stamant
> Also, are there any Lisp documentation generators like Doxygen or JavaDoc?
Have you met Albert?
"Albert is a Common Lisp doc-generator, comparable to Javadoc and
Doxygen."
from http://albert.sourceforge.net/
Cheers,
Marcus
Rayiner Hashem <·······@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 think maybe a look at http://docutils.sourceforge.net/ is worthwhile (it's
python, but that shouldn't matter too much -- if you really wanted I'm sure
you could port it witout too much hassle).
'as