On 2/18/07, Quentin Mathé <[EMAIL PROTECTED]> wrote:
Le 18 févr. 07 à 08:17, Yen-Ju Chen a écrit :
> I am playing an io script to generate a document of Etoile project
> based on README.
You mean by parsing the READMEs present in each module?
Yes, it is similar to generate API from comments in source code.
In this way, developers only need to maintain a copy of README
and we can have a update-to-date document automatically.
> The idea is to have an update-to-date document.
> It is understandable that people have less time maintaining the wiki.
> It also solves one of the issues that people have no idea what's
> inside Etoile and the naming.
> In order to make the script work well, the format of README has to
> be unified.
> I think it would be better in structured text which can be converted
> into other format.
> Here are two options I personally like:
> Stx2Any: http://sange.fi/~atehwa/cgi-bin/piki.cgi/stx2any
> ReST: http://docutils.sourceforge.net/rst.html
>
> I like Stx2Any more on its syntax in plain text format, which I think
> is more important.
> Most people read README straight.
I think I largely prefer ReST over other similar markup formats.
I like it because it improves document reading by clearly outlining
sections, subsections, titles etc. (I mean when you read the document
in markup form). In some way, Stx2Any isn't enough verbose for my
taste ;-) All README or INSTALL files I have maintained in Etoile
uses a syntax really close to ReST which should involve almost no
tweaks to become 100% ReST.
Examples are available in /trunk/Etoile/Developer/Templates/
FrameworkTemplate/
I will give it a try.
The basic idea is simply put all the introduction part in README all together,
then use ReST's tools to generate the final HTML.
Yen-Ju
> Since I have less time working on real stuff recently,
> I can go through all the projects and reformat the README into
> structured text
> and finish up the script.
ok. Good idea :-)
Cheers,
Quentin.
_______________________________________________
Etoile-discuss mailing list
[email protected]
https://mail.gna.org/listinfo/etoile-discuss
_______________________________________________
Etoile-discuss mailing list
[email protected]
https://mail.gna.org/listinfo/etoile-discuss
