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

[Graham Fawcett]

On 5/30/06, Alejandro Forero Cuervo <address@hidden> wrote:
> > But if this is to be the official documentation source, I'm a little
> > concerned about the lack of semantic cues. [snip]
>
> 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>

That looks fine to me. If you're considering an XML markup, I'd
suggest <procedure lib="library">(length l)</procedure>, where @lib
specifies the library or egg: an empty or missing @lib should indicate
"unknown" and built-ins should explicitly specify lib="library", IMO.
It's verbose, but it's explicit. What do you think?

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

Good question. :-) Procedures, parameters, syntax/macros,
example-code, definitely. I don't think "sample-implementation" really
deserves its own tag; in hindsight, that was a weak argument.

How about a procedure-reference, as in "In the example below, we use
<ref>map</ref>, <ref>sum</ref> and <ref>string-length</th> to
calculate the total length of the strings." That implies an index,
though.

Possibly a "command-line" tag, to show shell sessions? Maybe that's
just <highlight enscript="bash">?

A "smart-link" for SRFI docs would be nice, so one could write
something like, "see ((srfi-1)) for details" and get a proper link to
the official SRFI doc.

That's all I can think of! Really, I think (procedure parameter syntax
example) is an excellent starting point.

Graham