* literate programming
@ 2004-07-25 17:59 Andy Wingo
2004-07-26 13:06 ` Linas Vepstas
0 siblings, 1 reply; 9+ messages in thread
From: Andy Wingo @ 2004-07-25 17:59 UTC (permalink / raw)
Hey folks,
I wrote an article recently about literate programming in guile. The URL
is here (sorry, it's a bit long):
http://ambient.2y.net/wingo/archives/2004/07/25/literate-programming-with-guile-lib
The guile-lib that the article refers to is only in my branch, at the
moment; it will make it upstream soon.
Any comments would be appreciated.
--
Andy Wingo <wingo@pobox.com>
http://ambient.2y.net/wingo/
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-25 17:59 literate programming Andy Wingo
@ 2004-07-26 13:06 ` Linas Vepstas
2004-07-26 13:23 ` Nic Ferrier
2004-07-26 13:28 ` Andy Wingo
0 siblings, 2 replies; 9+ messages in thread
From: Linas Vepstas @ 2004-07-26 13:06 UTC (permalink / raw)
Cc: Guile Users
On Sun, Jul 25, 2004 at 06:59:54PM +0100, Andy Wingo was heard to remark:
> Hey folks,
>
> I wrote an article recently about literate programming in guile. The URL
> is here (sorry, it's a bit long):
>
> http://ambient.2y.net/wingo/archives/2004/07/25/literate-programming-with-guile-lib
What happens if one fails to document each and every variable?
How do you tell apart other usages of "..." ?
I use something similar to eguile, it embeds scheme into html,
<html><body>Howdy <?scm (do-stuff "<h1>more markup</h1>") ?></body></html>
Sounds incompatbile with the texinfo module.
I'd like to see documentation set off with ;; (double semicolon, to
distinguish from single semicolon). Or maybe ;! or ;-- or some other
unique setoff.
And what about "doxygen"? It works really really well for a half-dozen
other languages and styles ... can it be extended for guile?
http://www.stack.nl/~dimitri/doxygen/
--linas
--
pub 1024D/01045933 2001-02-01 Linas Vepstas (Labas!) <linas@linas.org>
PGP Key fingerprint = 8305 2521 6000 0B5E 8984 3F54 64A9 9A82 0104 5933
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-26 13:06 ` Linas Vepstas
@ 2004-07-26 13:23 ` Nic Ferrier
2004-07-29 9:22 ` Andy Wingo
2004-07-26 13:28 ` Andy Wingo
1 sibling, 1 reply; 9+ messages in thread
From: Nic Ferrier @ 2004-07-26 13:23 UTC (permalink / raw)
Cc: Guile Users
linas@linas.org (Linas Vepstas) writes:
> On Sun, Jul 25, 2004 at 06:59:54PM +0100, Andy Wingo was heard to remark:
> > Hey folks,
> >
> > I wrote an article recently about literate programming in guile. The URL
> > is here (sorry, it's a bit long):
> >
> > http://ambient.2y.net/wingo/archives/2004/07/25/literate-programming-with-guile-lib
>
> What happens if one fails to document each and every variable?
>
> How do you tell apart other usages of "..." ?
>
> I use something similar to eguile, it embeds scheme into html,
> <html><body>Howdy <?scm (do-stuff "<h1>more markup</h1>") ?></body></html>
> Sounds incompatbile with the texinfo module.
>
> I'd like to see documentation set off with ;; (double semicolon, to
> distinguish from single semicolon). Or maybe ;! or ;-- or some other
> unique setoff.
>
> And what about "doxygen"? It works really really well for a half-dozen
> other languages and styles ... can it be extended for guile?
>
> http://www.stack.nl/~dimitri/doxygen/
Aubrey Jaffer has got an SLIB based texinfo generator that works
really well:
http://swissnet.ai.mit.edu/~jaffer/slib_4.html#SEC86
It's very similar to doxygen.
Nic
http://www.tapsellferrier.co.uk
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-26 13:06 ` Linas Vepstas
2004-07-26 13:23 ` Nic Ferrier
@ 2004-07-26 13:28 ` Andy Wingo
2004-07-26 13:34 ` Andy Wingo
2004-07-27 3:30 ` Linas Vepstas
1 sibling, 2 replies; 9+ messages in thread
From: Andy Wingo @ 2004-07-26 13:28 UTC (permalink / raw)
Cc: Guile Users
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 <wingo@pobox.com>
http://ambient.2y.net/wingo/
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-26 13:28 ` Andy Wingo
@ 2004-07-26 13:34 ` Andy Wingo
2004-07-27 3:30 ` Linas Vepstas
1 sibling, 0 replies; 9+ messages in thread
From: Andy Wingo @ 2004-07-26 13:34 UTC (permalink / raw)
On Mon, 2004-07-26 at 14:28 +0100, Andy Wingo wrote:
> Did you look at the docs at http://ambient.2y.net/wingo/guile-lib/ ?
Whoops, mistyped:
http://ambient.2y.net/wingo/software/guile-lib/
--
Andy Wingo <wingo@pobox.com>
http://ambient.2y.net/wingo/
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-26 13:28 ` Andy Wingo
2004-07-26 13:34 ` Andy Wingo
@ 2004-07-27 3:30 ` Linas Vepstas
2004-07-29 9:18 ` Andy Wingo
1 sibling, 1 reply; 9+ messages in thread
From: Linas Vepstas @ 2004-07-27 3:30 UTC (permalink / raw)
Cc: Guile Users
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!) <linas@linas.org>
PGP Key fingerprint = 8305 2521 6000 0B5E 8984 3F54 64A9 9A82 0104 5933
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-27 3:30 ` Linas Vepstas
@ 2004-07-29 9:18 ` Andy Wingo
0 siblings, 0 replies; 9+ messages in thread
From: Andy Wingo @ 2004-07-29 9:18 UTC (permalink / raw)
Cc: Guile Users
Hi Linas,
On Mon, 2004-07-26 at 22:30 -0500, Linas Vepstas wrote:
> On Mon, Jul 26, 2004 at 02:28:13PM +0100, Andy Wingo was heard to remark:
> > > How do you tell apart other usages of "..." ?
> >
> > Pardon?
>
> How do you tell apart quoted strings from documentation?
Instead of analyzing the source syntactically, it analyzes the scheme
objects in a module.
Guile associates documentation with objects ("objects" in the general
sense of value + location) via the `documentation' object property.
Procedures are a special case: if the first element of the source list
after the formals is a string, and there are more elements after that,
the string is considered to be documentation for the object.
See (ice-9 documentation) to see exactly how it's done.
> > > I use something similar to eguile, it embeds scheme into html,
> > > <html><body>Howdy <?scm (do-stuff "<h1>more markup</h1>") ?></body></html>
>
> The above code snippet is an example of the kind of scheme code that I
> write.
That's cool.
(Although if you haven't seen it yet, SXML has some nice ways to embed
code in XML-type documents, either via quasiquotation or via
domain-specific XML vocabularies, which are then processed with
`pre-post-order'. See
http://ambient.2y.net/wingo/software/guile-lib/index.scm for an example.
When coupled with SSAX, it lets users write "normal-looking" HTML, and
then you can do your programmatic things to make
"<html><body>Howdy <person/></body></html>" do what you want to do.)
> > I'm not interested in preprocessing some kind of file -- the
>
> You may not be interested, but for me, that is all that I do:
Perhaps I wasn't explaining myself clearly either. I am interested in a
system to document guile modules. Modules are declarative, not
functional. (A report is functional.) Such a system needs to look at the
objects exported by the module, describe them, and describe the module
as a whole.
Embedding scheme into a web page is a different problem domain.
> > The preprocessing model sounds pretty wierd, if you ask me. But even if
>
> I can't begin to imagine why you say that.
Because we're talking about two different things, apparently ;) It would
be strange to make the module loader preprocess a file before it could
get to the bindings. But that's not what you're trying to do.
> > you turn it the other way around, where HTML is embedded in scheme,
>
> Acck. No, that absolutely, royally sucks, and I speak from experience.
[...]
> no mere mortal should have to hack scheme just to add "thank you" to
> the bottom of a web page.
Oh, I'm with you here. A report templating engine is different from a
module documentation system.
> It is a lot easier to give them HTML
> to play with, with some teensy-weensy amount of embedded scheme.
Consider also a custom vocabulary, coupled with (sxml transform)
(written by you, of course). Then there's no scheme at all, only some
funny tags that they can use.
> > 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.
Perhaps by this point we understand each other.
But I did want to mention that I wrote a browser whose native format is
stexinfo. I'll write something about help in a graphical application
later, but to get an idea,
http://ambient.2y.net/wingo/tmp/texinfo-browser.png.
> 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?
(help) and the repl, putting it into a graphical browser like the one
shown above, making a rich development environment (like emacs
itself)...
Cheers,
--
Andy Wingo <wingo@pobox.com>
http://ambient.2y.net/wingo/
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-26 13:23 ` Nic Ferrier
@ 2004-07-29 9:22 ` Andy Wingo
2004-07-29 10:00 ` Nic Ferrier
0 siblings, 1 reply; 9+ messages in thread
From: Andy Wingo @ 2004-07-29 9:22 UTC (permalink / raw)
Cc: Guile Users
On Mon, 2004-07-26 at 14:23 +0100, Nic Ferrier wrote:
> Aubrey Jaffer has got an SLIB based texinfo generator that works
> really well:
>
> http://swissnet.ai.mit.edu/~jaffer/slib_4.html#SEC86
True.
But why syntactically parse a file when guile has all of the information
already, at runtime? Indeed, it has more information -- the type of
variables (including classes and methods) regardless of how they were
defined, and the complete export list of a module (so you can be sure
you're documenting the whole thing).
Aside from that, looking at texinfo at runtime isn't so nice. Better if
it's made into text, like the output of info. (texinfo) will parse it,
(texinfo plain-text) will render the docs to text, so you can call
`help' on an object. Also, (gnome contrib texinfo-buffer) will render it
to a GtkTextBuffer, so you can read it online, even if some of the docs
were programmatically constructed *at runtime* (certainly the case for
systems that dynamically load plugins).
Regards,
--
Andy Wingo <wingo@pobox.com>
http://ambient.2y.net/wingo/
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literate programming
2004-07-29 9:22 ` Andy Wingo
@ 2004-07-29 10:00 ` Nic Ferrier
0 siblings, 0 replies; 9+ messages in thread
From: Nic Ferrier @ 2004-07-29 10:00 UTC (permalink / raw)
Cc: Guile Users
Andy Wingo <wingo@pobox.com> writes:
> On Mon, 2004-07-26 at 14:23 +0100, Nic Ferrier wrote:
> > Aubrey Jaffer has got an SLIB based texinfo generator that works
> > really well:
> >
> > http://swissnet.ai.mit.edu/~jaffer/slib_4.html#SEC86
>
> True.
>
> But why syntactically parse a file when guile has all of the information
> already, at runtime? Indeed, it has more information -- the type of
> variables (including classes and methods) regardless of how they were
> defined, and the complete export list of a module (so you can be sure
> you're documenting the whole thing).
>
> Aside from that, looking at texinfo at runtime isn't so nice. Better if
> it's made into text, like the output of info. (texinfo) will parse it,
> (texinfo plain-text) will render the docs to text, so you can call
> `help' on an object. Also, (gnome contrib texinfo-buffer) will render it
> to a GtkTextBuffer, so you can read it online, even if some of the docs
> were programmatically constructed *at runtime* (certainly the case for
> systems that dynamically load plugins).
Ah I see, your system is dynamic.
Like the emacs manual says, I think dynamic, runtime documentation
probably has a different scope to doc for a manual.
I like your idea, it's neat.
Nic
_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2004-07-29 10:00 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2004-07-25 17:59 literate programming Andy Wingo
2004-07-26 13:06 ` Linas Vepstas
2004-07-26 13:23 ` Nic Ferrier
2004-07-29 9:22 ` Andy Wingo
2004-07-29 10:00 ` Nic Ferrier
2004-07-26 13:28 ` Andy Wingo
2004-07-26 13:34 ` Andy Wingo
2004-07-27 3:30 ` Linas Vepstas
2004-07-29 9:18 ` Andy Wingo
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).