[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Document formatting in Scheme
On 26 Oct 2001, Riku Saikkonen wrote:
> I'd just like to mention a somewhat different approach for this:
> literate programming. There are programming language-independent tools
> for this (nowebm seems to be a good and simple one), and the markup
> language is usually some form of TeX (which can, of course, be
> converted to HTML, good-quality PostScript, etc.). See the
TeX and HTML are examples of "presentation" markup which
describe a layout of resulting document.
Of course, TeX->HTML converters may be used, and so on,
but (IMHO) "structural" markup is more useful in this context.
If the source code markup highlights its semantic structure
when it is possible to use a number (relatively) independent
stylesheets for generation of output documents,
the situation here is the same as with HTML vs. XML.
TeX was never designed for intermediate representation of HTML
documents, after all...
> I once had an idea of splitting up the documentation for arguments,
> like:
>
> (define (fun <argname> <argdescription> ...)
> <return-value-description>
> <docstring>
> <body of function ...>)
>
I think that it would be nice to have an analyzer for a code formatted
this style.
I do believe that some people would like to document their code like this.
On other hand, after using Mole in some "real life" IT projects I have to say
that the most important thing is to reduce requirements to source code formatting
style. I mean that markup has to be as simple as possible and as sparse as possible.
Also, I've an impression that automated analysis of definitions
may be of great value. Current Mole just makes some attempts to deduct
function name and to distinguish it from a macro...
Is it possible to have one universal formatting style which everyone
would like? I'm afraid this is rhetorical question...
IMHO,
a set of analyzers -> (S)XML -> a set of synthesizers
is one of solutions possible.
Best regards,
Kirill.