GNU bug report logs - #9445
24.0.50; `help-make-xrefs' has bad logic

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 9445 in the body.
You can then email your comments to 9445 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>
Subject: 24.0.50; `help-make-xrefs' has bad logic
Date: Mon, 5 Sep 2011 14:21:28 -0700

1. The doc string is inaccurate and misleading.  It says:
 
"Faces only get cross-referenced if
preceded or followed by the word `face'.
 
What really seems to happen is that if preceded by the word `face' then
ONLY a face is looked for to cross-reference.  That is not at all the
same thing.
 
It also says:
 
"Variables without
variable documentation do not get cross-referenced, unless
preceded by the word `variable' or `option'."
 
Again, what really seems to happen is that if preceded by one of those
words then ONLY a variable or option, resp., is looked for to
cross-reference.  Not at all the same thing.
 

2. Besides the doc describing the behavior incorrectly, the behavior itself is
broken/poor.  What SHOULD happen, if you must key off of
the preceding word, is that the type of thing guessed at due to that
preceding word is looked for FIRST, but not EXCLUSIVELY.

You simply look for `variable', and if you find it then you check for a
documented variable of that name.  That's silly - not enough.
 
E.g., if a function name `foo' happens to be preceded by `face',
`variable', or `option', and if there is no corresponding foo `face',
`variable', or `option', then it SHOULD pick up and cross-reference
the FUNCTION `foo'.

In sum, try your heuristics in order until you find a match or there is no
match.  Do not just try one and then give up.
 
If you introduce a sketchy heuristic such as using the preceding word,
then at least follow through and DTRT if no xref of that corresponding
type can be found.  Do not just ASSUME that the preceding word is the
be-all and end-all, necessarily determining perfectly the proper type.
It's just a FIRST GUESS.  If it doesn't match, then DTRT - look for a
function, command, etc.


FWIW, it took me a while to figure out why, in a list of command names and their
descriptions, there was an occasional command name that had no link.  It turned
out that the preceding line (the end of the previous commands' one-liner
description) ended with "face" or "option" etc.  Sheesh.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-08-29 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt'
 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 9445 <at> debbugs.gnu.org, 24842 <at> debbugs.gnu.org
Subject: Re: bug#9445: 24.0.50; `help-make-xrefs' has bad logic
Date: Tue, 07 Sep 2021 20:00:20 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> `help-make-xrefs' tries to guess the type of a symbol that is enclosed
> in `...', in help.
>
> This determination needs to to be improved, or else programmers need
> some way to inhibit it when it turns out to be inappropriate.
>
> Example: This is part of a doc string I have:
>
> `isearchp-movement-unit-alist'\t- units and their movement functions
> `isearchp-on-demand-action-function'\t- on-demand action function
> `isearchp-prompt-for-filter-name'\t- when to ask for filter name
>
> Those symbols are all variables (in fact, user options), not functions.
> but the word "function" at the end of the second line causes the quoted
> symbol that follows it to be considered as a function name.  And then,
> because it is not `fboundp', it gets no link.  It should instead get a
> variable-name link to its definition.

There wasn't any recipe for reproduction here, so I came up with this:

(defun foo1 ())
(defvar foo2 ())

