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

[Gour]

On Tue, 26 Mar 2013 00:50:07 +0100
Dirk Bächle <tshortik at gmx.de> wrote:


> Hi developers,



>    - All processing is based on plain Python scripts, the only 

> additional dependencies are either lxml or libxml2.

>      (for creating the PDF files, you also need to have a renderer

> like fop, xep or jw installed)

>      XML parsing is now DOM-based, instead of using SAX.

>    - Uses a special SCons XSD, based on the Docbook v4.5 DTD/XSD.

>    - All documents (like MAN pages, User guide and also the 

> Tools/Builders docs in the src/engine folder)

>      are valid against this XSD and can be easily re-validated after

> any changes by running a single script.

>    - The troff input files for the MAN pages have been converted to 

> Docbook (DocLifter still rocks!).

>    - Entities, the descriptions for Tools/Builders/Functions/CVars

> and the automatically created example

>      outputs are supported as before.

>    - All document folders have SConstructs, together with the added 

> Docbook Tool you can directly create

>      HTML and MAN pages. The User guide has its own titlepage design, 

> see the attached PDF for getting

>      a first impression from a few selected pages.


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.

Of course, I greatly appreciate Dirk's work on improving the toolchain and my
proposal is in the same vein. :-)


Sincerely,
Gour

-- 
One must deliver himself with the help of his mind, and not 
degrade himself. The mind is the friend of the conditioned soul, 
and his enemy as well.

http://www.atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810