What is a hook?

Question

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?

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.