I dislike a veto without an adequate reason. Can you make your objections explicit? What can't we do (that we need) with Markdown?
B. On 31 Jul 2012, at 13:55, Benoit Chesneau wrote: > -1 on markdown. 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...) > > If we want to move from docbook I would strongly suggest to go for > sphinx doc [1] in ReStructuredText. Also sphix is a supported tools > used even in non python systems. db2rsy [2] can be used to convert > the docbook files. > > - benoit > > [1] http://sphinx.pocoo.org/ > [2] http://code.google.com/p/db2rst/ > > On Tue, Jul 31, 2012 at 4:08 AM, Dave Cottlehuber <[email protected]> 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/
