* bug#25033: [PATCH] Add a missing index for `man'.
@ 2016-11-26 9:18 Hong Xu
2016-11-26 9:29 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Hong Xu @ 2016-11-26 9:18 UTC (permalink / raw)
To: 25033
* 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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#25033: [PATCH] Add a missing index for `man'.
2016-11-26 9:18 bug#25033: [PATCH] Add a missing index for `man' Hong Xu
@ 2016-11-26 9:29 ` Eli Zaretskii
2016-11-26 10:06 ` Hong Xu
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2016-11-26 9:29 UTC (permalink / raw)
To: Hong Xu; +Cc: 25033
> From: Hong Xu <hong@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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#25033: [PATCH] Add a missing index for `man'.
2016-11-26 9:29 ` Eli Zaretskii
@ 2016-11-26 10:06 ` Hong Xu
2016-11-26 11:27 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Hong Xu @ 2016-11-26 10:06 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 25033
[-- Attachment #1: Type: text/plain, Size: 1400 bytes --]
On 2016-11-26 Sat 01:29 GMT-0800, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Hong Xu <hong@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.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#25033: [PATCH] Add a missing index for `man'.
2016-11-26 10:06 ` Hong Xu
@ 2016-11-26 11:27 ` Eli Zaretskii
2016-11-26 19:17 ` Hong Xu
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2016-11-26 11:27 UTC (permalink / raw)
To: Hong Xu; +Cc: 25033
> 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.
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#25033: [PATCH] Add a missing index for `man'.
2016-11-26 11:27 ` Eli Zaretskii
@ 2016-11-26 19:17 ` Hong Xu
2016-12-02 9:15 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Hong Xu @ 2016-11-26 19:17 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 25033
[-- 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 --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#25033: [PATCH] Add a missing index for `man'.
2016-11-26 19:17 ` Hong Xu
@ 2016-12-02 9:15 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2016-12-02 9:15 UTC (permalink / raw)
To: Hong Xu; +Cc: 25033-done
> From: Hong Xu <hong@topbug.net>
> Cc: 25033@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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-12-02 9:15 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-11-26 9:18 bug#25033: [PATCH] Add a missing index for `man' Hong Xu
2016-11-26 9:29 ` Eli Zaretskii
2016-11-26 10:06 ` Hong Xu
2016-11-26 11:27 ` Eli Zaretskii
2016-11-26 19:17 ` Hong Xu
2016-12-02 9:15 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).