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

[Graham Fawcett]

On 5/29/06, felix winkelmann <address@hidden> wrote:
> On 5/29/06, Graham Fawcett <address@hidden> wrote:
> >
> > I was just thinking about what's happening now in the Python
> > community. A well-known Python developer dumped all of the official
> > documentation into a Wiki / content management system, and the
> > community is busy filling in gaps, and adding new information.
>
> Actually, Alejandro suggested this already - there is an unofficial manual:
>
> http://wiki.freaks-unidos.net/chicken%20scheme%20manual
>
> Now, I have absolutely no problem with this. There is just one catch: I don't
> want to maintain two versions of the manual, and we definitely need something
> that can be installed locally.

Looking at Alejandro's wiki, it looks like the first issue is easily
resolved: the wiki pages are stored in a subversion repository, and
can be edited either through the Web or via subversion patches. That's
a nice feature.

> Personally, I would suggest that we use
> http://galinha.ucpel.tche.br/coop, since it's internal format can be converted
> relatively easily to/from other formats.

I also like the coop format; however, the current "freaks-manual" uses
a more traditional Wiki format. Here's a snippet, the documentation
for the (conc) procedure.

#<<SNIPPET-END
=== conc

(conc X ...)

Returns a string with the string-represenation of all arguments
concatenated together.

Examples:

<enscript highlight=scheme>
(conc "alejandro" "forero" "cuervo")
=> "alejandroforerocuervo"
</enscript>

{{conc}} could be implemented as:

<enscript highlight=scheme>
(define (conc . args)
 (apply string-append (map ->string args)) )
</enscript>

This procedure is specific of Chicken; other Scheme implementations
might not include it.
SNIPPET-END

This is a fairly standard Wiki markup and is quite simple to learn.
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.)

So, Felix -- local editing is available. Assuming a good wiki->texinfo
procedure, what do you think of the wiki markup?

Graham