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.