On Thu, 09 May 2013 12:14:29 +0200 Dirk Bächle <[email protected]> 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 _______________________________________________ Scons-dev mailing list [email protected] http://two.pairlist.net/mailman/listinfo/scons-dev
