Irreal

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.

Anthony Tedjamulia has a nice post on What I Wish I’d Known About Emacs. If you’re an experienced Emacser, you won’t find much that you didn’t already know but if you’re just starting with Emacs it’s an excellent orientation. One nice thing is that it explains the terminology that Emacs uses. I remember that I kept getting hung up on “yank” because its meaning was exactly the opposite of the way Vim uses it.

Another point that Tedjamulia makes is that Emacs is not so much an editor as a programming environment. Although Tedjamulia doesn’t say so explicitly, that environment is, in fact, a sort of Lisp Machine environment. He compares it to MS Office, an unsavory comparison to be sure but one not without merit. The idea is that Emacs provides a framework in which you or others can write applications. Notice that those applications don’t necessarily involve editing text. You can play music, chat on IRC, handle your email and many other things all because Emacs provides a framework which makes it easy to implement these things.

The final point that Tedjamulia makes that’s worth mentioning is that Emacs is completely transparent. As he puts it, everything is discoverable. You can easily query the documentation for any function, variable, or key sequence. If that doesn’t answer your question, you can follow the link to the source and see for yourself what a function or variable does. Everything is there for you to learn from or extend.

Tedjamulia’s post is, I think, a valuable resource for those new to Emacs. If you’re just starting out, or want to, give this post a read.

I recently learned something useful from Timo Geusch in a post on pinning a package to a specific archive. It turns out that Emacs 24.4 has a new variable, package-pinned-packages, that tells the package system to get certain packages from a certain archive and no others. The variable is a list of cons cells of the form (PACKAGE . ARCHIVE). For example, if you want to get the package htmlize from marmalade only, you would add the cons

(htmlize . "marmalade")

to the package-pinned-packages list.

Probably the most important use of this is to specify that some packages be loaded only from melpa-stable. For example, if you want to ensure that you get the stable versions of smex, yasnippet, and typo you would add

(setq package-pinned-packages '((smex . "melpa-stable")
                                (yasnippet . "melpa-stable")
                                (typo . "melpa-stable")))

to your .emacs or init.el file.

This is really convenient and much easier than the workarounds that were necessary before.

Here’s a problem I dealt with recently. We have a tab-delimited data file that has time as one of the fields. The times are in the U.S. 12-hour format with a trailing ‘a’ for AM or a ‘p’ or PM. We want the times to be in 24-hour format. The file looks like

# -*- Mode: text; indent-tabs-mode: t -*-
11/13/07        7:14a   232     74      70
11/13/07        8:05a   340     85      60
11/13/07        3:47p   927     79      66
11/14/07        7:58a   109     79      72
...

and we want it to look like

# -*- Mode: text; indent-tabs-mode: t -*-
11/13/07        07:14   232     74      70
11/13/07        08:05   340     85      60
11/13/07        15:47   927     79      66
11/14/07        07:58   109     79      72
...

Note that we want each time to contain exactly 5 characters (including the colon). None of the other fields should be changed.

The file is over 1,100 lines long so editing each line by hand is not feasible. How would you do this as efficiently as possible?

Bernd Haug has an interesting take on what the real legacy of Emacs is:

#Emacs’s lasting legacy may be keeping #functional programming for real-life applications alive between AI winter and current renaissance.

— Bernd Haug (@xaibeha) November 7, 2014