bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Mark Harig via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 507 bytes --]

Emacs Maintainers,
   In the documentation string in define-minor-mode edebug-mode in edebug.el:
   1. The option `edebug-on-signal' is listed, but it does not exist in the file.
   2. The following options, which are described in (elisp) Edebug Options, are missing:      edebug-sit-for-seconds, edebug-sit-on-break, edebug-behavior-alist,      edebug-new-definition-function, edebug-after-instrumentation-function
As mentioned in the Subject line, this is in GNU Emacs version 27.1.
---

[-- Attachment #2: Type: text/html, Size: 1991 bytes --]

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Stefan Kangas]

Mark Harig via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

> Emacs Maintainers,
>    In the documentation string in define-minor-mode edebug-mode in edebug.el:
>    1. The option `edebug-on-signal' is listed, but it does not exist in the file.

Indeed, I find no matches grepping in the repository for
`edebug-on-signal', nor in the git log.

Perhaps it should just be removed?

> 2. The following options, which are described in (elisp) Edebug Options, are missing:      edebug-sit-for-seconds, edebug-sit-on-break, edebug-behavior-alist,      edebug-new-definition-function, edebug-after-instrumentation-function

Maybe instead of maintaining a list, we should just point users to `M-x
customize-group RET edebug RET'.  Or just remove the list and say
nothing.

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Mark Harig via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1227 bytes --]


> > Emacs Maintainers,
> >    In the documentation string in define-minor-mode edebug-mode in edebug.el:
> >    1. The option `edebug-on-signal' is listed, but it does not exist in the file.

> Indeed, I find no matches grepping in the repository for
> `edebug-on-signal', nor in the git log.
> 
> Perhaps it should just be removed?
Yes. That is the intent of the report, to get the non-existent option removed.

> > 2. The following options, which are described in (elisp) Edebug Options, are missing:      > >    edebug-sit-for-seconds, edebug-sit-on-break, edebug-behavior-alist,> >    edebug-new-definition-function, edebug-after-instrumentation-function
>
> Maybe instead of maintaining a list, we should just point users to `M-x
> customize-group RET edebug RET'.  Or just remove the list and say
> nothing.
In edebug mode, type '?' to list help for the mode.  
This will list the keys defined for the mode followed by a list of the options.The options are listed as help-mode links.  The links can be used to displayhelp for each of the options, including their current value.  This provides aquick method for looking up help or checking the values of the (many) edebugoptions.
---

[-- Attachment #2: Type: text/html, Size: 3592 bytes --]

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Lars Ingebrigtsen]

Mark Harig <idirectscm@aim.com> writes:

> Yes. That is the intent of the report, to get the non-existent option removed.

I've now removed this from the doc string in Emacs 28.

>> Maybe instead of maintaining a list, we should just point users to `M-x
>> customize-group RET edebug RET'.  Or just remove the list and say
>> nothing.
>
> In edebug mode, type '?' to list help for the mode.  
>
> This will list the keys defined for the mode followed by a list of the options.
> The options are listed as help-mode links.  The links can be used to display
> help for each of the options, including their current value.  This provides a
> quick method for looking up help or checking the values of the (many) edebug
> options.

Yeah, it's somewhat unconventional, but I think it's otherwise fine as is.

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

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 11 Nov 2020 10:22:13 -0600
> 
> Mark Harig via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" <bug-gnu-emacs@gnu.org> writes:
> 
> > Emacs Maintainers,
> >    In the documentation string in define-minor-mode edebug-mode in edebug.el:
> >    1. The option `edebug-on-signal' is listed, but it does not exist in the file.
> 
> Indeed, I find no matches grepping in the repository for
> `edebug-on-signal', nor in the git log.
> 
> Perhaps it should just be removed?

Yes, please.

> > 2. The following options, which are described in (elisp) Edebug Options, are missing:      edebug-sit-for-seconds, edebug-sit-on-break, edebug-behavior-alist,      edebug-new-definition-function, edebug-after-instrumentation-function
> 
> Maybe instead of maintaining a list, we should just point users to `M-x
> customize-group RET edebug RET'.  Or just remove the list and say
> nothing.

I think we should remove the list from the doc string, yes.  It is
unusual for a doc string of a mode to include an exhaustive list of
all of its customization options; in general, the feature's group
should be enough to discover all of them.  And the manual documents
the most important ones.

Thanks.

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I think we should remove the list from the doc string, yes.  It is
> unusual for a doc string of a mode to include an exhaustive list of
> all of its customization options; in general, the feature's group
> should be enough to discover all of them.  And the manual documents
> the most important ones.

The use case here is the `?' command when edebugging, which makes the
list somewhat useful.

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

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Mark Harig via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 717 bytes --]

> The use case here is the `?' command when edebugging, which makes the
> list somewhat useful.

Note also that of the 22 options documented in (elisp) Edebug Options, six (6) of the toggle (on/off) options are included in the Edebug/Optionsmenu:
- Edebug All Defs- Edebug All Forms- Tracing- Test Coverage- Save Windows- Save Point
Five (5) other toggle (on/off) options are available but are not includedin the Edebug/Options menu: 
1. edebug-eval-macro-args2. edebug-continue-kbd-macro3. edebug-unwrap-results4. edebug-on-quit5. edebug-sit-on-break
This omission from the Options sub-menu might be intentional (minor options?)or an oversight (maintenance by different developers over the years).
---

[-- Attachment #2: Type: text/html, Size: 5021 bytes --]

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>,  44577@debbugs.gnu.org,
>   idirectscm@aim.com
> Date: Thu, 12 Nov 2020 14:54:19 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think we should remove the list from the doc string, yes.  It is
> > unusual for a doc string of a mode to include an exhaustive list of
> > all of its customization options; in general, the feature's group
> > should be enough to discover all of them.  And the manual documents
> > the most important ones.
> 
> The use case here is the `?' command when edebugging, which makes the
> list somewhat useful.

Cannot the '?' command map over the customization group instead?  It's
a maintenance burden to keep that list exhaustive and up-to-date, just
so '?' could show all of the options.

bug#44577: 27.1; Missing options in definition of edebug-mode in edebug.el

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Cannot the '?' command map over the customization group instead?  It's
> a maintenance burden to keep that list exhaustive and up-to-date, just
> so '?' could show all of the options.

Sure, writing a new command for `?' sounds like a good idea.

In slightly related news, I was just looking at the dired-mode doc
string, which has a similar list of user options, but the added
confusing text.

Does anybody know what this refers to?  I mean, the `C-h v' is probably
just left-over cruft from before `this-stuff' are links, but...  "rename
this buffer"?

Oh, perhaps that's from before the *Help* buffer had prev/next
navigation commands?

----

Customization variables (rename this buffer and type C-h v on each line
for more info):

  ‘dired-listing-switches’
  ‘dired-trivial-filenames’
  ‘dired-marker-char’
  ‘dired-del-marker’
  ‘dired-keep-marker-rename’
  ‘dired-keep-marker-copy’
  ‘dired-keep-marker-hardlink’
  ‘dired-keep-marker-symlink’

Hooks (use C-h v to see their documentation):

  ‘dired-before-readin-hook’
  ‘dired-after-readin-hook’
  ‘dired-mode-hook’


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