couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@apache.org>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 14 Jun 2011 17:13:12 GMT

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
Mime
View raw message