[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: literate programming
|
From: |
Linas Vepstas |
|
Subject: |
Re: literate programming |
|
Date: |
Mon, 26 Jul 2004 22:30:36 -0500 |
|
User-agent: |
Mutt/1.5.4i |
On Mon, Jul 26, 2004 at 02:28:13PM +0100, Andy Wingo was heard to remark:
> 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
OK, well, you didn't mention that in the orig email...
Looks good.
> 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?
How do you tell apart quoted strings from documentation?
It looked to me like you were assuming that every other element of a
list must be documentation. Clearly, that wouldn't work very well,
so you must have better heuristics than that.
> > 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.
I must have explained myself poorly.
The above code snippet is an example of the kind of scheme code that I
write. If I passed the above scheme code through your doc generator,
what would it generate as the documentation? Hopefully it will not
assume that "<h1>more markup</h1>" is the subroutine documentation,
because its not, its the argument to my subroutine.
> 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
I'm not sure what you are trying to say here. You may not be
interested, but for me, that is all that I do: I process embedded
scheme markup to generate web pages on the fly. See for example,
"GnoTime", http://gttr.sourceforge.net. The reports are all
generated with embedded scheme.
> 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.
Yes, the point of eguile is to disply html at run-time, but it does so
by preprocessing. I'm not using eguile in GnoTime, I actually had invented
my own home-grown system, but its quite similar. As the user manipulates
the GUI, events are delivered to the scheme processor, which then sucks in
the scheme markup and spits out html on the fly. Its pre-processing,
its live, its runtime, its dynamic, it uses negligable cpu time,
including the overhead of rendering the html to the screen.
> The preprocessing model sounds pretty wierd, if you ask me. But even if
I can't begin to imagine why you say that.
> you turn it the other way around, where HTML is embedded in scheme,
Acck. No, that absolutely, royally sucks, and I speak from experience.
We tried that in GnuCash and it is so totally bass-ackwards, its
absolutely the wrong way to generate reports, its totally unmaintainable.
We have had a handful of people try to change/enhance the reports
over the last four years. There is currently a long email thread
where some poor slob wants to add the words "Thank you for Your
Patronage" to the bottom of the generated invoices, and he is
waist deep in scheme trying to figure out how to do this.
He is not a programmer, much less a scheme programmer. He
is barely a proverbial "power user". It may as well be
assembly code ... no mere mortal should have to hack scheme
just to add "thank you" to the bottom of a web page.
The simple truth is that the vast majority of the programming world
is totally ignorant of scheme. It is a lot easier to give them HTML
to play with, with some teensy-weensy amount of embedded scheme.
They can deal with that.
> you're then comparing texinfo and HTML. I think the former wins
? No, I wasn't. mozilla knows html, it doesn't know texinfo.
There's no comparison. What's texinfo got to do with anything?
> 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.)
This is very nice, but irrelelvant. I know of no web browser that
supports texinfo.
> > 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.
You seem to be talking about two things at once, which I am finding
confusing. Are we talking about embedding scheme, or are we talking
about scheme documentation? Or do you view these as somehow being the
same topic?
> 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.)
I guess I have no clue whatsoever how/why this is useful.
Why is it important for documentation to be accessible at runtime?
Why is it important for guile to know how docs are associated with
variables?
> > 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!
Urgh.
Offtopic, but what's important is having a scheme debugger/execution
visualizer. Unless one is experienced in grokking scheme programs
whole hog, its very very hard to understand what led to an error.
Now *that* is important.
--linas
--
pub 1024D/01045933 2001-02-01 Linas Vepstas (Labas!) <address@hidden>
PGP Key fingerprint = 8305 2521 6000 0B5E 8984 3F54 64A9 9A82 0104 5933