GNU bug report logs - #50146
26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'

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 50146 in the body.
You can then email your comments to 50146 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: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; Doc of `MODE-' things created by `define-globalized-minor-mode'
Date: Sat, 21 Aug 2021 15:46:38 +0000

A user can be puzzled by `C-h v' and `C-h f' completion showing the
names of variables and functions that get created by macro
`define-globalized-minor-mode'.  `C-h v' and `C-h f' are primary means
of discovery.

If a user chooses such a name from completion she's not helped, but
further pushed into puzzlement.  She'll see something like this:

  foo-mode-set-explicitly is a Lisp function in 'foobar.el'.

  (foo-mode-set-explicitly)

And clicking that file-name link won't help at all, but will add to the
confusion.

Can we not fix this somehow?

If nothing really reasonable can be found to fix this, maybe a kludge
improvement would be to at least add a doc string to such a created
thing, which says that the thing was created by
`define-globalized-minor-mode' and perhaps points to that macro.  And
perhaps that doc string could point to the corresponding mode command,
so users can consult its doc (which won't mention the thing created, but
at least might get users closer to what's going on).

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19042
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 50146 <at> debbugs.gnu.org
Subject: Re: bug#50146: 26.3;
 Doc of `MODE-' things created by `define-globalized-minor-mode'
Date: Sat, 21 Aug 2021 18:59:33 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Sat, 21 Aug 2021 15:46:38 +0000
> 
> A user can be puzzled by `C-h v' and `C-h f' completion showing the
> names of variables and functions that get created by macro
> `define-globalized-minor-mode'.  `C-h v' and `C-h f' are primary means
> of discovery.
> 
> If a user chooses such a name from completion she's not helped, but
> further pushed into puzzlement.  She'll see something like this:
> 
>   foo-mode-set-explicitly is a Lisp function in 'foobar.el'.
> 
>   (foo-mode-set-explicitly)
> 
> And clicking that file-name link won't help at all, but will add to the
> confusion.
> 
> Can we not fix this somehow?

Please provide a specific example or two.  I tried looking at
global-visual-line-mode, and didn't see anything like what you
describe.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "50146 <at> debbugs.gnu.org" <50146 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#50146: 26.3; Doc of `MODE-' things created
 by `define-globalized-minor-mode'
Date: Sat, 21 Aug 2021 16:25:59 +0000

> Please provide a specific example or two.  I tried looking at
> global-visual-line-mode, and didn't see anything like what you
> describe.

emacs -Q

(define-minor-mode foo-mode "..."
  :init-value nil :global t :group 'convenience)

(defun turn-on-foo-mode () "..." (foo-mode 1))

(define-globalized-minor-mode foo-global-mode
  foo-mode turn-on-foo-mode :group 'convenience)

C-h f foo TAB
___

You see this in *Completions*:

Click on a completion to select it.
In this buffer, type RET to select the completion near point.

Possible completions are:
foo-global-mode 	foo-global-mode-check-buffers
foo-global-mode-cmhh 	foo-global-mode-enable-in-buffers
foo-mode 	foo-mode-set-explicitly
footnote-mode
___

`foo-mode-set-explicitly' is created by the macro.
If you click that name in *Completions* you see this:
___

foo-mode-set-explicitly is a Lisp function.

(foo-mode-set-explicitly)

Not documented.
___

Same thing, if you use `C-h v foo TAB' and choose
`foo-mode-set-explicitly': the help for the var is
just as vacuous.

These automatically created things seems like noise,
for users.  If they're intended to be under the covers
then maybe they should be more under the covers.

If they're intended to be usable by, or understandable
to, users, then maybe they should have some doc that at
least tries to dispel some of the possible confusion.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 50146 <at> debbugs.gnu.org
Subject: Re: [External] : Re: bug#50146: 26.3; Doc of `MODE-' things created
 by `define-globalized-minor-mode'
Date: Sat, 21 Aug 2021 19:46:16 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "50146 <at> debbugs.gnu.org" <50146 <at> debbugs.gnu.org>
> Date: Sat, 21 Aug 2021 16:25:59 +0000
> 
> C-h f foo TAB
> ___
> 
> You see this in *Completions*:
> 
> Click on a completion to select it.
> In this buffer, type RET to select the completion near point.
> 
> Possible completions are:
> foo-global-mode 	foo-global-mode-check-buffers
> foo-global-mode-cmhh 	foo-global-mode-enable-in-buffers
> foo-mode 	foo-mode-set-explicitly
> footnote-mode
> ___
> 
> `foo-mode-set-explicitly' is created by the macro.
> If you click that name in *Completions* you see this:
> ___
> 
> foo-mode-set-explicitly is a Lisp function.
> 
> (foo-mode-set-explicitly)
> 
> Not documented.
> ___

When I see something that is "not documented", I conclude that it's an
internal function without a need for documentation.  YMMV.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50146 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#50146: 26.3; Doc of `MODE-' things created by
 `define-globalized-minor-mode'
Date: Sun, 22 Aug 2021 16:49:19 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> When I see something that is "not documented", I conclude that it's an
> internal function without a need for documentation.  YMMV.

Yup -- it's an internal function used by the easy-mmode machinery, and
as such shouldn't be documented.  So I'm closing this bug report.

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

Previous Next

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