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
_______________________________________________
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
