eintr: defcustom
16.2 Specifying Variables using ‘defcustom’
===========================================
You can specify variables using ‘defcustom’ so that you and others can
then use Emacs’s ‘customize’ feature to set their values. (You cannot
use ‘customize’ to write function definitions; but you can write
‘defuns’ in your ‘.emacs’ file. Indeed, you can write any Lisp
expression in your ‘.emacs’ file.)
The ‘customize’ feature depends on the ‘defcustom’ macro. Although
you can use ‘defvar’ or ‘setq’ for variables that users set, the
‘defcustom’ macro is designed for the job.
You can use your knowledge of ‘defvar’ for writing the first three
arguments for ‘defcustom’. The first argument to ‘defcustom’ is the
name of the variable. The second argument is the variable’s initial
value, if any; and this value is set only if the value has not already
been set. The third argument is the documentation.
The fourth and subsequent arguments to ‘defcustom’ specify types and
options; these are not featured in ‘defvar’. (These arguments are
optional.)
Each of these arguments consists of a keyword followed by a value.
Each keyword starts with the colon character ‘:’.
For example, the customizable user option variable ‘text-mode-hook’
looks like this:
(defcustom text-mode-hook nil
"Normal hook run when entering Text mode and many related modes."
:type 'hook
:options '(turn-on-auto-fill flyspell-mode)
:group 'wp)
The name of the variable is ‘text-mode-hook’; it has no default value;
and its documentation string tells you what it does.
The ‘:type’ keyword tells Emacs the kind of data to which
‘text-mode-hook’ should be set and how to display the value in a
Customization buffer.
The ‘:options’ keyword specifies a suggested list of values for the
variable. Usually, ‘:options’ applies to a hook. The list is only a
suggestion; it is not exclusive; a person who sets the variable may set
it to other values; the list shown following the ‘:options’ keyword is
intended to offer convenient choices to a user.
Finally, the ‘:group’ keyword tells the Emacs Customization command
in which group the variable is located. This tells where to find it.
The ‘defcustom’ macro recognizes more than a dozen keywords. For
more information, see 
Writing Customization Definitions
(elisp)Customization.
Consider ‘text-mode-hook’ as an example.
There are two ways to customize this variable. You can use the
customization command or write the appropriate expressions yourself.
Using the customization command, you can type:
M-x customize
and find that the group for editing files of text is called “Text”.
Enter that group. Text Mode Hook is the first member. You can click on
its various options, such as ‘turn-on-auto-fill’, to set the values.
After you click on the button to
Save for Future Sessions
Emacs will write an expression into your ‘.emacs’ file. It will look
like this:
(custom-set-variables
;; custom-set-variables was added by Custom.
;; If you edit it by hand, you could mess it up, so be careful.
;; Your init file should contain only one such instance.
;; If there is more than one, they won't work right.
'(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
(The ‘text-mode-hook-identify’ function tells
‘toggle-text-mode-auto-fill’ which buffers are in Text mode. It comes
on automatically.)
The ‘custom-set-variables’ function works somewhat differently than a
‘setq’. While I have never learned the differences, I modify the
‘custom-set-variables’ expressions in my ‘.emacs’ file by hand: I make
the changes in what appears to me to be a reasonable manner and have not
had any problems. Others prefer to use the Customization command and
let Emacs do the work for them.
Another ‘custom-set-...’ function is ‘custom-set-faces’. This
function sets the various font faces. Over time, I have set a
considerable number of faces. Some of the time, I re-set them using
‘customize’; other times, I simply edit the ‘custom-set-faces’
expression in my ‘.emacs’ file itself.
The second way to customize your ‘text-mode-hook’ is to set it
yourself in your ‘.emacs’ file using code that has nothing to do with
the ‘custom-set-...’ functions.
When you do this, and later use ‘customize’, you will see a message
that says
CHANGED outside Customize; operating on it here may be unreliable.
This message is only a warning. If you click on the button to
Save for Future Sessions
Emacs will write a ‘custom-set-...’ expression near the end of your
‘.emacs’ file that will be evaluated after your hand-written expression.
It will, therefore, overrule your hand-written expression. No harm will
be done. When you do this, however, be careful to remember which
expression is active; if you forget, you may confuse yourself.
So long as you remember where the values are set, you will have no
trouble. In any event, the values are always set in your initialization
file, which is usually called ‘.emacs’.
I myself use ‘customize’ for hardly anything. Mostly, I write
expressions myself.
Incidentally, to be more complete concerning defines: ‘defsubst’
defines an inline function. The syntax is just like that of ‘defun’.
‘defconst’ defines a symbol as a constant. The intent is that neither
programs nor users should ever change a value set by ‘defconst’. (You
can change it; the value set is a variable; but please do not.)
Info Catalog
eintr: Site-wide Init
eintr: Emacs Initialization
eintr: Beginning init File