bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Drew Adams]

For `i home TAB' you see these candidates:
HOME
home directory shorthand

In my setup I see also these two, but for some reason I don't see them
with `emacs -Q':
HOME directory on MS-Windows
HOME directory under MS-DOS

In any case, those with the uppercase HOME should presumably not point
to node `Moving Point' (and, in particular, to the key `<home>'.  That
is wrong.  Presumably, `HOME' should take you to some information about
environment variable `HOME' or at least about the home directory.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Eli Zaretskii]

> Date: Fri, 13 Mar 2015 19:23:31 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> For `i home TAB' you see these candidates:
> HOME
> home directory shorthand
> 
> In my setup I see also these two, but for some reason I don't see them
> with `emacs -Q':
> HOME directory on MS-Windows
> HOME directory under MS-DOS

I see all 4 of them in "emacs -Q".  Not sure why you don't; perhaps
because your build is very old (but I doubt that).  Do you have
INFOPATH set in the environment, perhaps?

> In any case, those with the uppercase HOME should presumably not point
> to node `Moving Point' (and, in particular, to the key `<home>'.  That
> is wrong.  Presumably, `HOME' should take you to some information about
> environment variable `HOME' or at least about the home directory.

I disagree.  In general, index searches are deliberately
case-insensitive.  In this particular case, you might assume that
everyone knows the key is called <home>, but a seasonal reader of the
manual does not necessarily know that; he could, for example, take
inspiration from SPC, RET, TAB, etc.  We shouldn't fail those users,
IMO.

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Drew Adams]

> > For `i home TAB' you see these candidates:
> > HOME
> > home directory shorthand
> >
> > In my setup I see also these two, but for some reason I don't see them
> > with `emacs -Q':
> > HOME directory on MS-Windows
> > HOME directory under MS-DOS
> 
> I see all 4 of them in "emacs -Q".  Not sure why you don't; perhaps
> because your build is very old (but I doubt that).

No, I see only 2, even in this recent build (see end of this message).

> Do you have INFOPATH set in the environment, perhaps?

Nope.

> > In any case, those with the uppercase HOME should presumably not point
> > to node `Moving Point' (and, in particular, to the key `<home>'.  That
> > is wrong.  Presumably, `HOME' should take you to some information about
> > environment variable `HOME' or at least about the home directory.
> 
> I disagree.  In general, index searches are deliberately
> case-insensitive.  In this particular case, you might assume that
> everyone knows the key is called <home>, but a seasonal reader of the
> manual does not necessarily know that; he could, for example, take
> inspiration from SPC, RET, TAB, etc.  We shouldn't fail those users,
> IMO.

I agree about (a) case-insensitive "in general" and (b) users might not
know about `<home>' vs `home' vs `HOME'.

But why is `HOME' capitalized as a candidate if it points to info about
the key?  That can only be misleading, I think.  I don't think Emacs
ever refers to the key that way (unlike, say, `TAB').

If we have a single `home' or `HOME' entry then we invite such problems.
(If we _must_ have a single such entry, I would expect it to point to
the env var.)

We should have similar treatment for the key and the env var, IMO.
E.g., if we have `home directory shorthand' then the key entry should
be something like `home keyboard key'.

And we don't seem to have any entry currently for the env var (?).
Shouldn't a user be able to find some info about it?
`HOME environment variable', for example.

Anyway, I don't have a brilliant solution.  But I noticed a problem.
Maybe you can make some improvement based on this feedback.  If not,
feel free to close the bug.

More recent build where I still see only two entries for `home TAB':

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-02-27 on LEG570
Repository revision: b2a590d4e3dc692a97c1b53e015b945d84b4b4c7
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1252

Major mode: Info

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  line-number-mode: t

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Making completion list...
Quit [2 times]

Load-path shadows:
None found.

Features:
(shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev
gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util
help-fns mail-prsvr mail-utils info easymenu dired time-date tooltip
eldoc electric uniquify ediff-hook vc-hooks lisp-float-type mwheel
dos-w32 ls-lisp disp-table w32-win w32-vars tool-bar dnd fontset image
regexp-opt fringe tabulated-list newcomment elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
minibuffer cl-preloaded nadvice loaddefs button faces cus-face macroexp
files text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote make-network-process
w32notify w32 multi-tty emacs)

