GNU bug report logs - #6151
mystery arguments of define-minor-mode + describe-function

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6151 in the body.
You can then email your comments to 6151 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: jidanni <at> jidanni.org
To: bug-gnu-emacs <at> gnu.org
Subject: mystery arguments of define-minor-mode + describe-function
Date: Mon, 10 May 2010 18:02:37 +0800

Some describe-function results add a mystery argument ARG, not visible
in the corresponding lisp code.

Or maybe it is visible, but not to your average reader.

E.g., here's what describe-function says

    longlines-mode is an interactive compiled Lisp function in
    `longlines.el'.

    (longlines-mode &optional ARG)

    Toggle Long Lines mode.
    In Long Lines mode, long lines are wrapped if they extend beyond

And here's where we get placed when clicking on longlines.el above

    ;;;###autoload
    (define-minor-mode longlines-mode
      "Toggle Long Lines mode.
    In Long Lines mode, long lines are wrapped if they extend beyond

Message #8 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: jidanni <at> jidanni.org
Cc: 6151 <at> debbugs.gnu.org
Subject: Re: bug#6151: mystery arguments of define-minor-mode + 
	describe-function
Date: Mon, 10 May 2010 12:45:19 +0200

On Mon, May 10, 2010 at 12:02,  <jidanni <at> jidanni.org> wrote:

> Some describe-function results add a mystery argument ARG, not visible
> in the corresponding lisp code.
>
> Or maybe it is visible, but not to your average reader.

Among other things, `define-minor-mode' defines a function, in this
case longlines-mode; and that function, like all minor modes, has an
arg to turn it on or off. So it's not `describe-function' which adds a
"mystery argument", but the docstring for the modes, that sometimes
lacks the relevant info.

That said, any Emacs user should be by now used to minor modes having
such an argument...

    Juanma

Message #11 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: jidanni <at> jidanni.org
To: lekktu <at> gmail.com
Cc: 6151 <at> debbugs.gnu.org
Subject: Re: bug#6151: mystery arguments of define-minor-mode +
	describe-function
Date: Mon, 10 May 2010 18:57:06 +0800

>>>>> "JB" == Juanma Barranquero <lekktu <at> gmail.com> writes:
JB> "mystery argument", but the docstring for the modes, that sometimes
JB> lacks the relevant info.

Perhaps an inventory should be made of these defective docstrings, and
then they should be repaired.

JB> That said, any Emacs user should be by now used to minor modes having
JB> such an argument...

I'm the dud-type user sometimes referred to in http://www.useit.com/alertbox/ .

Message #14 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: jidanni <at> jidanni.org
Cc: 6151 <at> debbugs.gnu.org
Subject: Re: bug#6151: mystery arguments of define-minor-mode + 
	describe-function
Date: Mon, 10 May 2010 13:02:13 +0200

On Mon, May 10, 2010 at 12:57,  <jidanni <at> jidanni.org> wrote:

> Perhaps an inventory should be made of these defective docstrings, and
> then they should be repaired.

There's such an inventory: it is called Emacs bugs list :-)

> I'm the dud-type user sometimes referred to in http://www.useit.com/alertbox/ .

That meaning?

    Juanma

Message #17 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: Lennart Borgman <lennart.borgman <at> gmail.com>
To: Juanma Barranquero <lekktu <at> gmail.com>
Cc: 6151 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#6151: mystery arguments of define-minor-mode + 
	describe-function
Date: Mon, 10 May 2010 13:39:06 +0200

On Mon, May 10, 2010 at 12:45 PM, Juanma Barranquero <lekktu <at> gmail.com> wrote:
> On Mon, May 10, 2010 at 12:02,  <jidanni <at> jidanni.org> wrote:
>
>> Some describe-function results add a mystery argument ARG, not visible
>> in the corresponding lisp code.
>>
>> Or maybe it is visible, but not to your average reader.
>
> Among other things, `define-minor-mode' defines a function, in this
> case longlines-mode; and that function, like all minor modes, has an
> arg to turn it on or off. So it's not `describe-function' which adds a
> "mystery argument", but the docstring for the modes, that sometimes
> lacks the relevant info.


