On Tue, 26 Mar 2013 00:50:07 +0100 Dirk Bächle <[email protected]> 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. [email protected]) 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 _______________________________________________ Scons-dev mailing list [email protected] http://two.pairlist.net/mailman/listinfo/scons-dev