Memory information:
((conses 8 187997 47058)
 (symbols 32 18506 1)
 (miscs 32 52 159)
 (strings 16 17991 4941)
 (string-bytes 1 413382)
 (vectors 8 9953)
 (vector-slots 4 396848 6048)
 (floats 8 68 277)
 (intervals 28 35386 3975)
 (buffers 516 15))

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Eli Zaretskii]

> Date: Sat, 14 Mar 2015 07:46:49 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20105@debbugs.gnu.org
> 
> > > For `i home TAB' you see these candidates:
> > > HOME
> > > home directory shorthand
> > >
> > > In my setup I see also these two, but for some reason I don't see them
> > > with `emacs -Q':
> > > HOME directory on MS-Windows
> > > HOME directory under MS-DOS
> > 
> > I see all 4 of them in "emacs -Q".  Not sure why you don't; perhaps
> > because your build is very old (but I doubt that).
> 
> No, I see only 2, even in this recent build (see end of this message).
> 
> > Do you have INFOPATH set in the environment, perhaps?
> 
> Nope.

Strange.  I have no idea why you see only 2 candidates.  I see all 4
in both the master and emacs-24 branch.

> I agree about (a) case-insensitive "in general" and (b) users might not
> know about `<home>' vs `home' vs `HOME'.
> 
> But why is `HOME' capitalized as a candidate if it points to info about
> the key?

Don't know.  Looks like some feature of completion.

> And we don't seem to have any entry currently for the env var (?).
> Shouldn't a user be able to find some info about it?
> `HOME environment variable', for example.

That's one of the 2 "HOME" entries.  They belong to different indices,
so they are identical (and collapsed by completion into a single
completion candidate, I presume).

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Drew Adams]

> > > > For `i home TAB' you see these candidates:
> > > > HOME
> > > > home directory shorthand
> > > >
> > > > In my setup I see also these two, but for some reason I don't see them
> > > > with `emacs -Q':
> > > > HOME directory on MS-Windows
> > > > HOME directory under MS-DOS
> > >
> > > I see all 4 of them in "emacs -Q".  Not sure why you don't; perhaps
> > > because your build is very old (but I doubt that).
> > No, I see only 2, even in this recent build (see end of this message).
> > > Do you have INFOPATH set in the environment, perhaps?
> > Nope.
> 
> Strange.  I have no idea why you see only 2 candidates.  I see all 4
> in both the master and emacs-24 branch.

I hear you.  I don't know why.  I'm on Windows 7 64-bit.  Other than
that, I don't know what else I can add here.

But see below.  I do have those two missing candidates as explicit
entries in the manual indexes.  It is completion that, for some reason,
fails to pick them up.  I don't see how you get different behavior, if
we're both using `emacs -Q'.

> > I agree about (a) case-insensitive "in general" and (b) users might not
> > know about `<home>' vs `home' vs `HOME'.
> >
> > But why is `HOME' capitalized as a candidate if it points to info about
> > the key?
> 
> Don't know.  Looks like some feature of completion.

Really?  My guess is instead that it comes from this explicit index
entry (which I see in Emacs 24 but not 23): (I removed some whitespace.)

* HOME:             Moving Point.        (line  57)

That's from the Key Index.  However, note that there are also these
two entries in the Variable Index, which seem not to be used when
I do `i home TAB':

* HOME:             General Variables.   (line  59)
* HOSTNAME:         General Variables.   (line  70)

(Got this from an Emacs 24.4 build.  I assume things are similar
for more recent builds.)

> > And we don't seem to have any entry currently for the env var (?).
> > Shouldn't a user be able to find some info about it?
> > `HOME environment variable', for example.
> 
> That's one of the 2 "HOME" entries.  They belong to different indices,
> so they are identical (and collapsed by completion into a single
> completion candidate, I presume).

Sorry, I don't know what you mean here.  I'm guessing that you're
saying something (?) about these entries (again, from Emacs 24.4):

* HOME directory on MS-Windows:      Windows HOME.        (line   6)
* home directory shorthand:          Minibuffer File.     (line  38)
* HOME directory under MS-DOS:       MS-DOS File Names.   (line  35)

From what I see, the only explicit index entries that include `HOME'
(capitalized) refer to the home directory, not to the <home> key.

So it seems to me that Emacs is not correctly dealing with its own
index entries.  It also seems that the Key Index somehow overrides
the Variable Index (instead of being augmented by it), for completion.

