On Tue, Jun 14, 2011 at 10:13 AM, Noah Slater <[email protected]> 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
