Werden wir Helden für einen Tag

Advent of emacs #8: How I find information about emacs in emacs

Posted on Dec 8, 2022 by Chung-hong Chan

Yesterday, I talked about mode and keymap/modemap. And it actually opens up a pandora box: How do I know all these information? In order to customize emacs, you need to find all the relevant information.

In the past, I found it overwhelming to find all these information online. There are dense manuals, source code, but rarely tutorials and blog posts. I am not a good learner. I don’t want to digest the whole manual of an emacs package to be able to customize it, although one should. This is not a blog post about how to learn emacs. But a quick one on finding information about emacs, in emacs.

Variables

By customization, I think 80% of it boils down to:

Change a variable
Create a new command

I will not talk about create new commands now, although I will show you how I do it later. I want to focus on variables today. Most of you know what a variable is. There are actually local variables and “(vanilla) variables”. In the context of customization, one deals with (vanilla) variables more. A good way to experimenting with it is to use the emacs lisp repl ielm (M-x ielm).

(setq pi 3.14)
pi ;; 3.14
(setq pi (/ 22.0 7))
pi ;; 3.1416...
;; or

(set 'pi (/ 22.0 7))
;; but

(defvar adam "bad" "dog") ;; "dog" is docsting
adam ;; bad
(defvar adam "good" "dog")
adam ;; bad
(setq adam "good")
adam ;; good

But how to find information about these variables. The standard answer is to read the fine manual. ESS (Emacs Speaks Statistics), for example, has a great online manual. In the manual, it has an index of all variables. Another route is to the usual use the source, luke!, i.e. read the source code.

The internet is wonderful, but not all information is available online. Somehow we also need to be able to navigate around these information even the information isn’t online. One important, but often neglected, feature of emacs is the documentation. The original author of emacs, Stallman, maintains that emacs is “self-documenting” (1981). (But the Stallmanian self-documenting is not the same as self-documenting in modern programming lingos.) I would rather say that functions and variables are usually well documented with docstrings. But how to access these documentation?

Using the interactive help system to find variables

The key combination C-h maps to various interactive help systems of emacs. If you use it for the first time, I suggesting C-h ? (help-for-help) to know more about these help systems. C-h needs to follow by a single key to access different helps. I will only talk about “k”, “v”, “f”, and “i”.

C-h k describes a key combination. For example, C-h k and then C-x C-s will show you the command save-buffer has been mapped to C-x C-s and displays the command’s documentation. C-h f and C-h v can be used to look for documentation of functions and variables. I find it extremely useful when the help system is running with a completion engine such as Helm (see day2). The completion engine also makes the documentation more discoverable.

Suppose I have no clue what the mode-map of emacs lisp mode is called. I just fire up C-h v and type in some keywords such as “lisp map”; and surely, Helm shows some hits. And the 2nd hit looks like it. I can then select it and see how it is defined.

You can of course also select the variable and see what is the current value and what it does.

Package complete documentation

Some packages have the complete documentation available from within emacs. The complete index is available by pressing C-h i.

For example, the emacs built-in webbrowser eww has a complete documentation in the GNU Texinfo format and it has variable and command indices.

In the Texinfo viewer, “n” and “p” go next and back. And “d” goes back to the index.

Endnote

The interactive system is tremendous helpful. There are even books on emacs in the interactive system: “Emacs”, “Emacs Lisp Intro”, and “Elisp”. Of course, there is also an interactive tutorial (C-h t) ¹. I prefer to read these inside emacs rather than online because emacs is less distractive then the web. I will talk about context collapse and context separation in a future blog post. But keep in mind that emacs is also a good plain-text content consumption tool.

Tomorrow, I will go back to the topic of typing more by typing less.

Unlike many emacs educators, I am quite reluctance to recommend this tutorial to newbies. Newbies would probably find the tutorial confusing because of the emacs’ trademarked archaic use of computer terms. My opinion is that it is not very suitable to modern learners who do not have the same attention span of the learners in the 80s. If you really need a relative modern newbie tutorial, I prefer this one from TU Kaiserlautern. No BS, one page. And then learn from the interactive help system. ↩