Re: [Scons-dev] New SCons doc toolchain...
On Tue, 26 Mar 2013 00:50:07 +0100 Dirk Bächle tshor...@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. us...@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 ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] New SCons doc toolchain...
Hi Gour, On 09.05.2013 10:33, Gour wrote: On Tue, 26 Mar 2013 00:50:07 +0100 Dirk Bächle tshor...@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. us...@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 ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] New SCons doc toolchain...
On Thu, 9 May 2013 17:06:35 -0400 Gary Oberbrunner ga...@oberbrunner.com wrote: I see this as an iterative process. The first thing was to rationalize the tool chain and use one tool for everything. Formerly we had a hodgepodge of stuff. Now that it's decently organized, there's of course more work to be done to make the doc better, more beautiful and readable, and so on -- and we can consider switching to alternative tools too; at least everything parses and validates now! So it's conceivable to convert it if that makes sense. Thank you for that. I was simply not aware about the whole context. :-( Now it is clear and makes much more sense. Once again, kudos to Dirk for his work on the doc toolchain which is often thankless job. (By the way, I use git at work and for some other open source projects, and I have to say, even though it's more complicated and the doc is poor and the commands args are inconsistent, I like it a lot more than mercurial. Having the right core architecture and philosophy makes all the difference.) Strangely enough, I was avoiding getting 'dirty' with Git always assuming (prejudices, prejudices...) that's it's very (too) complicated to use, but now I find it's very pleasurable and easy to use, even easier than some other DVCS tool (darcs is still the king of UI, imho). Sincerely, Gour -- When your intelligence has passed out of the dense forest of delusion, you shall become indifferent to all that has been heard and all that is to be heard. http://www.atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810 ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] New SCons doc toolchain...
Hello Gour, On 09.05.2013 22:53, Gour wrote: On Thu, 09 May 2013 12:14:29 +0200 Dirk Bächle tshor...@gmx.de wrote: [...] If it's good-enough for Python project docs itself, I believe it should be for SCons as well. that's okay...but to make me believe this as well, you (or someone else) has to deliver actual results. ;) As I stated before in this thread, as long as the same functionality is kept regarding the automatic creation of examples (and the generated list of tools and builders, while delivering the same output formats we have now), a toolchain based on a Markdown processor gets my full support. Knowledge of Docbook authoring is not very common in general and certainly not within Python community, so I'm afraid that contributing docs to SCons project would remain niche for a few people only. Moreover, the current output of the manual shows that the complexity of the markup used to write it is not in proportion the quality of output and tweaking/theming is still, imho, much easier to do with Sphinx. That's more because the stylesheets have been neglected in the past (obviously nobody wanted to fiddle with DSSSL) and because parts of the document processing relied on home-brewed SGML parsing without proper support for XML. Like this, not all valid XML/Docbook constructs would have worked, which held back people a little to use the full power of the Docbook stylesheets. This can (and hopefully will) change now... Finally, in regard to the argument of converting Docbook to something else, there is wonderful tool called Pandoc (http://johnmacfarlane.net/pandoc/) which is capable of reading Docbook markup and select it to several other markup formats. Then just try to convert a few SCons documents with it, and send us some selected pages (not the whole document!) of output samples. Regards, Dirk ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
Re: [Scons-dev] New SCons doc toolchain...
In SCons as with all opensource.. words are ok, but functional tested, documented pull requests are rare and priceless! -Bill On Thu, May 9, 2013 at 2:55 PM, Dirk Bächle tshor...@gmx.de wrote: Hello Gour, On 09.05.2013 22:53, Gour wrote: On Thu, 09 May 2013 12:14:29 +0200 Dirk Bächle tshor...@gmx.de wrote: [...] If it's good-enough for Python project docs itself, I believe it should be for SCons as well. that's okay...but to make me believe this as well, you (or someone else) has to deliver actual results. ;) As I stated before in this thread, as long as the same functionality is kept regarding the automatic creation of examples (and the generated list of tools and builders, while delivering the same output formats we have now), a toolchain based on a Markdown processor gets my full support. Knowledge of Docbook authoring is not very common in general and certainly not within Python community, so I'm afraid that contributing docs to SCons project would remain niche for a few people only. Moreover, the current output of the manual shows that the complexity of the markup used to write it is not in proportion the quality of output and tweaking/theming is still, imho, much easier to do with Sphinx. That's more because the stylesheets have been neglected in the past (obviously nobody wanted to fiddle with DSSSL) and because parts of the document processing relied on home-brewed SGML parsing without proper support for XML. Like this, not all valid XML/Docbook constructs would have worked, which held back people a little to use the full power of the Docbook stylesheets. This can (and hopefully will) change now... Finally, in regard to the argument of converting Docbook to something else, there is wonderful tool called Pandoc (http://johnmacfarlane.net/** pandoc/ http://johnmacfarlane.net/pandoc/) which is capable of reading Docbook markup and select it to several other markup formats. Then just try to convert a few SCons documents with it, and send us some selected pages (not the whole document!) of output samples. Regards, Dirk __**_ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/**mailman/listinfo/scons-devhttp://two.pairlist.net/mailman/listinfo/scons-dev ___ Scons-dev mailing list Scons-dev@scons.org http://two.pairlist.net/mailman/listinfo/scons-dev
