AD.2.2.2 Changing an Option

Here is an example of what a user option looks like in the customization buffer:

Kill Ring Max: [Hide] 60 [State]: this option is unchanged from its standard setting. Maximum length of kill ring before oldest elements are thrown away.

The text following `[Hide]', `60' in this case, indicates the current value of the option. If you see `[Show]' instead of `[Hide]', it means that the value is hidden; the customization buffer initially hides values that take up several lines. Invoke `[Show]' to show the value.

The line after the option name indicates the customization state of the option: in the example above, it says you have not changed the option yet. The word `[State]' at the beginning of this line is active; you can get a menu of various operations by invoking it with Mouse-1 or RET. These operations are essential for customizing the variable.

The line after the `[State]' line displays the beginning of the option's documentation string. If there are more lines of documentation, this line ends with `[More]'; invoke this to show the full documentation string.

To enter a new value for `Kill Ring Max', move point to the value and edit it textually. For example, you can type M-d, then insert another number.

When you begin to alter the text, you will see the `[State]' line change to say that you have edited the value:

[State]: you have edited the value as text, but not set the option.

Editing the value does not actually set the option variable. To do that, you must set the option. To do this, invoke the word `[State]' and choose `Set for Current Session'.

The state of the option changes visibly when you set it:

[State]: you have set this option, but not saved it for future sessions.

You don't have to worry about specifying a value that is not valid; setting the option checks for validity and will not really install an unacceptable value.

While editing a value or field that is a file name, directory name, command name, or anything else for which completion is defined, you can type M-TAB (widget-complete) to do completion.

Some options have a small fixed set of possible legitimate values. These options don't let you edit the value textually. Instead, an active field `[Value Menu]' appears before the value; invoke this field to edit the value. For a boolean "on or off" value, the active field says `[Toggle]', and it changes to the other value. `[Value Menu]' and `[Toggle]' edit the buffer; the changes take effect when you use the `Set for Current Session' operation.

Some options have values with complex structure. For example, the value of file-coding-system-alist is an association list. Here is how it appears in the customization buffer:

File Coding System Alist: [Hide] [INS] [DEL] File regexp: \.elc\' Choice: [Value Menu] Encoding/decoding pair: Decoding: emacs-mule Encoding: emacs-mule [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' Choice: [Value Menu] Encoding/decoding pair: Decoding: raw-text Encoding: raw-text-unix [INS] [DEL] File regexp: \.tar\' Choice: [Value Menu] Encoding/decoding pair: Decoding: no-conversion Encoding: no-conversion [INS] [DEL] File regexp: Choice: [Value Menu] Encoding/decoding pair: Decoding: undecided Encoding: nil [INS] [State]: this option is unchanged from its standard setting. Alist to decide a coding system to use for a file I/O operation. [Hide] The format is ((PATTERN . VAL) ...), where PATTERN is a regular expression matching a file name, [...more lines of documentation...]

Each association in the list appears on four lines, with several editable or "active" fields. You can edit the regexps and coding systems using ordinary editing commands. You can also invoke `[Value Menu]' to switch to a kind of value--for instance, to specify a function instead of a pair of coding systems.

To delete an association from the list, invoke the `[DEL]' button for that item. To add an association, invoke `[INS]' at the position where you want to add it. There is an `[INS]' button between each pair of association, another at the beginning and another at the end, so you can add the new association at any position in the list.

Two special commands, TAB and S-TAB, are useful for moving through the customization buffer. TAB (widget-forward) moves forward to the next active or editable field; S-TAB (widget-backward) moves backward to the previous active or editable field.

Typing RET on an editable field also moves forward, just like TAB. We set it up this way because people often type RET when they are finished editing a field. To insert a newline within an editable field, use C-o or C-q C-j.

Setting the option changes its value in the current Emacs session; saving the value changes it for future sessions as well. This works by writing code into your `~/.emacs' file so as to set the option variable again each time you start Emacs. To save the option, invoke `[State]' and select the `Save for Future Sessions' operation.

If Emacs was invoked with the `-q' or `--no-init-file' options (see section AE.2 Initial Options), it will not let you save your customizations in your `~/.emacs' init file. This is because saving customizations from such a session would wipe out all the other customizations you might have on your init file.

You can also restore the option to its standard value by invoking `[State]' and selecting the `Erase Customization' operation. There are actually three reset operations:

`Reset'

If you have made some modifications and not yet set the option, this restores the text in the customization buffer to match the actual value.

`Reset to Saved'

This restores the value of the option to the last saved value, and updates the text accordingly.

`Erase Customization'

This sets the option to its standard value, and updates the text accordingly. This also eliminates any saved value for the option, so that you will get the standard value in future Emacs sessions.

Sometimes it is useful to record a comment about a specific customization. Use the `Add Comment' item from the `[State]' menu to create a field for entering the comment. The comment you enter will be saved, and displayed again if you again view the same option in a customization buffer, even in another session.

The state of a group indicates whether anything in that group has been edited, set or saved. You can select `Set for Current Session', `Save for Future Sessions' and the various kinds of `Reset' operation for the group; these operations on the group apply to all options in the group and its subgroups.

Near the top of the customization buffer there are two lines containing several active fields:

[Set for Current Session] [Save for Future Sessions] [Reset] [Reset to Saved] [Erase Customization] [Finish]

Invoking `[Finish]' either buries or kills this customization buffer according to the setting of the option custom-buffer-done-function; the default is to bury the buffer. Each of the other fields performs an operation--set, save or reset--on each of the items in the buffer that could meaningfully be set, saved or reset.