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

[Gour]

On Thu, 09 May 2013 12:14:29 +0200
Dirk Bächle <tshortik at gmx.de> wrote:

Hello Dirk,


> 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.


I read those wiki pages and have to say that I'm not really convinced.

Docbook was on my testing plate several years ago and it seems to me that it
does not changed a lot - it's still involves quite complicated toolchain, it's
not easy for author writers and I'd never replace LaTeX with e.g. FOP.

When SCons project moved from SVN to Mercurial (personally I tried/used
everything from darcs, bzr, hg, mtn, fossil and now settled on Git, although I
prefer Bitbucekt over Github), I believe that one of the rationale is hope to
increase contributors by using DVCS.

In the same light I also propose(d) using reST/Sphinx which is much easier for
content authors, has lot of support within Python community and its usage is
simply exploding in recent years. (see http://sphinx-doc.org/examples.html)

If it's good-enough for Python project docs itself, I believe it should be for
SCons as well.

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.

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.

As a last resort, although I gave up on it preferring reST/Sphinx, there is
AsciiDoc (used by SCons' competitor Waf) which is also based on Docboook-based
toolchain in order to generate output and it's much easier to write in it than
directly in Docbook's XML format.

(My) conclusion: reST/Sphinx are Python tools, very actively developed and
(used within Python community and considering that for efficient use of SCons
(one is supposed to be familiar with Python language it's quite natural for me
(to use Python-based tools since it produces good-enough output for many
(projects. My mantra is: "simplify, simplify" in order to use precious
(developer's time to enhance SCons tool itself and simultaneously provide low-
(hanging fruit for new doc contributors.

I'm only sorry for not settling on SCons earlier and being able to express my
opinion earlier, but, otoh, since you're the only one working on new
toolchain, it probably would not make a change and I still congratulate you to
being courageous enough to wrestle with the Docbook. :-)


Sincerely,
Gour

-- 
In this endeavor there is no loss or diminution, 
and a little advancement on this path can protect 
one from the most dangerous type of fear.

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