[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#25033: [PATCH] Add a missing index for `man'.
From: |
Hong Xu |
Subject: |
bug#25033: [PATCH] Add a missing index for `man'. |
Date: |
Sat, 26 Nov 2016 11:17:35 -0800 |
User-agent: |
mu4e 0.9.17; emacs 25.1.50.14 |
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.
signature.asc
Description: PGP signature