Re: org-mode and mode hooks.

[Stefan Monnier]

>> ! @strong{Warning:} Only use a address@hidden @var{mode} argument when
>> ! you use @code{font-lock-add-keywords} or
>> ! @code{font-lock-remove-keywords} in your @file{.emacs} file.  When you
>> ! use these functions from a Lisp program (such as a minor mode), we
>> ! recommend that you use @code{nil} for @var{mode} (and place the call
>> ! on a hook) to avoid subtle problems due to the details of the
>> ! implementation.

>    The intention with the above text was to make a non-nil argument
>    semi-obsolete,

> That may be what the above text _intends_ to say, but it definitely is
> not what it says.

Could be, but your change does not try to fix it, instead it documents the
part of the misbehavior we happen to know about, thus legitimizing the use,
rather than discouraging i.t

> It even says to always use a non-nil argument when used from .emacs,
> probably the most important use.

There's admittedly an ambiguity when it says:

   Only use a address@hidden @var{mode} argument when you use
   @code{font-lock-add-keywords} or @code{font-lock-remove-keywords} in your
   @file{.emacs} file.

you understand it to mean

   When you use @code{font-lock-add-keywords} or
   @code{font-lock-remove-keywords} in your @file{.emacs} file, only use
   a address@hidden @var{mode} argument.

whereas I meant it to mean:

   Use a address@hidden @var{mode} argument only when you use
   @code{font-lock-add-keywords} or @code{font-lock-remove-keywords} in your
   @file{.emacs} file.

If you could fix the wording to make it more clear, I'd be grateful.
OTOH I wouldn't be grateful if you completely removed this warning like
you're suggesting to do.

> The text is very vague, for instance, it says to add them to "a hook"
> whereas there are only two hooks for which it will work properly (for
> compliant major modes), the major mode hook and
> after-change-major-mode-hook (if you want to get a "permanent local" type
> behavior).

Then please make it more precise.  E.g. by saying "mode hook".

> The misleading text in question made me lose a lot of time.

In what way, specifically?  Which hook did you try?

> In my replacement text, I document the actual situation: a non-nil
> argument does not apply to derived modes, a nil one must be added to a
> major mode hook and if used this way, it will apply to derived modes
> _if_ the major modes in question follow the conventions.

As mention, I'd like to semi-obsolete it, so I'd rather not document
it further: use at your own risk.


        Stefan