bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Drew Adams]

1. Someone on EmacsWiki asked how to tell if a given minor mode is
on.  I said to check the mode variable.  The reply was that
auto-fill-mode has no mode variable. 
 
The code shows this:
 
(put 'auto-fill-function :minor-mode-function 'auto-fill-mode)
;; FIXME: turn into a proper minor mode.
;; Add a global minor mode version of it.
(defun auto-fill-mode (&optional arg)
...
 
So it seems to be in need of a fix, but I see no bug filed against it.
 

2. What is :minor-mode-function?  It is used in a couple of places in
the Emacs Lisp sources, with no comment or other explanation.  It is
not in the Elisp manual.  It seems to be a way to associate a
different function with a minor mode - a function with a different
name from the mode itself.  For example, `auto-fill-function' is the
:minor-mode-function for `auto-fill-mode'.
 
Is this mechanism still needed if `define-minor-mode' is used?  Is it
just for compatibility with XEmacs code and legacy code?
 
How about documenting it - at least with a comment in the code
somewhere: what is for, how and when to use it.
 

In GNU Emacs 23.0.90.1 (i386-mingw-nt5.1.2600)
 of 2009-02-01 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Stefan Monnier]

> So it seems to be in need of a fix, but I see no bug filed against it.

Then file one.

> 2. What is :minor-mode-function?  It is used in a couple of places in
> the Emacs Lisp sources, with no comment or other explanation.  It is
> not in the Elisp manual.  It seems to be a way to associate a
> different function with a minor mode - a function with a different
> name from the mode itself.  For example, `auto-fill-function' is the
> :minor-mode-function for `auto-fill-mode'.
 
> Is this mechanism still needed if `define-minor-mode' is used?  Is it
> just for compatibility with XEmacs code and legacy code?

It's got nothing to do with XEmacs, AFAIK, but it does have with legacy
code such as auto-fill-function.
 
> How about documenting it - at least with a comment in the code
> somewhere: what is for, how and when to use it.
 
When to use it, is easy: never in new code.


        Stefan

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Drew Adams]

> From: Stefan Monnier Sent: Wednesday, February 25, 2009 11:57 AM
> > So it seems to be in need of a fix, but I see no bug filed 
> > against it.
> 
> Then file one.

Is it a joke? That's what this bug report is.

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Juanma Barranquero]

On Wed, Feb 25, 2009 at 18:59, Drew Adams <drew.adams@oracle.com> wrote:

> I said to check the mode variable.  The reply was that
> auto-fill-mode has no mode variable.

As you point out below, the "mode variable" for auto-fill-mode is
auto-fill-function. Is what gets set in minor-mode-alist, and its a
reliable way to know whether the mode is active or not.

> ;; FIXME: turn into a proper minor mode.
> ;; Add a global minor mode version of it.
> (defun auto-fill-mode (&optional arg)
> ...
>
> So it seems to be in need of a fix, but I see no bug filed against it.

It now says:

;; FIXME: turn into a proper minor mode.
;; Add a global minor mode version of it.
(define-minor-mode auto-fill-mode

The comment (from 2002) is still there, but the mode was converted to
define-minor-mode in 2010.

> Is this mechanism still needed if `define-minor-mode' is used? Is it
> just for compatibility with XEmacs code and legacy code?

define-minor-mode has an equivalent :variable keyword, used, as in
this case, when it is preferable to get/set the mode variable
differently, or use another variable. It is not, AFAIK, because of
XEmacs compatibility, but cases where the variable is not just a
toggle; for example, overwrite-mode uses it too, and also the new
emacs-lock-mode that I committed a few days ago.

> How about documenting it - at least with a comment in the code
> somewhere: what is for, how and when to use it.

About :minor-mode-function, Stefan already answered you that should
not be used in new code, so nothing to document.

Is anything more to be done about this bug?

    Juanma

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Drew Adams]

> Is anything more to be done about this bug?

I guess not, if people have taken a look at it and done whatever they think
needed doing (if anything).

Would someone such as the person who posed the original question about how to
tell if this minor mode is on know now how to do that for `auto-fill-mode'?

That's really the question, I think.  Are things sufficiently clear (e.g. from
the doc) that a user would now know how to tell this?  I'll let you decide.  I
don't know what, if anything, has changed since the bug report was filed.

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Juanma Barranquero]

On Sun, Jul 10, 2011 at 01:10, Drew Adams <drew.adams@oracle.com> wrote:

> I guess not, if people have taken a look at it and done whatever they think
> needed doing (if anything).

Codewise, I don't think there's anything to be done.

> Would someone such as the person who posed the original question about how to
> tell if this minor mode is on know now how to do that for `auto-fill-mode'?
>
> That's really the question, I think.  Are things sufficiently clear (e.g. from
> the doc) that a user would now know how to tell this?

Likely not, though strictly speaking, a user that needs to know the
variable name will usually be able to take a look at minor-mode-alist
and deduce it by himself.

In any case, could you please suggest a suitable change for the
docstring of auto-fill-mode?

    Juanma

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Drew Adams]

> > That's really the question, I think.  Are things 
> > sufficiently clear (e.g. from
> > the doc) that a user would now know how to tell this?
> 
> Likely not, though strictly speaking, a user that needs to know the
> variable name will usually be able to take a look at minor-mode-alist
> and deduce it by himself.
> 
> In any case, could you please suggest a suitable change for the
> docstring of auto-fill-mode?

I don't see a problem with that doc string in particular.
What did you have in mind?

This part is a little unclear:

"The value of `normal-auto-fill-function' specifies the function to use
for `auto-fill-function' when turning Auto Fill mode on."

One wonders why it speaks of `auto-fill-function', as if it is something
understood  (begs the question of its relation to `auto-fill-mode').

If you then click the `auto-fill-function' link you get doc on that function,
but it's not clear at all what it has to do with `auto-fill-mode'.

It does say also this: "auto-fill-function is also a variable."  But the name is
neither quoted (`...') nor a link to help on that var.  And there is nothing
saying  anything about what you said: that the variable tells you whether
`auto-fill-mode' is on (which was the OP question).

Perhaps we should at least add something like this to the `auto-fill-mode' doc:

"When `auto-fill-mode' is on, variable `auto-fill-function' is non-`nil'."

bug#2470: 23.0.90; auto-fill-mode, :minor-mode-function

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Perhaps we should at least add something like this to the `auto-fill-mode' doc:
>
> "When `auto-fill-mode' is on, variable `auto-fill-function' is non-`nil'."

I've now added this.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/