Re: [Chicken-users] egg documentation

[Vincent Manis]

On 2008 Feb 17, at 06:15, Alejandro Forero Cuervo wrote:

...
> Documentation for egg foobar should live in the chicken-eggs
> repository, in wiki/foobar, in wiki format with some extensions for
> including semantics.  By this I mean wiki syntax using tags such as
> <procedure> ... </procedure>, from where some semantics can be
> extracted by other tools.  I oppose using XML or some similar format
> (eg. s-expr based format) on the basis that this would make it harder
> for our users to modify.  Raising the bar required for editing, even
> if only  slightly, can greatly reduce the number of contributions.
...

Ivan tasked me with a proposal on the subject of egg documentation,
so let me augment Alejandro's proposal slightly, and then my work
will be done :-).

The idea is to make it easy for users to add tutorials or other  
documents
to an egg.

1. The main author documentation should live in wiki/foobar.
2. Users who want to add documents to the main user documentation should
put them in other files whose names begin with foobar--, with whatever
names they like, e.g., foobar--HOWTO-frobozz.
3. A derived files in HTML is produced, containing a table of contents,
the official foobar documentation, plus any auxiliary documents. This  
file
is placed as index.html at a well-defined place in the egg hierarchy
(doc/foobar.html seems plausible). This HTML file has a comment at the
beginning, reading `automatically-generated file, DO NOT EDIT'.

That's pretty much what I had in mind in my earlier message. Comments?

By the way, on the subject of wiki markup, I'd like to put in a plug
for marking index entries.

-- vincent