bug#25033: [PATCH] Add a missing index for `man'.

[Hong Xu <hong@topbug.net>]

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


On 2016-11-26 Sat 03:27 GMT-0800, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Hong Xu <hong@topbug.net>
>> Cc: 25033@debbugs.gnu.org
>> Date: Sat, 26 Nov 2016 02:06:02 -0800
>>
>> >> +@findex man
>> >>  @findex manual-entry
>> >>    You can read the man page for an operating system command, library
>> >>  function, or system call, with the @kbd{M-x man} command.  This
>> >
>> > If I type "i man RET" in the current Emacs manual, I land in that
>> > node, and "i man TAB" produces a list of completions one of which is
>> > "man pages", which leads to the same node.  So why did you see the
>> > need for adding this index entry?
>>
>> The missing index actually confused me when I searched the manual for
>> it, as it was hidden in my completion list.
>
> Please describe in more detail how it happened that it was hidden,
> perhaps there's something I'm missing.
>

I use ivy-mode for completion. I was expecting there was an exact
matching of "man", but there wasn't. A lot of other entries with higher
scores were on the first page of the completion list.

>> The main reason is though for the completeness of the documentation --
>> "man" should be an indexed function name just like "manual-entry". I
>> don't see how it could be harmful to add this index, although the
>> benefit may also not be significant.
>
> The harm is in having two or more index entries that begin with the
> same text and point to the same page.  That's not useful, and its only
> effect is bloating the index, including in the printed version of the
> manual (which increases the page count).  So we try to avoid that.

These are two different types of indices: one is a function, the other
is a concept -- they locate in different indices. If a user wants to
look for the man function, it can't be found in the function index.

How about this: replace all "manual-entry" with "man" in the section,
and remove the "manual-entry" index as well. In this way, the total
number of indices won't increase. It also fixes the inconsistency --
both "M-x manual-entry" and "M-x man" are used without pointing out they
are the same thing.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]