Here is an example of what a variable (a user option) looks like in the customization buffer:
Kill Ring Max: [Hide Value] 60 [State]: STANDARD. Maximum length of kill ring before oldest elements are thrown away.
The text following ‘[Hide Value]’, ‘60’ in this case, indicates the current value of the variable. If you see ‘[Show Value]’ instead of ‘[Hide Value]’, it means that the value is hidden; the customization buffer initially hides values that take up several lines. Invoke ‘[Show Value]’ to show the value.
The line after the variable name indicates the customization state of the variable: in the example above, it says you have not changed the option yet. The ‘[State]’ button at the beginning of this line gives you a menu of various operations for customizing the variable.
The line after the ‘[State]’ line displays the beginning of the variable's documentation string. If there are more lines of documentation, this line ends with a ‘[More]’ button; invoke that 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. As you begin to alter the text, you will see the ‘[State]’ line change to say that you have edited the value:
[State]: EDITED, shown value does not take effect until you set or ... save it.
Editing the value does not actually set the variable. To do that, you must set the variable. To do this, invoke the ‘[State]’ button and choose ‘Set for Current Session’.
The state of the variable changes visibly when you set it:
[State]: SET for current session only.
You don't have to worry about specifying a value that is not valid; the ‘Set for Current Session’ operation checks for validity and will not install an unacceptable value.
While editing a 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.
(<ESC> <TAB> and C-M-i do the same thing.)
Some variables have a small fixed set of possible legitimate values. These variables don't let you edit the value textually. Instead, a ‘[Value Menu]’ button appears before the value; invoke this button to change the value. For a boolean “on or off” value, the button says ‘[Toggle]’, and it changes to the other value. ‘[Value Menu]’ and ‘[Toggle]’ simply edit the buffer; the changes take real effect when you use the ‘Set for Current Session’ operation.
Some variables have values with complex structure. For example, the
file-coding-system-alist is an association list. Here
is how it appears in the customization buffer:
File Coding System Alist: [Hide Value] [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]: STANDARD. Alist to decide a coding system to use for a file I/O ... operation. [Hide Rest] 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 fields and/or buttons. You can edit the regexps and coding systems using ordinary editing commands. You can also invoke ‘[Value Menu]’ to switch to a different 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 associations, another at the beginning and another at the end, so you can add a 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 button or editable
field; S-<TAB> (
widget-backward) moves backward to
the previous button or editable field.
Typing <RET> on an editable field also moves forward, just like <TAB>. You can thus type <RET> when you are finished editing a field, to move on to the next button or field. To insert a newline within an editable field, use C-o or C-q C-j.
Setting the variable changes its value in the current Emacs session; saving the value changes it for future sessions as well. To save the variable, invoke ‘[State]’ and select the ‘Save for Future Sessions’ operation. This works by writing code so as to set the variable again, each time you start Emacs (see Saving Customizations).
You can also restore the variable to its standard value by invoking ‘[State]’ and selecting the ‘Erase Customization’ operation. There are actually four reset operations:
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 variable 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.
Near the top of the customization buffer there are two lines of buttons:
[Set for Current Session] [Save for Future Sessions] [Undo Edits] [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-kill; the default is to bury the buffer.
Each of the other buttons performs an operation—set, save or
reset—on each of the settings in the buffer that could meaningfully
be set, saved or reset. They do not operate on settings whose values
are hidden, nor on subgroups which are hidden or not visible in the buffer.