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
