On 2016-11-26 Sat 03:27 GMT-0800, Eli Zaretskii wrote: >> From: Hong Xu >> 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.