HTH.

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Eli Zaretskii]

> Date: Sat, 14 Mar 2015 08:59:29 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20105@debbugs.gnu.org
> 
> > Strange.  I have no idea why you see only 2 candidates.  I see all 4
> > in both the master and emacs-24 branch.
> 
> I hear you.  I don't know why.  I'm on Windows 7 64-bit.  Other than
> that, I don't know what else I can add here.
> 
> But see below.  I do have those two missing candidates as explicit
> entries in the manual indexes.  It is completion that, for some reason,
> fails to pick them up.  I don't see how you get different behavior, if
> we're both using `emacs -Q'.

Yes, "emacs -Q" here.  And it's not a surprise you have those missing
candidates in the index, that's how I can see them ;-)

Are you sure you did 'i home TAB' in the latest manual, though?

> > > But why is `HOME' capitalized as a candidate if it points to info about
> > > the key?
> > 
> > Don't know.  Looks like some feature of completion.
> 
> Really?  My guess is instead that it comes from this explicit index
> entry (which I see in Emacs 24 but not 23): (I removed some whitespace.)
> 
> * HOME:             Moving Point.        (line  57)

By "feature" I meant that it replaces "home" which I typed by "HOME",
for whatever reasons.  The _only_ reason that I could accept as
legitimate is if _all_ completion candidates started with an
upper-case "HOME".  But that's not what we have here.  So it looks
like some attempt at being smart is misfiring.

> That's from the Key Index.  However, note that there are also these
> two entries in the Variable Index, which seem not to be used when
> I do `i home TAB':
> 
> * HOME:             General Variables.   (line  59)
> * HOSTNAME:         General Variables.   (line  70)

HOME _is_ used, except that completion removes duplicates (I guess).
As for HOSTNAME -- why should it be used?  I don't see it used here.

> >From what I see, the only explicit index entries that include `HOME'
> (capitalized) refer to the home directory, not to the <home> key.

No, the entry that revers to "Moving Point" is also capitalized.

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Drew Adams]

> Yes, "emacs -Q" here.  And it's not a surprise you have those missing
> candidates in the index, that's how I can see them ;-)
> 
> Are you sure you did 'i home TAB' in the latest manual, though?

Yes, exactly that, in this build:

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-02-27 on LEG570
Repository revision: b2a590d4e3dc692a97c1b53e015b945d84b4b4c7
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

> > > > But why is `HOME' capitalized as a candidate if it points to info
> > > > about the key?
> > >
> > > Don't know.  Looks like some feature of completion.
> >
> > Really?  My guess is instead that it comes from this explicit index
> > entry (which I see in Emacs 24 but not 23): (I removed some whitespace.)
> >
> > * HOME:             Moving Point.        (line  57)
> 
> By "feature" I meant that it replaces "home" which I typed by "HOME",
> for whatever reasons.  The _only_ reason that I could accept as
> legitimate is if _all_ completion candidates started with an
> upper-case "HOME".  But that's not what we have here.  So it looks
> like some attempt at being smart is misfiring.

Yes, I guess so.

But I'm guessing that what happens might have to do with searching the
indexes in order, where Key Index comes first.  And in that index,
`HOME' is the only entry matching input `home'.  It is also the only
matching entry in the Variable Index.

> > That's from the Key Index.  However, note that there are also these
> > two entries in the Variable Index, which seem not to be used when
> > I do `i home TAB':
> >
> > * HOME:             General Variables.   (line  59)
> > * HOSTNAME:         General Variables.   (line  70)
> 
> HOME _is_ used, except that completion removes duplicates (I guess).

I guess so too.  That is a mistake.  The calling function should
decide whether completion should remove duplicates (IMHO).  And in
this case, it should not (IMHO).

> As for HOSTNAME -- why should it be used?  I don't see it used here.

My bad for mentioning HOSTNAME.  Might have been a copy&paste error.
Or it might have reflected a senior moment.

> > From what I see, the only explicit index entries that include `HOME'
> > (capitalized) refer to the home directory, not to the <home> key.
> 
> No, the entry that revers to "Moving Point" is also capitalized.

Right.  Do you agree that that is wrong?  I doubt that that is the
only problem here.  But it would be a start, to fix that entry.
It should be changed to something like `home keyboard key' or `home
key (keyboard)', I think.

