On 5/30/06, Alejandro Forero Cuervo <[EMAIL PROTECTED]> 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 _______________________________________________ Chicken-users mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
