Eric Raymond (esr) is a hero of mine. He writes great software and has done yeoman work for Emacs, including the just completed conversion of the repository to Git. Recently, he proposed that Emacs abandon info in favor of a Web-based documentation system using asciidoc as the source format.
Esr is a believer in browser-based documentation. A few years ago he made a similar pitch for replacing man pages with Web-documentation. I don’t know how much uptake that effort enjoyed but I, for one, am still happily using man. The reason is simple: when I’m working and need some documentation, the last thing I want to do is change out of my editor to the browser. I want to pop up the documentation in another buffer, read the information I need, and get on with my work. It’s not just an Emacs thing; back then I was still using Vim and its built-in man page reader.
It’s no surprise, then, that I’m not in favor of this latest move either. But even on its own terms, esr’s proposal seems odd. Why get rid of texinfo in favor of asciidoc? If, as he says, texinfo is a barrier to entry for new hackers—something I find unlikely—why use asciidoc instead of the excellent built-in Org Mode? The answer appears to be that esr isn’t very familiar with Org Mode (although he has admitted he should learn more) and fears that it may not be up to producing a manual. Several of the posters pointed out that Org Mode has been used to write books and that it certainly is up to the task even if it hasn’t been used to produce any manuals yet.
Then RMS popped up defending the decision to use asciidoc and saying that he started to read the Org Mode documentation but it didn’t immediately say anything about producing manuals so he stopped reading. Really, all this seems bizarre. Esr and RMS are proposing a major change to how Emacs does documentation but seem unaware of a built in solution.
But that, as I say, is considering the proposal on its own terms. I do not agree that we should abandon info in favor of the Web, Org Mode, or anything else. I find the notion that info and texinfo are scaring away new developers silly and, really, insulting to younger developers. Esr may prefer reading documentation in a browser but many of us do not. Read the thread (warning: it’s long) and you’ll see that most of the commenters agree that the system’s not broken and doesn’t need fixing. Also be sure to check out David Kastrup’s description of what he was able to do with texinfo and info for the LilyPond documentation. It’s very impressive.
The sometimes heated arguments in the thread aside, reasonable people can take either side of the question. What do you think?
UPDATE: LWN has an excellent article on this debate.