couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benoit Chesneau <bchesn...@gmail.com>
Subject Re: Docs, second try
Date Tue, 31 Jul 2012 12:55:19 GMT
-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