couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Newson <rnew...@apache.org>
Subject Re: Docs, second try
Date Tue, 31 Jul 2012 13:22:48 GMT

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 <dave@muse.net.nz> wrote:
>> On 30 July 2012 18:41, Simon Metson <simon@cloudant.com> 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/


Mime
View raw message