Re: Documentation (was Re: [Chicken-users] How to use prelude?)

[Alejandro Forero Cuervo]

> But if this is to be the official documentation source, I'm a little
> concerned about the lack of semantic cues. For example, in the snippet
> above, the same markup is used for both the example and the sample
> implementation; and the procedure signature is "weakly marked up"
> using whitespace. Personally, I'd like to see a more explict, semantic
> markup, particularly for key elements like procedure signatures. (I
> assume the syntax is extensible, maybe Alejandro could add some tags
> to address this.)

I will certainly add some tags.  I absolutely agree with you.

I'll probably use a format based in tags (ala XML), something along
the lines of:

    ==== List length

    <procedure>(length l)</procedure>

    Returns the length of list {{l}}.

    <examples>
    (length '(1 . 2))
    => 1.5
    </examples>

I'll probably do this by making it possible to define wiki-specific
tags whose definition is a Scheme function mapping the text between
the opening and closing tag to “lower-level” wiki language.  These
definitions will probably live in a file on the wiki and get executed
by the sandbox egg.

What tags would you suggest?  Examples, procedure, syntax?  Hmm.

Thanks for your suggestions, Graham.  You've raised a very valid
point.

Alejo.
http://azul.freaks-unidos.net/