[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: |
Thu, 29 Jul 2004 10:18:13 +0100 |
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 <address@hidden>
http://ambient.2y.net/wingo/