[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 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,

> 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

Andy Wingo <address@hidden>

reply via email to

[Prev in Thread] Current Thread [Next in Thread]