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

[F. Wittenberger]

Am Dienstag, den 30.05.2006, 11:35 -0500 schrieb 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:

So why not xml at the end?  At least as the canonical format.  Not that
I'd especially like xml, but it seems to be the only format, which is
going to live for a long time (since it's making it's way into
legislation already).  (By canonical I mean: I could imagine an
encoding, which plays nicer with text diffs for instance... and store
that encoding in svn.  Or sxml if you want.)

I'd recomment to store some xml.  Then use XML editors (like nvu) if you
like.  And those who like plain text editors more (like me) can get a
wiki style markup on the fly.  This had the added advantage, that the
tagset to be used and the wiki syntax are independent decisions to make.

Example:

this is the template of the askemos wiki 
http://askemos2.tc-mw.de/A849640f672ed0df0958abc0712110f3c/template?template=source
near the top there's a link to view with a wikipedia style wiki markup
(I failed to get the lalr tool parse the original syntax, any help
apreciated ;-)
http://askemos2.tc-mw.de/A849640f672ed0df0958abc0712110f3c/template?media-type=text/wikipedia&template=source
Sure since that' the template it's not exactly a good example of wiki
syntax, since all the xsl and embedded Scheme is droped.

I'm not using the first view for template editing.

The wiki syntax with a more documentation type of page:
http://askemos2.tc-mw.de/A849640f672ed0df0958abc0712110f3c/AskemosServer?media-type=text/wikipedia&template=source
and I'm using the wiki syntax there.

just my $0.02

/Jörg