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

[Dirk Bächle]

Hello Gour,

On 09.05.2013 22:53, Gour wrote:

> On Thu, 09 May 2013 12:14:29 +0200

> Dirk Bächle <tshortik at 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