+1 for markdown. I'm stepping up (with Paul Davis) to get on with the BigCouch merge, which will mean these docs will need a fair amount of editing and expanding. It would be nice if they were in a format that encouraged that.
B. On 31 Jul 2012, at 03:08, Dave Cottlehuber wrote: > 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/
