[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: literate programming
|
From: |
Andy Wingo |
|
Subject: |
Re: literate programming |
|
Date: |
Mon, 26 Jul 2004 14:28:13 +0100 |
Hi Linas,
On Mon, 2004-07-26 at 08:06 -0500, Linas Vepstas wrote:
> What happens if one fails to document each and every variable?
Did you look at the docs at http://ambient.2y.net/wingo/guile-lib/ ? It
puts "[undocumented]" in the body. Of course Guile still knows about the
type, arity, variable name, etc.
> How do you tell apart other usages of "..." ?
Pardon?
> I use something similar to eguile, it embeds scheme into html,
> <html><body>Howdy <?scm (do-stuff "<h1>more markup</h1>") ?></body></html>
I think you're missing the point here. One key thing that makes lisp
good is that you have a rich development environment that's actually
"alive". I'm not interested in preprocessing some kind of file -- the
source is still lisp, and you're still doing the same amount of work,
only that you're doing it in such a way that the user can get to it at
runtime.
> Sounds incompatbile with the texinfo module.
The preprocessing model sounds pretty wierd, if you ask me. But even if
you turn it the other way around, where HTML is embedded in scheme,
you're then comparing texinfo and HTML. I think the former wins
hands-down in the categories of conciseness, relevance of vocabulary to
programming projects, indexing, cross-referencing, and print output.
Texinfo has semantic ways of documenting data; HTML does not. (i.e.
there's no deffn in HTML.)
> I'd like to see documentation set off with ;; (double semicolon, to
> distinguish from single semicolon). Or maybe ;! or ;-- or some other
> unique setoff.
You're talking about a more schmoozy system. That's cool, although less
accessible during runtime. I'm talking about a system where guile knows
how docs are associated with variables. It's more suitable for the
runtime environment, although with some clever processor you could
probably get at the docs this way as well. (And it would be useful for
the myriad of 3rd party packages out there as well.)
> And what about "doxygen"? It works really really well for a half-dozen
> other languages and styles ... can it be extended for guile?
It's static, man. That's boring. That's not why I use lisp!
Regards,
--
Andy Wingo <address@hidden>
http://ambient.2y.net/wingo/