ooc-dev team mailing list archive

[Fabien Bourgeois <fabien.8@xxxxxxx>]

OOC API isn't already consolidated but, with rock, I think we can say 
that pretty few things will change around current syntax and grammar.

So, can it be interesting to begin to set a *best practices guide* ?
The goal isn't to constrain anybody but I think some little rules can 
help about readability and code reuse.

Can we start to talk about it ? An example can be the Python style guide 
: [http://www.python.org/dev/peps/pep-0008/]. Points that should be 
discussed :

* Indentations
* Line length
* Encodings
* Whitespaces
* Naming conventions
* Comments
* ....

Apart from style guide, I d'like to talk about documentation. Python 
(it's my world, sorry) uses docstring 
[http://www.python.org/dev/peps/pep-0257/]. What's your point of view 
about standardizing how we should document our ooc projects ?

What do you think about using a *markup language* within it and to have 
an 'official' one; as it can automate documentation extraction, as with 
Sphinx for Docs-OOC.

In my mind, if you're allright about using a lightweight markup 
language, there are two good candidates :

 - *Markdown*, and eventually Markdown Extra / extensions 
[http://daringfireball.net/projects/markdown/]
 - RestructuredText 
[http://docutils.sourceforge.net/docs/user/rst/quickref.html]

Although RST and MD have closer syntax, I can say that :

- *RST* is by default more powerfull than MD : tables, ids, classes... 
It have good Python tools to translate into many formats (ODT, PDF, 
XHTML, LaTex, S5, Manpage...); it's extensible and there is Sphinx. 
Furthermore, RST is already used by OOC with the official docs.

- On the other side, MD have many interpreters, and some are written in 
C. It's most widely used and known, and we can easily integrate it with 
the current official website (Dokuwiki and Wordpress plugins are available).

Personally, I incline to RST, maybe from habit, but I also think RST is 
more powerful, more structured than MD. It also have more output formats 
available. Writing an OOC Rst2Xhtml program should be a nice project, as 
it can be largely faster than the official package. As I know it's not a 
priority at all, note that it could be one thing I have to write at work 
in a couple of months from now.