lispref/hooks.texi

lispref/hooks.texi

[Glenn Morris]

lispref/hooks.texi is an appendix to the Elisp manual that includes a
list of hooks (about 80). It is very difficult to keep the list up to
date with every hook in Emacs, and I'm not sure that a list of hooks is
a useful thing to have anyway. If I want to know what I can do when
Emacs deletes a frame, I'll look in the "Deleting Frames" section, not
in a list of hooks to see if anything happens to look relevant.

How about merging the general information about hooks from the start of
hooks.texi into the section "Hooks" in modes.texi (if not there
already), and removing hooks.texi?

If for some reason an index of hooks is needed, it should be
automatically generated, like the function index. But I can't see that
it is useful.

Re: lispref/hooks.texi

[Glenn Morris]

I just noticed

  Appendix G Buffer-Local Variables

  The table below lists the general-purpose Emacs variables that
  automatically become buffer-local in each buffer.

and

  Appendix H Standard Keymaps

  The following symbols are used as the names for various keymaps.

about which I would say much the same.

The latter doesn't pretend to be exhaustive, perhaps it should stay. But
I can't get excited about a list which includes such gems as
"edit-tab-stops-map: A sparse keymap used in `edit-tab-stops'", and
"facemenu-foreground-menu: The sparse keymap that displays the
Foreground Color submenu of the Text Properties menu."
Things like ctl-x-5-map are more useful; but already mentioned in "22.6
Prefix Keys".

(I assume these appendices date from a simpler time when it was actually
possible to list ALL the buffer-local variables, or whatever.)

Re: lispref/hooks.texi

[Chong Yidong]

Glenn Morris <rgm@gnu.org> writes:

> How about merging the general information about hooks from the start
> of hooks.texi into the section "Hooks" in modes.texi (if not there
> already), and removing hooks.texi?

The idea behind this appendix, I think, is that if someone is not sure
which hook to put a function onto, it's good to have a list of possible
hooks to use.

If we agree that that's its purpose, I think we should take out all the
hooks not related to general Emacs editing, e.g. `blink-paren-function',
`diary-*-hook', and `font-lock-beginning-of-syntax-function'.  This will
also make hooks.texi easier to maintain.

> I just noticed
>   Appendix G Buffer-Local Variables
> and
>   Appendix H Standard Keymaps
> about which I would say much the same.

Appendix G seems pretty useless.  Appendix H can be kept, but we should
remove all the mode-specific keymaps, like `apropos-mode-map' and
`c-mode-map', and just state that each mode has an associated keymap.

Re: lispref/hooks.texi

[Stefan Monnier]

> The idea behind this appendix, I think, is that if someone is not sure
> which hook to put a function onto, it's good to have a list of possible
> hooks to use.

Right, I can imagine it to be convenient when you're looking around for
window-configuration-change-hook, post-command-hook, and things along
these lines, where the set of possible hooks is not related to
a single chapter.


        Stefan

Re: lispref/hooks.texi

[Eli Zaretskii]

> From: Chong Yidong <cyd@gnu.org>
> Date: Sun, 26 Feb 2012 15:49:08 +0800
> Cc: emacs-devel@gnu.org
> 
> If we agree that that's its purpose, I think we should take out all the
> hooks not related to general Emacs editing, e.g. `blink-paren-function',
> `diary-*-hook', and `font-lock-beginning-of-syntax-function'.  This will
> also make hooks.texi easier to maintain.

Isn't it possible to craft some script that would extract all the
hooks and put them in there?  That would make the maintenance burden
about zero.

RE: lispref/hooks.texi

[Drew Adams]

> > The idea behind this appendix, I think, is that if someone 
> > is not sure which hook to put a function onto, it's good
> > to have a list of possible hooks to use.
> 
> Right, I can imagine it to be convenient when you're looking 
> around for window-configuration-change-hook, post-command-hook,
> and things along these lines, where the set of possible hooks
> is not related to a single chapter.

(So far, I have no opinion about whether the appendix is a good idea.  Note,
though, that there is some information there besides the list of hooks.  That
info could be moved to node `Hooks' if the appendix is removed.)

I would just point out that any particular hooks mentioned in a manual are
presumably indexed there, so `i' and `Info-apropos' should help readers find the
principal chapters that discuss them.  And `C-s' should help them find any
additional occurrences.

If part of your point is that it can be helpful to know about hooks that are not
mentioned in a manual, then `apropos-variable' should help with that.

Wouldn't `C-u apropos-variable -\(hooks?\|functions\)$ RET' list the (loaded or
autoloaded) normal and abnormal hooks?  If so, maybe just mention that somewhere
in the manual (e.g. `(emacs) Hooks' or `(elisp) Hooks'), instead of trying to
list hooks in the manual explicitly?

Finally, a comment about having an appendix that lists only some of the hooks -
e.g., removing "`blink-paren-function', `diary-*-hook'" etc. as Yidong
suggested:

In that case, we should no longer say that these are the "standard hook
variables".  We should be clear that the list is limited to a selection of hooks
"related to general Emacs editing".  And we should probably rename the node from
`Standard Hooks' to `Common Editing Hooks' or some such.