[izpack-devel] Docutils

[Scott Plante]

I offer these points in favor of keeping the doc in HTML:
  * Most of us already know HTML
  * There are free, cross-platform WYSIWYG tools for editing HTML, such 
as NVU / Mozilla composer
  * Even editing the HTML directly with, say, vim, you can see your 
changes immediately by hitting reload in the browser, vs. having to do a 
"compile" step, i.e. converting from reST to HTML.
  * Like reST, it is versioned under SVN, so the doc versions match the 
app versions.
  * For these reason, I believe the barrier for people to send 
improvements is as low or lower than reST.

That being said, I don't thing reST is so bad. The reST tables seem a 
little awkward to edit, but other than that it seems fine. There are 
some  tools for converting the HTML to PDF, but I don't know how their 
output compares to that of the reST generated PDFs. That might be a 
factor in favor of reST.

Scott

-- 
Scott Plante, CTO
Insight Systems, Inc.
(+1) 404 873 0058 x104
splante at insightsys.com
http://zyross.com


Julien Ponge wrote:
> I am relaunching the discussion about that :-)
>
> I am in favour of moving the documentation to DocUtils
> http://docutils.sourceforge.net/docs/
> starting from IzPack 3.11.0
>
> I believe that the reST format that they propose is great because:
> * it is a plain text that is easy to read by itself, and most
> importantly, it is very intuitive
> * it is easy to export to HTML, PDF, ...
> * it should lower the barrier for people to send improvements
> * we can keep it versionned under SVN, so it is better in this regard
> than a wiki.
>
> I have also heard the idea of having the possibility to comment once
> put online. We can think about it latter, but the idea is definitely a
> good one.
>
> I would like to get your point of view about this, so that we can take
> a decision. BTW I am volunteering to make the conversion to reST ;-)
>