[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Chicken-users] egg documentation
From: |
Vincent Manis |
Subject: |
Re: [Chicken-users] egg documentation |
Date: |
Sun, 17 Feb 2008 23:04:01 -0800 |
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
Re: [Chicken-users] egg documentation, Alejandro Forero Cuervo, 2008/02/17
Re: [Chicken-users] egg documentation, Ivan Raikov, 2008/02/17
Re: [Chicken-users] egg documentation,
Vincent Manis <=
- Re: [Chicken-users] egg documentation, Alejandro Forero Cuervo, 2008/02/18
- [Chicken-users] Topics and a main index (was: egg documentation), Tobia Conforto, 2008/02/19
- Re: [Chicken-users] Topics and a main index (was: egg documentation), Vincent Manis, 2008/02/19
- Re: [Chicken-users] Topics and a main index (was: egg documentation), Jim Ursetto, 2008/02/19
- Re: [Chicken-users] Topics and a main index (was: egg documentation), Graham Fawcett, 2008/02/19
- Re: [Chicken-users] Topics and a main index (was: egg documentation), Tobia Conforto, 2008/02/19