(We might also want to add an entry for `<home> keyboard key'.)

Also, I question whether the quote marks should be included in these
two index entries:

* 'HOME' directory on MS-Windows:    Windows HOME.        (line   6)
* 'HOME' directory under MS-DOS:     MS-DOS File Names.   (line  35)

Et voila: That's probably why typing `host' does not match either of
these entries.  And it's perhaps why it does work for you: the curly
quotes are perhaps not present for you, in the indexes.

---

Interestingly, copying and pasting those into this mail shows them
as curly quotes, but in Info they appear to be straight.  They are
LEFT SINGLE QUOTATION MARK etc.  I guess it is the default Info font
that makes them appear straight.

But I thought that we had arranged to use the older makeinfo or
whatever, and that Emacs was arranging to keep simple backtick and
apostrophe in the produced Info buffers.  No?  I see now that Isearch
for ` or ' fails miserably in Info, wrt finding such quoted names.

This makes it hard for users who want to use keyboard keys ` and '
for searching.  That's a clear regression in usefulness, IMHO.

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Eli Zaretskii]

> Date: Sat, 14 Mar 2015 09:44:09 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20105@debbugs.gnu.org
> 
> (We might also want to add an entry for `<home> keyboard key'.)

I changed the existing entry to say "HOME key".  The other one now
mentions it's an environment variable.

> Also, I question whether the quote marks should be included in these
> two index entries:
> 
> * 'HOME' directory on MS-Windows:    Windows HOME.        (line   6)
> * 'HOME' directory under MS-DOS:     MS-DOS File Names.   (line  35)
> 
> Et voila: That's probably why typing `host' does not match either of
> these entries.  And it's perhaps why it does work for you: the curly
> quotes are perhaps not present for you, in the indexes.

Yes, I still use the old makeinfo to produce the manual, and this
subtle difference seems to be one more incompatibility of the new
versions.  I fixed that.

> Interestingly, copying and pasting those into this mail shows them
> as curly quotes, but in Info they appear to be straight.  They are
> LEFT SINGLE QUOTATION MARK etc.  I guess it is the default Info font
> that makes them appear straight.
> 
> But I thought that we had arranged to use the older makeinfo or
> whatever, and that Emacs was arranging to keep simple backtick and
> apostrophe in the produced Info buffers.  No?  I see now that Isearch
> for ` or ' fails miserably in Info, wrt finding such quoted names.
> 
> This makes it hard for users who want to use keyboard keys ` and '
> for searching.  That's a clear regression in usefulness, IMHO.

I guess this is a question for Dani, who produced the files.

I think the bug can now be closed.

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Drew Adams]

> > HOME _is_ used, except that completion removes duplicates (I guess).
> 
> I guess so too.  That is a mistake.  The calling function should
> decide whether completion should remove duplicates (IMHO).  And in
> this case, it should not (IMHO).

That is done here, in `Info-complete-menu-item':

(setq completions (delete-dups completions))

Also, debugging a bit shows this, which returns "HOME".

Debugger entered--entering a function:
* try-completion("home" ("home directory shorthand" "HOME") nil)
* complete-with-action(nil ("home directory shorthand" "HOME") "home" nil)

And then (after a bit), it does this, which also returns "HOME":

Debugger entered--entering a function:
* try-completion("HOME" ("home directory shorthand" "HOME") nil)
* complete-with-action(nil ("home directory shorthand" "HOME") "HOME" nil)

Which leads to:

Debugger entered--returning value: t
  completion--done("HOME" exact "Complete, but not unique")

And a second `TAB' shows the candidates in *Completions*:

Possible completions are:
HOME
home directory shorthand

bug#20105: 25.0.50; Emacs manual, `i HOME RET' sends you to `Moving Point', which is wrong

[Drew Adams]

> > (We might also want to add an entry for `<home> keyboard key'.)
> 
> I changed the existing entry to say "HOME key".  The other one now
> mentions it's an environment variable.

Thx.

> > Et voila: That's probably why typing `host' does not match either of
> > these entries.  And it's perhaps why it does work for you: the curly
> > quotes are perhaps not present for you, in the indexes.
> 
> Yes, I still use the old makeinfo to produce the manual, and this
> subtle difference seems to be one more incompatibility of the new
> versions.  I fixed that.

Thx.

> I think the bug can now be closed.

Done.  Thx.