Those are all good points, thanks. I haven't used Sphinx, is it popular? Are there any other choices?
Does this decision block getting the current work onto the master branch? My main concern with the donated documentation is not with the DocBook format itself (I quite like it, but I'd switch in a heartbeat if some other format would encourage more contributions) but the toolchain needed to build it. Last I looked, and forgive me if this has changed, there was quite a bit of work (and a JVM) to build the docs. I wouldn't block the merge to trunk on that basis, but I would probably spend some time to simplify it once it did. Can we merge what we have into master today and address these problems together within the code base? In the absolute worst case, we can remove it again for a release, but we could leave these on the side forever while we mull over these issues. B. On 31 Jul 2012, at 14:28, Benoit Chesneau wrote: > On Tue, Jul 31, 2012 at 3:22 PM, Robert Newson <[email protected]> wrote: >> >> I dislike a veto without an adequate reason. Can you make your objections >> explicit? What can't we do (that we need) with Markdown? > > I gave some: >>> [..] There is no real doc system in markdown which will >>> force to write another script and we will lost some features given by >>> docbook (linking, references...) >>> > > linking, automatic references, templating. specific section markups ... > the need to write this tool to generate the doc while we could reuse a > widely used tool wich is important for me. Also with sphinx you could > still generate a PDF or event an ebook which is imo important for > those who want to consult the doc offline. > > - benoît
