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

[Bill Deegan]

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 <tshortik at 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 <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/ <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 at scons.org

> http://two.pairlist.net/**mailman/listinfo/scons-dev<http://two.pairlist.net/mailman/listinfo/scons-dev>

>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://two.pairlist.net/pipermail/scons-dev/attachments/20130509/5f2a356b/attachment-0001.html>