Sams Teach Yourself Emacs in 24 Hours


Hour 10: The Emacs Help System and Configuration System

Previous HourNext Hour

Sections in this Hour:


Customizing Emacs's Features

The most important feature in Emacs 20 (seen from the point of view of a newcomer to Emacs) is the customization utility. Customization support makes it a hundred times easier to configure Emacs.

Customization in Emacs is done using a variant of the Lisp programming language, called elisp. Thus, to configure Emacs to beep instead of inserting a blank line when you click arrow down (next-line) on the last line of a buffer, you must insert the following line into your .emacs file:

(setq next-line-add-newlines nil)

There are many chances for a person unfamiliar with programming languages or unfamiliar with elisp to make a mistake when inserting the preceding code line. Such a mistake would cause the line to have no effect and, in most situations, the lines following it would also have no effect. An alternative for customizing the preceding code line is to offer the user (that's you) a semi-graphical user interface. This is exactly what the customize library does. In Figures 10.7 and 10.8 you can see the customization of the preceding variable using the customize library in XEmacs and in GNU Emacs.

Figure 10.7
Customization of next-line-add-newlines using the customize library in XEmacs.

Figure 10.8
Customization of next-line-add-newlines using the customize library in GNU Emacs.

Note - As discussed in the Introduction to this book, XEmacs is more graphically oriented than GNU Emacs, which you can easily see in Figures 10.7 and 10.8. The rest of this hour uses figures from XEmacs, because they are much easier to interpret when you're only seeing them. You should have no problem if you use the GNU Emacs customize interface instead, because the command buttons highlight when the cursor moves over them, which indicates that they are, in fact, buttons.

Customization using the customize library is done by using graphical elements such as check boxes (or something that resembles check buttons), text entries, pull-down menus, and so on. Each element is discussed in detail in the next section. The customize library contains about 2,500 options split over approximately 400 pages.

Figure 10.9 shows a customization buffer.

Figure 10.9
Part of a customization buffer for the group Editing Basics.

Caution - The group shown in Figure 10.9 is very large, so I had to remove some of the options to include all details of the customization page. In general, the options that you see on your customization pages might be different from mine, especially if you use GNU Emacs.

This buffer shows four options. Two of them are two-stated values, that is they might be either on or off. The other two are entries where the user can type a value. Each option part contains a header, which makes it easy to distinguish them from each other.

Apart from the header, the option section contains the following items:


When you have configured what you want on a given page, it's time to set the variables, which makes Emacs behave as the options say. To do this, click either the Set button or the Save button at the top of the page. Set means set the variables for the current Emacs session, but do not save to the .emacs file, whereas Save means set the variable and save to the .emacs file. To leave the page, click the Done button.

Caution - When you click the Done button, the configuration page will be removed. No warnings are given if you have not saved the option on the given page.

Tip - By default Emacs writes the customization to your ~/.emacs file. If you are trying to keep it well organized, this is not desirable. To tell Emacs to save to another file, insert the following lines into your .emacs file:

 ### Tell customize to save to ~/Emacs/customize.el TI (setq custom-file "~/Emacs/customize.el")
### Load the customizations.
(load-file "~/Emacs/customize.el")

If you change your mind or want to get back to the state before you invoked customize, click the Reset button, which shows a pop-up menu with the following items:

If you have edited only one option, but you are not certain whether the other options are changed and you do not care to check, you can select the Set/Save/Reset functions from the State menu for the given option, instead of selecting the buttons from the top of the buffer. This will then affect only the current option.

Before you save a given option to the .emacs file, you might want to test it a bit first. You can do that by setting the option (that is, do not save it) and, when you have tested it, you can press M-x and type customize-customized. Emacs will then create a customization page for you, with the unsaved options.

The customize library offers customization of 2,400 options! The customization options have been split in almost 500 groups of options. Each group can contain subgroups or customization options.

Customization Widgets

The customization library contains only a few different widgets, which it does the actual customization with. These widgets and their meanings are described in the following sections.

The Toggle Button

The Toggle button, shown in Figure 10.10, has already been discussed in the previous section. It is used to select between two values, often on or off.

Figure 10.10
The Toggle button shown onscreen.

The Entry Widget

You have also already seen the Entry widget, in which you can insert text (see Figure 10.11). To use it, place the point in it, and press Enter. Then you are queried for the value in the minibuffer. Here you also have completion, for command names and variable, in case the entry requires one.

Figure 10.11
The Entry widget shown onscreen.

The Value Menu

The value menu is used when there is a small limited set of values available for the given option (see Figure 10.12). When you click the widget, a pull-down menu appears with the possible values.

Figure 10.12
The Value menu widget shown onscreen.

The Multi Widget

The Multi widget is used when you are required to list a number of strings. The example shown in Figure 10.13 lists a number of modes for which Brace mode is enabled. To add an element, click the INS button on the line where you want a new entry. To delete an element, click the DEL button.

Note - The Multi widget can in fact also be used with some of the other widgets, not only the entry widget. This is, however, seldom seen.

Figure 10.13
The Multi widget shown onscreen.

The Face Widget

Faces in Emacs refers to a combination of font, color, and typeface attributes (that is underlining, italics, and bold). Figure 10.14 shows the configuration of Face. The column of check buttons is used to indicate whether the line they are in front of is to be regarded. Thus the widget in Figure 10.14 defines only the foreground color and the background color. The other values are taken from the default.

Figure 10.14
The Face widget shown onscreen.

In the State menu, you can select an element called Show All Display Spec. If you do that, you can specify the face for the given option based on the characteristics of the display used. For example, is the display black-and-white or color? The Multi widget is used here to give you the opportunity to describe several display types. As indicated previously, the left column of check buttons indicates which elements to use. Thus, in Figure 10.15, the display is a grayscale X, but nothing is said about the background brightness.

Figure 10.15
The Face widget, including display characteristics.

Customization Commands

Emacs offers a set of different entries to customize. All these are located in the menu bar, so there is no need to remember them unless you use them often. In GNU Emacs the commands are located as a submenu to the Help menu. In XEmacs, there is an item on the menu bar called Custom.

The entries to customize are as follows:

Figure 10.16
Buffer used for customize-browse.

Sams Teach Yourself Emacs in 24 Hours


Hour 10: The Emacs Help System and Configuration System

Previous HourNext Hour

Sections in this Hour: