couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benoit Chesneau <bchesn...@gmail.com>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 14 Jun 2011 17:31:43 GMT
On Tue, Jun 14, 2011 at 10:13 AM, Noah Slater <nslater@apache.org> wrote:
>
> On 14 Jun 2011, at 18:02, Benoit Chesneau wrote:
>
>> +0 docbook
>> +1 REST
>
> Seriously, let's not fall into this trap.
>
> And let us not be seduced by so called "plain text" formats.
>
> We made this mistake on the book and I'm in no rush to repeat it.
>
> I will quote from an email I sent to our O'Reilly editor.
>
>> On the CouchDB book, we used a combination of AsciiDoc and GNU Make for the build.
We all used our own favourite editor, and GNU Emacs, which I was using at the time, had a
major mode for AsciiDoc. I am using BBEdit now, and it doesn't pose a problem.
>>
>> However, I would strongly recommend against using AsciiDoc. As with any format that
tries to map to some other format - there are some places it makes things simpler, and some
places it makes things more complex. The gzip algorithm, for example, compresses most common
things, and expands some of the more uncommon things. You should never notice this, because
it is designed well.
>>
>> Unfortunately for us, AsciiDoc isn't as good, and the balance between what it makes
easier and what it makes harder was unfortunately weighted in the wrong direction. The amount
of hacks, and tweaking, and general ballache it caused me was crazy. I ended up wasting far
too much time on this. Add to that the cognitive burden of learning and remembering an entirely
new and arbitrary syntax.
>>
>> If we do a second version, or if I do a second book, I will be pushing hard to author
in HTML. It's a standard, it works, it's simple, and there are tools to convert it into DocBook.
Where they don't exist, I will write them. Working with "plain text" formats is just too much
work. There are too many edge cases where the "easy" syntax becomes a "nightmare" and you
wish you'd just stuck to something that has the benefit of 20 year's collective experience,
refinements, and authoring tools available.
>
>
> — November, 2009

I understand. So is your suggestion to just use docbook or html ? Both
are OK for me .

- benoît

Mime
View raw message