Maybe the define-minor-mode should always add to the docstring that it
is a minor mode and provide links between the minor mod variable and
the minor mode function?

Message #20 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lennart Borgman <lennart.borgman <at> gmail.com>
Cc: Juanma Barranquero <lekktu <at> gmail.com>, 6151 <at> debbugs.gnu.org,
	jidanni <at> jidanni.org
Subject: Re: bug#6151: mystery arguments of define-minor-mode +
	describe-function
Date: Mon, 10 May 2010 11:33:04 -0400

> Maybe the define-minor-mode should always add to the docstring that it
> is a minor mode and provide links between the minor mod variable and
> the minor mode function?

Yes, it could check the presence of "ARG" in the provided docstring or
something like that and add a standard blurb if the docstring doesn't
already have it.


        Stefan

Message #27 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: jidanni <at> jidanni.org
Cc: 6151 <at> debbugs.gnu.org
Subject: Re: mystery arguments of define-minor-mode + describe-function
Date: Wed, 13 Jul 2011 23:30:15 +0200

jidanni <at> jidanni.org writes:

> Some describe-function results add a mystery argument ARG, not visible
> in the corresponding lisp code.
>
> Or maybe it is visible, but not to your average reader.
>
> E.g., here's what describe-function says
>
>     longlines-mode is an interactive compiled Lisp function in
>     `longlines.el'.
>
>     (longlines-mode &optional ARG)
>
>     Toggle Long Lines mode.
>     In Long Lines mode, long lines are wrapped if they extend beyond
>
> And here's where we get placed when clicking on longlines.el above
>
>     ;;;###autoload
>     (define-minor-mode longlines-mode
>       "Toggle Long Lines mode.
>     In Long Lines mode, long lines are wrapped if they extend beyond

I don't see a bug here -- this is how `define-minor-mode' works.

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

Message #30 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Juanma Barranquero <lekktu <at> gmail.com>, 6151 <at> debbugs.gnu.org,
	Lennart Borgman <lennart.borgman <at> gmail.com>, jidanni <at> jidanni.org
Subject: Re: bug#6151: mystery arguments of define-minor-mode +
	describe-function
Date: Wed, 13 Jul 2011 23:31:01 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> Maybe the define-minor-mode should always add to the docstring that it
>> is a minor mode and provide links between the minor mod variable and
>> the minor mode function?
>
> Yes, it could check the presence of "ARG" in the provided docstring or
> something like that and add a standard blurb if the docstring doesn't
> already have it.

Opening a new "wishlist" bug report for this would be appropriate.

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

Message #33 received at 6151 <at> debbugs.gnu.org (full text, mbox):

From: jidanni <at> jidanni.org
To: larsi <at> gnus.org
Cc: lekktu <at> gmail.com, 6151 <at> debbugs.gnu.org, lennart.borgman <at> gmail.com,
	monnier <at> iro.umontreal.ca
Subject: Re: bug#6151: mystery arguments of define-minor-mode +
	describe-function
Date: Thu, 14 Jul 2011 08:57:39 +0800

>>>>> "LMI" == Lars Magne Ingebrigtsen <larsi <at> gnus.org> writes:
LMI> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>> Maybe the define-minor-mode should always add to the docstring that it
>>> is a minor mode and provide links between the minor mod variable and
>>> the minor mode function?
>> 
>> Yes, it could check the presence of "ARG" in the provided docstring or
>> something like that and add a standard blurb if the docstring doesn't
>> already have it.

LMI> Opening a new "wishlist" bug report for this would be appropriate.
Somebody who understands the issue please do. Even though I was the
submitter, this is all now beyond my comprehension abilities.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.