On 30 July 2012 18:41, Simon Metson <[email protected]> wrote: > Hi, > Has this moved on at all? Thinking about it a bit more (off and on) > I'm inclined to suggest that DocBook isn't the greatest format. If > we stored the docs in markdown it would be easier for people to > edit/contribute (they could view the docs and make changes in > github without having to compile/install anything). I'm happy to > put some cycles into converting whats there to a bunch of > markdown. Rendering that in futon is pretty easy too. > > I can see the benefits of DocBook for writing a book, but I'm not > sure that its what's needed here - it seems like using a hammer to > crack a nut. > Cheers > Simon
+1. TL;DR: Let's focus on the *real* issue: despite having a great working base for over 5 months now, the docs contribution barrier is too high for even the dev community to make any progress. I now have a working export of DocBook -> Markdown, using Pandoc[1], which can be turned into HTML5, PDFs or ePUBs easily. Notes/results: https://gist.github.com/3212532#file_readme.md If you want epub or PDF, try using this branch: https://github.com/dch/couchdb/tree/docs My next steps: - check the details (in daytime) - document how to add a chapter/section - make a list of things to be added to reach 1.2.0 equivalence - get stuck in & get helpers - sort out CSS & images for futon & standalone viewing - integrate build step with autotools - get this into 1.3.0 Long Version: Tonight, I tried to add a simple section to the XML pages, explaining the new [vendor] field in default.ini. I gave up after an hour of faffing about. If I'm not able to drive it, we set the contribution barrier too high methinks. I then tried installing XML editors and trying to make sense of the admittedly awesome couchbase doc structure, and related tools. I still failed, I was unable to add a simple chapter, or clarify the new [vendor] section in default.ini. Clearly somebody who *knows* DocBook and XML will be annoyed at my incompetence, but so far none of those people have the time to move our docs along, and more importantly, nor do most of our contributors. I want this in 1.3.0, as a solid baseline for the next release with bigcouch included. The output is not yet perfect, but I believe its workable: - the structure is right (chapters, headings, links, code) - integrating small sections works (merge chapters -> larger doc) - images are missing (I was too lazy to copy them in) - some tables are not right yet (ditto) - I don't have CSS right (ditto) Let's do the conversion, get the docs into master, and get them updated for 1.3. I'm up for it & I'm not waiting for DocBook nirvana to arrive, because the current barrier to contribution is simply too high. Pandoc[1], is a GPL-licensed Haskell library. It's available as a binary on pretty much every system we dev on, either in package manager tools or via download. And it just works, surprisingly well too, and it's fricking FAST. Blazing. DocBook -> HTML5 in seconds, without installing FOP, 6 jars, 12 perl modules, and the kitchen sink. Let's get this off the ground. Please. A+ Dave [1]: http://johnmacfarlane.net/pandoc/