(defvar foo nil
  "
`foo1' something.
`foo1'\t- units and their movement functions
`foo2' something.
`foo2'\t- units and their movement functions
")

When evaling this and then `C-h v foo RET' in Emacs 28, all these are
recognised as symbols in the *Help* buffer, so this seems to work for me
in this test case, at least.

Are you still seeing this issue in recent Emacs versions?

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
 "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#9445: 24.0.50; `help-make-xrefs' has bad
 logic
Date: Tue, 7 Sep 2021 19:24:24 +0000

> Are you still seeing this issue in recent Emacs versions?

Thanks for testing.  This was apparently fixed in release 24.
The bug was filed in a snapshot between 23 and 24.  (The bug
still exists in 23.)

So this can be closed.  Thx.

(I can't speak to the merges with other bugs, however.
Maybe they should not all be closed.)

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
 "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
Subject: Re: [External] : Re: bug#9445: 24.0.50; `help-make-xrefs' has bad
 logic
Date: Tue, 07 Sep 2021 21:28:22 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

>> Are you still seeing this issue in recent Emacs versions?
>
> Thanks for testing.  This was apparently fixed in release 24.
> The bug was filed in a snapshot between 23 and 24.  (The bug
> still exists in 23.)
>
> So this can be closed.  Thx.

Thanks; closing this, then.

> (I can't speak to the merges with other bugs, however.
> Maybe they should not all be closed.)

Yeah, they aren't about the same thing as this one, so I've now
de-merged them.

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

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

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 9445 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>,
 24842 <at> debbugs.gnu.org
Subject: Re: bug#24842: bug#9445: 24.0.50; `help-make-xrefs' has bad logic
Date: Tue, 07 Sep 2021 21:44:40 +0200

On Tue, 07 Sep 2021 20:00:20 +0200 Lars Ingebrigtsen <larsi <at> gnus.org> wrote:

> Drew Adams <drew.adams <at> oracle.com> writes:
>
>> `help-make-xrefs' tries to guess the type of a symbol that is enclosed
>> in `...', in help.
>>
>> This determination needs to to be improved, or else programmers need
>> some way to inhibit it when it turns out to be inappropriate.
>>
>> Example: This is part of a doc string I have:
>>
>> `isearchp-movement-unit-alist'\t- units and their movement functions
>> `isearchp-on-demand-action-function'\t- on-demand action function
>> `isearchp-prompt-for-filter-name'\t- when to ask for filter name
>>
>> Those symbols are all variables (in fact, user options), not functions.
>> but the word "function" at the end of the second line causes the quoted
>> symbol that follows it to be considered as a function name.  And then,
>> because it is not `fboundp', it gets no link.  It should instead get a
>> variable-name link to its definition.
>
> There wasn't any recipe for reproduction here, so I came up with this:
>
> (defun foo1 ())
> (defvar foo2 ())
>
> (defvar foo nil
>   "
> `foo1' something.
> `foo1'\t- units and their movement functions
> `foo2' something.
> `foo2'\t- units and their movement functions
> ")
>
> When evaling this and then `C-h v foo RET' in Emacs 28, all these are
> recognised as symbols in the *Help* buffer, so this seems to work for me
> in this test case, at least.
>
> Are you still seeing this issue in recent Emacs versions?

On Tue, 07 Sep 2021 21:28:22 +0200 Lars Ingebrigtsen <larsi <at> gnus.org> wrote:

> Drew Adams <drew.adams <at> oracle.com> writes:
>
>>> Are you still seeing this issue in recent Emacs versions?
>>
>> Thanks for testing.  This was apparently fixed in release 24.
>> The bug was filed in a snapshot between 23 and 24.  (The bug
>> still exists in 23.)
>>
>> So this can be closed.  Thx.
>
> Thanks; closing this, then.

But the recipe Lars gave doesn't quite match the description Drew gave,
IIUC: if in the recipe you change the first occurrence of `functions' to
`function', then eval and do `C-h v foo', then the first occurrence of
`foo2' in the doc string is not turned into a link.  Isn't that what the
problem was, and still is?

Steve Berman

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 9445 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>,
 24842 <at> debbugs.gnu.org
Subject: Re: bug#24842: bug#9445: 24.0.50; `help-make-xrefs' has bad logic
Date: Tue, 07 Sep 2021 21:55:20 +0200

Stephen Berman <stephen.berman <at> gmx.net> writes:

> But the recipe Lars gave doesn't quite match the description Drew gave,
> IIUC: if in the recipe you change the first occurrence of `functions' to
> `function', then eval and do `C-h v foo', then the first occurrence of
> `foo2' in the doc string is not turned into a link.  Isn't that what the
> problem was, and still is?

Yup.  So here's the recipe to reproduce the problem:

(defun foo1 ())
(defvar foo2 ())

(defvar foo nil
  "
`foo1'\t- on-demand action function
`foo2'")

So I'm reopening the bug report.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stephen Berman <stephen.berman <at> gmx.net>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
 "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#24842: bug#9445: 24.0.50; `help-make-xrefs'
 has bad logic
Date: Tue, 7 Sep 2021 20:13:02 +0000

> > (defun foo1 ())
> > (defvar foo2 ())
> >
> > (defvar foo nil
> >   "
> > `foo1' something.
> > `foo1'\t- units and their movement functions
> > `foo2' something.
> > `foo2'\t- units and their movement functions
> > ")
> >
> But the recipe Lars gave doesn't quite match the description Drew gave,
> IIUC: if in the recipe you change the first occurrence of `functions'
> to
> `function', then eval and do `C-h v foo', then the first occurrence of
> `foo2' in the doc string is not turned into a link.  Isn't that what
> the
> problem was, and still is?

Hm.  You're right, Stephen.  But not with just
that change, I think.  And it looks like the
problem is maybe for defun doc strings but not
for defvar doc strings?  (But see below.)

(defun foo1 ())
(defvar foo2 ())
(defvar foo nil
  "
`foo2' something.
`foo2'\t- units and their movement function
`foo1' something.
`foo1'\t- units and their movement function
")

(defun bar ()
  "
`foo2' something.
`foo2'\t- units and their movement function
`foo' something.
`foo'\t- units and their movement function
" 42)

`C-h v foo' shows links everywhere, for both
var foo2 and function foo1.

But `C-h f bar' does not show a link for the
first occurrence of `foo'.
___

What's odd, and the reason I thought this was
fixed, is that I checked  (using `emacs -Q')
the doc string in my code that I was reporting
about.  That doc string is for a function, not
a variable, but it (correctly) has links for
all of the variables mentioned in it.

The recipe for the original report is this:

1. Download library isearch+.el from here:

https://www.emacswiki.org/emacs/download/isearch%2b.el

2. Load that source code.

3. `C-h f isearch-forward'

4. This variable (user option) in the doc was
   not linked, but should have been:
   `isearchp-prompt-for-filter-name'.

But now that option has a link.  (With the above
recipe all have links except those with `[*]',
which the doc tells you are defined in another
library - so no links is correct without that
library loaded.)

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 9445 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>,
 24842 <at> debbugs.gnu.org
Subject: Re: bug#24842: 24.5; `help-make-xrefs': False link-type determinations
Date: Tue, 15 Feb 2022 11:43:02 +0100

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Yup.  So here's the recipe to reproduce the problem:
>
> (defun foo1 ())
> (defvar foo2 ())
>
> (defvar foo nil
>   "
> `foo1'\t- on-demand action function
> `foo2'")
>
> So I'm reopening the bug report.

But looking at this thing again, the DWIM code trying to parse doc
strings and adding links just can't get this case right.

It's, reasonably enough, interpreting "function `foo2'" as a function
(even if it's on two lines), and then seeing that it isn't, so it
doesn't add a link.  I think the answer here "don't do that, then" --
i.e., you have to write this in a different way to help the DWIM logic.

So I'm re-closing this as a "wontfix".

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Stephen Berman <stephen.berman <at> gmx.net>
Cc: "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
 "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#24842: 24.5; `help-make-xrefs': False
 link-type determinations
Date: Tue, 15 Feb 2022 16:58:01 +0000

> > Yup.  So here's the recipe to reproduce the problem:
> >
> > (defun foo1 ())
> > (defvar foo2 ())
> >
> > (defvar foo nil
> >   "
> > `foo1'\t- on-demand action function
> > `foo2'")
> >
> > So I'm reopening the bug report.
> 
> But looking at this thing again, the DWIM code trying to parse doc
> strings and adding links just can't get this case right.
> 
> It's, reasonably enough, interpreting "function `foo2'" as a function
> (even if it's on two lines), and then seeing that it isn't, so it
> doesn't add a link.  I think the answer here "don't do that, then" --
> i.e., you have to write this in a different way to help the DWIM logic.
> 
> So I'm re-closing this as a "wontfix".

That's just saying that you haven't found an
easy solution.  It's not saying that there's
no bug or that it can't be fixed.

I think there's more in this bug thread than
your latest recipe for reproducing what you
think the problem is.  But I won't insist on
that perception.

The priority shouldn't be to close bugs.  It
should be to report bugs, so they can perhaps
be fixed by someone who has the interest and
energy.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 9445 <at> debbugs.gnu.org, larsi <at> gnus.org, stephen.berman <at> gmx.net,
 24842 <at> debbugs.gnu.org
Subject: Re: bug#24842: [External] : Re: bug#24842: 24.5;
 `help-make-xrefs': False link-type determinations
Date: Tue, 15 Feb 2022 21:12:13 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Tue, 15 Feb 2022 16:58:01 +0000
> Cc: "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
>  "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
> 
> The priority shouldn't be to close bugs.  It
> should be to report bugs, so they can perhaps
> be fixed by someone who has the interest and
> energy.

It makes no sense to keep bugs open for years without anyone picking
up the gauntlet.  After so many years it is quite reasonable to assume
that no one is interested enough to work on this.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
 "larsi <at> gnus.org" <larsi <at> gnus.org>,
 "stephen.berman <at> gmx.net" <stephen.berman <at> gmx.net>,
 "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
Subject: RE: bug#24842: [External] : Re: bug#24842: 24.5; `help-make-xrefs':
 False link-type determinations
Date: Tue, 15 Feb 2022 19:22:00 +0000

> > The priority shouldn't be to close bugs.  It
> > should be to report bugs, so they can perhaps
> > be fixed by someone who has the interest and
> > energy.
> 
> It makes no sense to keep bugs open for years without anyone picking
> up the gauntlet.  After so many years it is quite reasonable to assume
> that no one is interested enough to work on this.

And the reason is?  No reason given.

Just what is the cost of leaving confirmed bugs
open?  Just what is the benefit of closing them
(apart perhaps from showing fewer in a report)?

You might have some good reasons.  So far, none
have been presented.

"It makes no sense" and "it is quite reasonable",
themselves make little sense with nothing
presented to back them up.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 9445 <at> debbugs.gnu.org, larsi <at> gnus.org, stephen.berman <at> gmx.net,
 24842 <at> debbugs.gnu.org
Subject: Re: bug#24842: [External] : Re: bug#24842: 24.5; `help-make-xrefs':
 False link-type determinations
Date: Tue, 15 Feb 2022 21:33:35 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "larsi <at> gnus.org" <larsi <at> gnus.org>,
>         "stephen.berman <at> gmx.net"
> 	<stephen.berman <at> gmx.net>,
>         "9445 <at> debbugs.gnu.org" <9445 <at> debbugs.gnu.org>,
>         "24842 <at> debbugs.gnu.org" <24842 <at> debbugs.gnu.org>
> Date: Tue, 15 Feb 2022 19:22:00 +0000
> Accept-Language: en-US
> 
> > > The priority shouldn't be to close bugs.  It
> > > should be to report bugs, so they can perhaps
> > > be fixed by someone who has the interest and
> > > energy.
> > 
> > It makes no sense to keep bugs open for years without anyone picking
> > up the gauntlet.  After so many years it is quite reasonable to assume
> > that no one is interested enough to work on this.
> 
> And the reason is?  No reason given.

I just gave it, above.

> Just what is the cost of leaving confirmed bugs
> open?

It's a cost to the project maintenance to have open bugs that no one
works on.

> Just what is the benefit of closing them
> (apart perhaps from showing fewer in a report)?

The benefit is to have a manageable number of bugs that we really want
to fix.

> "It makes no sense" and "it is quite reasonable",
> themselves make little sense

Perhaps for you.  But this is not your call and not your
responsibility.

Previous Next

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