Re: [Chicken-users] egg documentation

[Alejandro Forero Cuervo]

> Here's my suggested syntax, keeping it XML-compliant:
> 
>   <indexentry major="List procedures" [minor="{{append}}"]
>               [bold="yes|no"] [see="other topic"]/>

Hmm, I think this would be very redundant with the following syntax,
which not only is already support, I also find easier to type:

> == List procedures
> 
> ...
> 
> === Append
> 
> ...

As for the “bold” part, I think whether a title for a section is shown
as bold or not should probably depend on its level in the hierarchy
(eg. all ==, === and ==== titles (corresponding to <h2>, <h3> and
<h4>) should be bold, the rest shouldn't).  I'm not sure I understand
the “see="other topic"” functionality so I can't really comment on it,
but I believe it could be provided with other features already present
in the wiki.

Titles in a page can be automatically assembled from this, as
exemplified here:

  http://chicken.wiki.br/stream-ext

As such, I will need more convincing before implementing support for
<indexentry>.  I don't see what it adds that we can't already do.  Ok,
I see that it would allow arbitrary pages to declare sub-topics of a
given topic, but I don't think that should be supported.

> These entries would just be written to a file, and external code
> would then process them to produce index pages or whatever.

I think an index of the entire wiki would be way too big to be useful.
If there's interest in this, I could generate it.  Keep in mind that
the wiki currently has 300+ files.

> Perhaps Alejandro's database of `where symbols in the wiki are
> documented' could also be added to this external file?

I like this idea.  I'll probably do it. :-)

Thanks for the suggestions, Vincent.

Alejo.
http://azul.freaks-unidos.net/