Just to clarify... For example, in this doc:

A hook is a Lisp variable which holds a list of functions, to be called on some well-defined occasion. (This is called running the hook.) The individual functions in the list are called the hook functions of the hook. For example, the hook kill-emacs-hook runs just before exiting Emacs...

I think it's saying there is a variable (symbol) named kill-emacs-hookthat represents a list of a set of "hook functions" that will run when the kill-emacs-hook is evaluated, thereby performing those functions. Correct? Then

(add-hook 'text-mode-hook 'auto-fill-mode)

is adding auto-fill-mode to that list identified by text-mode-hook in addition to what's already there. Good. Now 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)

where it seems we are either creating or altering the text-mode-hook. I'm now confused as to the nature of hooks and their relationship with defcustom. My logical choice is that this code is creating a variable text-mode-hook which is of "type" (don't know what is meant by types in elisp) hook. Is this, indeed, supposed to be the initial creation of the hook text-mode-hook? If so, what's up with the "options?" Are those the supposed hook functions, or something else?

  • 1
    From your link: «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.» Aug 30, 2015 at 17:38

1 Answer 1


Your understanding of Emacs Lisp notion of hook is absolutely correct. Indeed, “normal” hooks are just lists of functions (every function doesn't take arguments, otherwise it's not usually called “hook” or “normal hook” in Emacs Lisp).

Most of these variables have names ending with -hook. They are normal hooks, run by means of run-hooks. The value of such a hook is a list of functions; the functions are called with no arguments and their values are completely ignored. The recommended way to put a new function on such a hook is to call add-hook.

The variables whose names end in -functions are usually abnormal hooks (some old code may also use the deprecated -hooks suffix); their values are lists of functions, but these functions are called in a special way (they are passed arguments, or their return values are used). The variables whose names end in -function have single functions as their values.

Customization interface is a different thing. All the difference between defvar and defcustom is that the latter allows user to edit the variable via “customize” interface. This interface can facilitate editing of certain types of data, so for example if you're saying that :type of text-mode-hook is hook, then customization interface makes sure that text-mode-hook is always a list of functions. Furthermore, you can specify which options are recommended with :options argument.

So, your understanding is correct and defcustom and its options are just a way to instruct Emacs, so it can better assist user when he/she uses “customize” interface.

  • But this example of a defcustom is not great because text-mode-hook already exists; it's included already. Right? Now, if I wrote my own mode and then wanted customization, I'd do this. My confusion is this example is really creating text-mode-hook, not altering it. Is that a correct understanding? And if this is indeed creating a new text-mode-hook, the :options is offering those two functions as options to do an add-hook to the list, right?
    – 147pm
    Aug 30, 2015 at 18:46
  • @147pm, this example just shows you how some part of Emacs' existing code defines customizable variable that represents hook. In nutshell defcustom just defines new variables. In this particular example text-mode-hook is created and its initial value is nil. Customization interface is also told that recommended values to have in this list are turn-on-auto-fill and flyspell-mode. You however can set text-mode-hook to anything you like programmatically, it's normal variable. You can use add-hook with any other functions too. Aug 30, 2015 at 19:06
  • @147, in other words, all the keyword arguments are just hints for customization system, they don't make any difference outside of it. Without the hints that code amounts to (defvar text-mode-hook nil). Aug 30, 2015 at 19:12
  • But is this defcustom how the hook is initially being created? That what it looks like. In other words this example is taken from deep in the bowels of Emacs code somewhere.
    – 147pm
    Aug 30, 2015 at 19:43
  • @147pm, yes, correct. Aug 30, 2015 at 20:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.