[Scons-dev] New SCons doc toolchain...

[Dirk Bächle]

Hi Gour,

On 09.05.2013 10:33, Gour wrote:

> On Tue, 26 Mar 2013 00:50:07 +0100

> Dirk Bächle <tshortik at gmx.de> wrote:

>

>> [...]

> I settled to use SCons for my PyQt project and was reading the User Manual

> yesterday and e.g. found that the email addresses listed are wrong (e.g.

> users at scons.tigris.org) which led me to check how are docs handled in order to

> know how to contribute some 'patches'.

>

> So, I was a bit surprised that SCons uses Docbook toolchain considering that

> some time ago project switched from SVN to (more pythonic) Mercurial, I wonder

> why not using (more pythonic) reST/Sphinx which, imho, requires less admin

> work and it provides lower-hanging fruit for potential contributors who are

> probably more familiar with reST/Sphinx than Docbook.

>

> Moreover, the current user manual is ~350p and not so complicated to require

> the above-mentioned features.

>

> I hope that you will find this email only as constructive feedback meant to

> improve SCons project by simplifying doc toolchain in order to spend valuable

> time of not-to-big developer's team on more important issues.


thanks a lot for trying out the new doc toolchain. It's still very fresh 
and there's probably a lot of room for improvement...including a rewrite 
to another input format (like asciidoc, reST, whatever).
So, we're very interested in hearing about first impressions from avid 
users like you.

If it were only about creating plain text with some graphics, you're 
right. This could easily be handled by a lot
of other toolchains. However, I'd like you to have a short look over the 
discussion at

   http://www.scons.org/wiki/DeveloperGuide/Documentation

and

   http://www.scons.org/wiki/DeveloperGuide/Documentation/Discussion

, respectively. There is also a description of the current 
implementation in the file "doc/overview.rst". Together they might shed 
some light on why we (errm, I) finally chose Docbook.
If you have further thoughts or questions, please don't hesitate to ask.

Thanks again for your feedback.

Best regards,

Dirk