couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Newson <>
Subject Re: Docs, second try
Date Tue, 31 Jul 2012 12:39:39 GMT
+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.


On 31 Jul 2012, at 03:08, Dave Cottlehuber wrote:

> On 30 July 2012 18:41, Simon Metson <> 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:
> If you want epub or PDF, try using this branch:
> 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]:

View raw message