GNU bug report logs - #25033
[PATCH] Add a missing index for `man'.

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 25033 in the body.
You can then email your comments to 25033 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: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add a missing index for `man'.
Date: Sat, 26 Nov 2016 01:18:26 -0800

	* programs.texi (Man Page): Add the index for `man'.
---
 doc/emacs/programs.texi | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index e409affd67d1..fc9f8e88b47a 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1193,6 +1193,7 @@ Man Page
 with Info (@pxref{Misc Help}).  This process is not finished, so it is
 still useful to read manual pages.
 
+@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
-- 
2.1.4

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 25033 <at> debbugs.gnu.org
Subject: Re: bug#25033: [PATCH] Add a missing index for `man'.
Date: Sat, 26 Nov 2016 11:29:44 +0200

> From: Hong Xu <hong <at> topbug.net>
> Date: Sat, 26 Nov 2016 01:18:26 -0800
> 
> 	* programs.texi (Man Page): Add the index for `man'.
> ---
>  doc/emacs/programs.texi | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
> index e409affd67d1..fc9f8e88b47a 100644
> --- a/doc/emacs/programs.texi
> +++ b/doc/emacs/programs.texi
> @@ -1193,6 +1193,7 @@ Man Page
>  with Info (@pxref{Misc Help}).  This process is not finished, so it is
>  still useful to read manual pages.
>  
> +@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?

Thanks.

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

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 25033 <at> debbugs.gnu.org
Subject: Re: bug#25033: [PATCH] Add a missing index for `man'.
Date: Sat, 26 Nov 2016 02:06:02 -0800

[Message part 1 (text/plain, inline)]

On 2016-11-26 Sat 01:29 GMT-0800, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Hong Xu <hong <at> topbug.net>
>> Date: Sat, 26 Nov 2016 01:18:26 -0800
>>
>> 	* programs.texi (Man Page): Add the index for `man'.
>> ---
>>  doc/emacs/programs.texi | 1 +
>>  1 file changed, 1 insertion(+)
>>
>> diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
>> index e409affd67d1..fc9f8e88b47a 100644
>> --- a/doc/emacs/programs.texi
>> +++ b/doc/emacs/programs.texi
>> @@ -1193,6 +1193,7 @@ Man Page
>>  with Info (@pxref{Misc Help}).  This process is not finished, so it is
>>  still useful to read manual pages.
>>
>> +@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.

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.

[signature.asc (application/pgp-signature, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 25033 <at> debbugs.gnu.org
Subject: Re: bug#25033: [PATCH] Add a missing index for `man'.
Date: Sat, 26 Nov 2016 13:27:09 +0200

> From: Hong Xu <hong <at> topbug.net>
> Cc: 25033 <at> 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.

> 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.

Thanks.

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

From: Hong Xu <hong <at> topbug.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 25033 <at> debbugs.gnu.org
Subject: Re: bug#25033: [PATCH] Add a missing index for `man'.
Date: Sat, 26 Nov 2016 11:17:35 -0800

[Message part 1 (text/plain, inline)]

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

>> From: Hong Xu <hong <at> topbug.net>
>> Cc: 25033 <at> 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 (application/pgp-signature, inline)]

Message #22 received at 25033-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 25033-done <at> debbugs.gnu.org
Subject: Re: bug#25033: [PATCH] Add a missing index for `man'.
Date: Fri, 02 Dec 2016 11:15:00 +0200

> From: Hong Xu <hong <at> topbug.net>
> Cc: 25033 <at> debbugs.gnu.org
> Date: Sat, 26 Nov 2016 11:17:35 -0800
> 
> 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.

Done, thanks for the suggestion.

Previous Next

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