Emacs Helper Functions

If there’s one thing I wish I was doing when I first started learning emacs, it would be calling documentation on functions as I was keying them in.

Remember, while you’re using emacs and punching in various key commands, there are functions running in the background. Those functions are attached to the keystrokes you’re punching in.

The helper functions can tell you exactly which functions are running with each key press.

Let’s take standard example: the save function. In order to save your work in emacs, you can key in C-x C-s. But what function runs in the background in order to accomplish this task.

To discover the function, type C-h k. Then, you’ll be prompted for the key command. Type in C-x C-s and a window will pop up with the documentation on the function:

C-x C-s runs the command save-buffer (found in global-map), which is
an interactive compiled Lisp function in ‘files.el’.

It is bound to s-s, C-x C-s, <menu-bar> <file> <save-buffer>.

(save-buffer &optional ARG)

  Probably introduced at or before Emacs version 26.1.

Save current buffer in visited file if modified.
Variations are described below.

By default, makes the previous version into a backup file
 if previously requested or if this is the first save.
Prefixed with one C-u, marks this version
 to become a backup when the next save is done.
Prefixed with two C-u’s,
 makes the previous version into a backup file.
Prefixed with three C-u’s, marks this version
 to become a backup when the next save is done,
 and makes the previous version into a backup file.

With a numeric prefix argument of 0, never make the previous version
into a backup file.

Note that the various variables that control backups, such
as ‘version-control’, ‘backup-enable-predicate’, ‘vc-make-backup-files’,
and ‘backup-inhibited’, to name just the more popular ones, still
control whether a backup will actually be produced, even when you
invoke this command prefixed with two or three C-u’s.

If a file’s name is FOO, the names of its numbered backup versions are
 FOO.~i~ for various integers i.  A non-numbered backup file is called FOO~.
Numeric backups (rather than FOO~) will be made if value of
 ‘version-control’ is not the atom ‘never’ and either there are already
 numeric versions of the file being backed up, or ‘version-control’ is
 non-nil.
We don’t want excessive versions piling up, so there are variables
 ‘kept-old-versions’, which tells Emacs how many oldest versions to keep,
 and ‘kept-new-versions’, which tells how many newest versions to keep.
 Defaults are 2 old versions and 2 new.
‘dired-kept-versions’ controls dired’s clean-directory (.) command.
If ‘delete-old-versions’ is nil, system will query user
 before trimming versions.  Otherwise it does it silently.

If ‘vc-make-backup-files’ is nil, which is the default,
 no backup files are made for files managed by version control.
 (This is because the version control system itself records previous versions.)

See the subroutine ‘basic-save-buffer’ for more information.

That’s a detailed documentation listing for one little function. Every function in Emacs, contributed by hundreds of volunteers over many years, are (for the most part) self-documenting, which means you can access documentation for virtually every function available in emacs, and there are thousands.

As you advance further in your emacs judo, you’ll learn how to chain various functions together to build custom functions to speed up your workflow.

As you proceed on your emacs journey, you will spend a great deal of time running commands upon your text. The most important commands are already bound to certain keys on your keyboard. If there is a command you’re accustomed to running by rote, you may be curious to know the background information about what command.

With the F key in the help menu you can instruct emacs to deliver the manual page containing extra information about that command.

But first, you’ll need the proper name for that command. For example, you’re aware that C-x C-s runs the command to save your buffer. But what is the formal name for that function? Use the key function “c Keys” mentioned above to get the function name.

Now, let’s put that all together. You will use C-h to call the interactive help function followed by F (that’s a case-sensitive capital “F”) followed by the command for which you are requesting documentation.

In emacs, documentation is everything. And everything is documented. Emacs ships with a lot of written material that you can refer to at any time while working in emacs.

You can peruse all of this documentation using “Info” mode. Info mode, like other modes in emacs, comes with its own set of key commands for movement and processing.

Here’s some free advice. When starting with emacs, spend a great deal of time in info mode. You won’t regret it. Over many years of learning emacs, you’ll always find something new and fascinating behind the scenes. Info mode describes every aspect of the program itself and includes loads of other documents describing various features and modes.

In order to enter info mode, type C-h i. When you first arrive, I recommend reading the info manual to learn how to navigate info mode. It should be the first link “Info” in the main menu.