How to Read the Commentary Section of Emacs Packages

Alexandro de Oliveira has a problem that I’ve also experienced. He wants to know how he can read a complete description of a package such as that given on its Elpa page. He asked on Stack Exchange and gave as an example the documentation for undo-tree. I’ve had that exact problem. I’m always forgetting some of the undo-tree keystrokes and that means I have to bring up the source to read the commentary at the front of the source file.

It turns out that there’s a much better way: as suggested by wasamasa, simply use finder-commentary to extract the commentary from the source file. That function is part of the finder package written by Eric Raymond back in 1992 so it’s been around for a long time but this is the first time I’ve heard about it.

If you’re writing a package, this tip should encourage you to spend some time on the commentary section. It can really be useful to your users, especially if the package’s UI is the least bit complicated. As usual, I’m always learning something new about Emacs.

This entry was posted in General and tagged . Bookmark the permalink.
  • You can also use `C-h P` (`describe-package`) and that Commentary is fetched from ELPA (such as http://elpa.gnu.org/packages/undo-tree-readme.txt ), thus you can read it without installing the package. Note that If you find the Commentary doesn't appear for a installed package, simply click a link after "Other versions", it will download the readme file for you. I also often use `describe-package` to find package's Homepage.

    • jcs

      Interesting. I also tried describe-package but it didn't include the commentary section. Nice to know how to get that---especially for uninstalled packages.

  • Phil

    Oh, neat! I didn't know that existed either. I have find-library bound to C-h C-l which has always made it easy to read a commentary; but this is just that much nicer! I think I shall clobber C-h C-c for this (with apologies to describe-copying; but I'm well aware of the GPL :)

    • jcs

      Yeah, I use C-h C-l too (I'm pretty sure I learned that from you) but I agree finder-commentary is much nicer. I hadn't thought of mapping it to C-h C-c but that seems like a good idea. As you say, we're all pretty much up to speed on the GPL.