From dev-return-22763-apmail-couchdb-dev-archive=couchdb.apache.org@couchdb.apache.org Tue Jul 31 12:39:42 2012 Return-Path: X-Original-To: apmail-couchdb-dev-archive@www.apache.org Delivered-To: apmail-couchdb-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 7AA8CD392 for ; Tue, 31 Jul 2012 12:39:42 +0000 (UTC) Received: (qmail 76932 invoked by uid 500); 31 Jul 2012 12:39:42 -0000 Delivered-To: apmail-couchdb-dev-archive@couchdb.apache.org Received: (qmail 76862 invoked by uid 500); 31 Jul 2012 12:39:41 -0000 Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list dev@couchdb.apache.org Received: (qmail 76853 invoked by uid 99); 31 Jul 2012 12:39:41 -0000 Received: from minotaur.apache.org (HELO minotaur.apache.org) (140.211.11.9) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 31 Jul 2012 12:39:41 +0000 Received: from localhost (HELO [192.168.1.5]) (127.0.0.1) (smtp-auth username rnewson, mechanism plain) by minotaur.apache.org (qpsmtpd/0.29) with ESMTP; Tue, 31 Jul 2012 12:39:41 +0000 Content-Type: text/plain; charset=iso-8859-1 Mime-Version: 1.0 (Apple Message framework v1278) Subject: Re: Docs, second try From: Robert Newson In-Reply-To: Date: Tue, 31 Jul 2012 13:39:39 +0100 Content-Transfer-Encoding: quoted-printable Message-Id: References: <8A69B3F1-C955-4127-B92B-B0DA1AA9AEB6@apache.org> <19EB8367-1282-4406-9C51-B3AE4AFA0080@apache.org> <2E5C3210-58B9-48A7-9E21-3B6206D24899@apache.org> <382956416E9B4787895A95D59AC5ECC1@cloudant.com> <70658AB3-81FA-4E3A-ABE6-D6299ED2704A@apache.org> <436CC93B-6244-4A01-9933-46B2937AB331@apache.org> <872CBFC9-B758-492C-8297-410600E6DA84@tumbolia.org> To: dev@couchdb.apache.org X-Mailer: Apple Mail (2.1278) +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 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. >>=20 >> 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 >=20 > +1. TL;DR: >=20 > 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. >=20 > I now have a working export of DocBook -> Markdown, using Pandoc[1], > which can be turned into HTML5, PDFs or ePUBs easily. >=20 > 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 >=20 > My next steps: >=20 > - 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 >=20 > Long Version: >=20 > 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. >=20 > If I'm not able to drive it, we set the contribution barrier too high = methinks. >=20 > 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. >=20 > 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. >=20 > The output is not yet perfect, but I believe its workable: >=20 > - 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) >=20 > 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. >=20 > 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. >=20 > Let's get this off the ground. Please. >=20 > A+ > Dave >=20 > [1]: http://johnmacfarlane.net/pandoc/