GNU bug report logs - #3717
M-x man completion

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 3717 in the body.
You can then email your comments to 3717 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: jidanni <at> jidanni.org
To: bug-gnu-emacs <at> gnu.org
Subject: M-x man completion
Date: Tue, 30 Jun 2009 04:48:10 +0800

severity: wishlist

I was thinking when M-x man prompts
  Manual entry (default Neurdsburg):
wouldn't it be neat if there was completion, just like for
M-! shell-command...

Message #10 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: jidanni <at> jidanni.org
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Tue, 30 Jun 2009 00:02:33 +0200

>>>>> "jidanni" == jidanni  <jidanni <at> jidanni.org> writes:

> severity: wishlist
> I was thinking when M-x man prompts
>   Manual entry (default Neurdsburg):
> wouldn't it be neat if there was completion, just like for
> M-! shell-command...

I use the patch below.  It's very lightly tested.


        Stefan


=== modified file 'lisp/man.el'
--- lisp/man.el	2009-03-07 20:30:47 +0000
+++ lisp/man.el	2009-03-14 03:18:28 +0000
@@ -749,6 +749,22 @@
 ;;;###autoload
 (defalias 'manual-entry 'man)
 
+(defun Man-completion-table (string pred action)
+  (let ((table '()))
+    (with-temp-buffer
+      ;; Actually for my `man' the arg is a regexp.  Don't know how
+      ;; standard that is.  Also, it's not clear what kind of
+      ;; regexp are accepted: under GNU/Linux it seems it's ERE-style,
+      ;; whereas under MacOSX it seems to be BRE-style and
+      ;; doesn't accept backslashes at all.  Let's not bother to
+      ;; quote anything.
+      (call-process "man" nil '(t nil) nil "-k" (concat "^" string))
+      (goto-char (point-min))
+      (while (re-search-forward "^[^ \t\n]+" nil t)
+        (push (match-string 0) table)))
+    ;; The table may contain false positives since the match is made
+    ;; by "man -k" not just on the manpage's name.
+    (complete-with-action action table string pred)))
 
 ;;;###autoload
 (defun man (man-args)
@@ -765,12 +781,13 @@
 `Man-switches' variable, which see."
   (interactive
    (list (let* ((default-entry (Man-default-man-entry))
-		(input (read-string
+		(input (completing-read
 			(format "Manual entry%s"
 				(if (string= default-entry "")
 				    ": "
 				  (format " (default %s): " default-entry)))
-			nil 'Man-topic-history default-entry)))
+                        'Man-completion-table
+			nil nil nil 'Man-topic-history default-entry)))
 	   (if (string= input "")
 	       (error "No man args given")
 	     input))))

Message #15 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Sven Joachim <svenjoac <at> gmx.de>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 3717 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Tue, 30 Jun 2009 09:50:05 +0200

On 2009-06-30 00:02 +0200, Stefan Monnier wrote:

>>>>>> "jidanni" == jidanni  <jidanni <at> jidanni.org> writes:
>
>> severity: wishlist
>> I was thinking when M-x man prompts
>>   Manual entry (default Neurdsburg):
>> wouldn't it be neat if there was completion, just like for
>> M-! shell-command...
>
> I use the patch below.  It's very lightly tested.

Hey, cool!  Works great for me.

Sven

Message #20 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: jidanni <at> jidanni.org
To: svenjoac <at> gmx.de
Cc: monnier <at> iro.umontreal.ca, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 01 Jul 2009 03:52:19 +0800

>> I use the patch below.  It's very lightly tested.
SJ> Hey, cool!  Works great for me.
I hope it gets included into emacs then.

Message #25 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: 3717 <at> debbugs.gnu.org
Cc: jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 01 Jul 2009 08:38:07 +1000

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> +(defun Man-completion-table (string pred action)

As a bit of shameless self-promotion, I use my man-completion.el
... http://user42.tuxfamily.org/man-completion/index.html

Among its feeping creatures it tries to cope with pages the same name in
different sections, long names truncated to the tty width, a cache
because man -k takes a couple of seconds for me, and filenames for M-x
man "-l foo".

Message #30 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: monnier <at> iro.umontreal.ca
Cc: jidanni <at> jidanni.org, user42 <at> zip.com.au, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Tue, 24 Nov 2009 19:11:32 +0200

>>> I use the patch below.  It's very lightly tested.
> SJ> Hey, cool!  Works great for me.
> I hope it gets included into emacs then.

Stefan, could you please install your patch that implements
completions for `man'.  This is very useful.

Maybe later Kevin Ryde will add more code to man.el from his
man-completion.el.  Some useful things in man-completion.el are
the cache for `man -k', handling same names in different sections.

Also part of man-completion.el deals with man-completion-at-point
that returns a man page name as a string found at point.
I think this part should be properly integrated into the
"thing-at-point" framework.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #37 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Juri Linkov <juri <at> jurta.org>
Cc: jidanni <at> jidanni.org, user42 <at> zip.com.au, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Tue, 24 Nov 2009 15:01:07 -0500

> Stefan, could you please install your patch that implements
> completions for `man'.  This is very useful.

Yes, done, thank you,


        Stefan

Message #42 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: monnier <at> iro.umontreal.ca, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 09:58:09 +1100

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

Juri Linkov <juri <at> jurta.org> writes:
>
> man-completion.el are the cache for `man -k'

It's pretty vital for me, since man -k is about 1 to 2 seconds per run,
which is too slow if you hit tab a few times (twice each to see the
completion list).

> handling same names in different sections.

It's been through a few goes at making it friendly for both page names
and file names and stuff. :-)

> Also part of man-completion.el deals with man-completion-at-point
> that returns a man page name as a string found at point.

That's another been though loosening and tightening.  I quite like what
I got to for line-break hyphenations.  I looked last week at
Man-hyphenated-reference-regexp and wondered if it was the same thing,
but the docstring of Man-possibly-hyphenated-word about returning the
previous line's word like "tcgetp-" suggested not.  If it is the same
then a U+2010 hyphen could be worked in there -- it comes out of recent
groff "-Tutf8".


If nothing else then give the following bit a go.  man-db truncates page
names longer than about half the screen width.  (Long names arise from
perl classes.)

2009-11-24  Kevin Ryde  <user42 <at> zip.com.au>

	* man.el (Man-completion-table): default-directory "/" in case
	doesn't otherwise exist.  process-environment COLUMNS=999 so as
	not to truncate long names.  process-connection-type pipe to avoid
	any chance of hitting the pseudo-tty TIOCGWINSZ.

[man.el.no-truncate.diff (text/x-diff, inline)]

--- man.el.~1.187.~	2009-11-25 09:08:03.000000000 +1100
+++ man.el	2009-11-25 09:26:02.000000000 +1100
@@ -754,13 +754,17 @@
    ((memq action '(t nil))
     (let ((table '()))
       (with-temp-buffer
+	(setq default-directory "/") ;; in case inherited doesn't exist
         ;; Actually for my `man' the arg is a regexp.  Don't know how
         ;; standard that is.  Also, it's not clear what kind of
         ;; regexp are accepted: under GNU/Linux it seems it's ERE-style,
         ;; whereas under MacOSX it seems to be BRE-style and
         ;; doesn't accept backslashes at all.  Let's not bother to
         ;; quote anything.
-        (call-process "man" nil '(t nil) nil "-k" (concat "^" string))
+ 	(let ((process-connection-type nil) ;; pipe
+	      (process-environment (copy-sequence process-environment)))
+	  (setenv "COLUMNS" "999") ;; don't truncate long names
+	  (call-process "man" nil '(t nil) nil "-k" (concat "^" string)))
         (goto-char (point-min))
         (while (re-search-forward "^[^ \t\n]+" nil t)
           (push (match-string 0) table)))

Message #47 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: monnier <at> iro.umontreal.ca, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 10:45:47 +1100

Oh, and I've also found case-insensitive completion best for page names,
when trying to type bizarre-case things like the x11 funcs.

I was going to make the sensitivity configurable, or switchable with C-t
like isearch, but never thought of a good way, so it's hard coded
insensitive -- with the justification that man itself is
case-insensitive on the command line. :-)

Message #52 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Ryde <user42 <at> zip.com.au>, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 06:21:42 +0200

> From: Kevin Ryde <user42 <at> zip.com.au>
> Date: Wed, 25 Nov 2009 09:58:09 +1100
> Cc: 3717 <at> emacsbugs.donarmstrong.com, jidanni <at> jidanni.org
> 
> -        (call-process "man" nil '(t nil) nil "-k" (concat "^" string))
> + 	(let ((process-connection-type nil) ;; pipe
> +	      (process-environment (copy-sequence process-environment)))
> +	  (setenv "COLUMNS" "999") ;; don't truncate long names
> +	  (call-process "man" nil '(t nil) nil "-k" (concat "^" string)))

This needs to deal with versions of `man' that don't support the -k
switch.

Message #57 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3717 <at> debbugs.gnu.org, Kevin Ryde <user42 <at> zip.com.au>
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 09:47:22 -0500

>> -        (call-process "man" nil '(t nil) nil "-k" (concat "^" string))
>> + 	(let ((process-connection-type nil) ;; pipe
>> +	      (process-environment (copy-sequence process-environment)))
>> +	  (setenv "COLUMNS" "999") ;; don't truncate long names
>> +	  (call-process "man" nil '(t nil) nil "-k" (concat "^" string)))

> This needs to deal with versions of `man' that don't support the -k
> switch.

It pretty much does, I believe.  At worst (i.e. in case that "man" sends
its error message to stdout rather than stderr) it may suggest a couple
of words of completion which are taken from the error message.
I.e. I wouldn't worry about it for now,


        Stefan

Message #62 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: jidanni <at> jidanni.org, user42 <at> zip.com.au, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 19:29:42 +0200

>> Stefan, could you please install your patch that implements
>> completions for `man'.  This is very useful.
>
> Yes, done, thank you,

Thanks.  Currently it doesn't add a section name to the end of
completion strings.  So it is not clear to which section does
a manual belong and also it's impossible to select an ambiguous
name that belongs to different sections.

For instance, typing `M-x man RET lib TAB' displays only one
completion whereas there are two manuals in different sections:
`lib (3erl)' for Erlang and `lib (3perl)' for Perl.

Replacing a regexp in your change with "^[^ \t\n]+\\([ \t\n]+[^-)]+)\\)?"
that adds section names to completion strings fixes this problem,
so the *Completions* buffer displays in the aforementioned case:

  Possible completions are:
  lib (3erl)
  lib (3perl)

WDYT?

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #67 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Juri Linkov <juri <at> jurta.org>
Cc: jidanni <at> jidanni.org, user42 <at> zip.com.au, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 14:30:16 -0500

> Replacing a regexp in your change with "^[^ \t\n]+\\([ \t\n]+[^-)]+)\\)?"
> that adds section names to completion strings fixes this problem,
> so the *Completions* buffer displays in the aforementioned case:

Fine by me, but please try and make the regexp a bit tighter.  E.g. the
above one doesn't have an explicit "(" and allows several spaces between
the page name and the section, whereas AFAICT there's never more than
one space there.


        Stefan

Message #72 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: jidanni <at> jidanni.org, user42 <at> zip.com.au, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 23:17:20 +0200

>> Replacing a regexp in your change with "^[^ \t\n]+\\([ \t\n]+[^-)]+)\\)?"
>> that adds section names to completion strings fixes this problem,
>> so the *Completions* buffer displays in the aforementioned case:
>
> Fine by me, but please try and make the regexp a bit tighter.  E.g. the
> above one doesn't have an explicit "(" and allows several spaces between
> the page name and the section, whereas AFAICT there's never more than
> one space there.

Done.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #77 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 09:53:28 +1100

Eli Zaretskii <eliz <at> gnu.org> writes:
>
> This needs to deal with versions of `man' that don't support the -k
> switch.

Is the "apropos" program better?  It's been about 15 years since I had
to use anything other than man-db :-).

Message #82 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: Stefan Monnier <monnier <at> IRO.UMontreal.CA>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 10:04:16 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
>   Possible completions are:
>   lib (3erl)
>   lib (3perl)

If you complete from "li" it gives "lib (", which will make man error
out.  I insert a bare "lib" for such cases so that completion stops
without the "(" for whatever is man's default page for "lib".  You may
have seen the "chmod" example in my code.

I also put in stuff like "3erl lib", since you can enter it like that to
man, and it can be easier to give the section first then complete among
pages in the section, as opposed to a section suffix.

That latter probably doesn't cooperate with Stefan's prefix-based cache
thing as it stands.  But I found it better to cache all page names once,
because a "-k" run is pretty much as slow asking for a few matches as
many.

I did say there was lots of things I've already been through for
friendliness and features!  :-)

Message #87 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: Juri Linkov <juri <at> jurta.org>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 10:11:19 +1100

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:
>
> Yes, done

In the completions table I insinuate "-k " and "-l " so it's possible to
type those things without needing C-q Space.  Is there a better way to
defang `minibuffer-complete-word', ie. make it just insert a space in
certain circumstances?

(The way M-x man accepts "-k pattern" seems to be a well-kept secret --
or is it obvious to everyone except me!)

Message #92 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 10:18:32 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> Done.

Incidentally, I'm just today tinkering in my stuff with keeping the
description part of that -k output in the completions table too, to make
it available for completing-help.el.  I think icicles.el has a similar
help/info thing for completions, but I haven't looked into that one yet.

Message #97 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: Juri Linkov <juri <at> jurta.org>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 25 Nov 2009 22:03:27 -0500

> (The way M-x man accepts "-k pattern" seems to be a well-kept secret --
> or is it obvious to everyone except me!)

It's not a feature, AFAIK, more like an accident.  M-x man xterm|tail RET
also works, but again, it's just an accident.
Hopefully at some point we'll get rid of the sed script and then we may
run "man" without going through a shell, in which case those accidents
won't work any more.


        Stefan

Message #102 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 06:20:25 +0200

> From: Kevin Ryde <user42 <at> zip.com.au>
> Cc: 3717 <at> emacsbugs.donarmstrong.com
> Date: Thu, 26 Nov 2009 09:53:28 +1100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> >
> > This needs to deal with versions of `man' that don't support the -k
> > switch.
> 
> Is the "apropos" program better?

It could be, but it also isn't universally available, especially if
you are on a non-Posix platform.

Ideally, `man' should test what's available, like `grep' does, and if
nothing is, simply not provide this feature.

Message #107 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 11:28:37 +0200

> Incidentally, I'm just today tinkering in my stuff with keeping the
> description part of that -k output in the completions table too, to make
> it available for completing-help.el.  I think icicles.el has a similar
> help/info thing for completions, but I haven't looked into that one yet.

You could try to use annotations in the *Completions* buffer.  I can't say
in advance how convenient it would be to use them for man completions.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #112 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: Stefan Monnier <monnier <at> IRO.UMontreal.CA>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 11:28:27 +0200

>>   Possible completions are:
>>   lib (3erl)
>>   lib (3perl)
>
> If you complete from "li" it gives "lib (", which will make man error
> out.

What man error?  I see no problem here.  If the user sees an incomplete
manual name with the opening parenthesis, then s?he continues to complete it
to the specific section name.

> I insert a bare "lib" for such cases so that completion stops
> without the "(" for whatever is man's default page for "lib".  You may
> have seen the "chmod" example in my code.

I think it's bad to hide the fact that a manual name is ambiguous and
that the user have to select the necessary section instead of using an
arbitrary default section.  IOW, what I don't like is missing indication
that may cause to select a wrong section.  For manual names that belong
only to one section, removing the section name would be ok.

`M-x woman' deals with this problem by asking a manual file name
when the selected manual name is ambiguous.

> I also put in stuff like "3erl lib", since you can enter it like that to
> man, and it can be easier to give the section first then complete among
> pages in the section, as opposed to a section suffix.

This duplicates completions for every manual name with e.g.
"lib (3erl)" and "3erl lib".

Perhaps this is not a problem, because when the first character
of the completion is a digit, then completions are performed on the
format "3erl lib".  Otherwise, completions are performed on the
format "lib (3erl)".

For the format "lib (3erl)", you can narrow all completions to the
specific section with `M-x man RET * (3erl) TAB'.  But for the
"3erl lib" format, it is easier to type `M-x man RET 3erl TAB'.

So it seems this is a good change.

> That latter probably doesn't cooperate with Stefan's prefix-based cache
> thing as it stands.  But I found it better to cache all page names once,
> because a "-k" run is pretty much as slow asking for a few matches as
> many.
>
> I did say there was lots of things I've already been through for
> friendliness and features!  :-)

In your first message to bug#3717, you named them "feeping creatures" :-)
(I hope most features in man-completion.el are not creeping.)

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #117 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Juri Linkov <juri <at> jurta.org>
Cc: Kevin Ryde <user42 <at> zip.com.au>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 11:54:19 -0500

>> If you complete from "li" it gives "lib (", which will make man error
>> out.
> What man error?  I see no problem here.  If the user sees an incomplete
> manual name with the opening parenthesis, then s?he continues to complete it
> to the specific section name.

Maybe, but maybe the user doesn't want to care.  "lib" is a valid name
to pass to man, so completion should provide it.  After all, M-x man
can show *all* the pages found, so the choice of section can be
made later.

>> I also put in stuff like "3erl lib", since you can enter it like that to
>> man, and it can be easier to give the section first then complete among
>> pages in the section, as opposed to a section suffix.

> This duplicates completions for every manual name with e.g.
> "lib (3erl)" and "3erl lib".

Yes, a better way to do it would be to consider "3erl " "as
a directory", i.e. the completion table should recognize it and set
a "boundary" right there.  It doesn't need to provide completion for the
section names.

> For the format "lib (3erl)", you can narrow all completions to the
> specific section with `M-x man RET * (3erl) TAB'.  But for the
> "3erl lib" format, it is easier to type `M-x man RET 3erl TAB'.

You could also do it via M-x man RET 3erl C-a TAB since a * is
implicitly added at point.


        Stefan

Message #122 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Juri Linkov <juri <at> jurta.org>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 08:12:52 +1100

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> It's not a feature, AFAIK, more like an accident.

I'm pretty sure it's intentional, explicit in Man-highlight-references,
just not described in the M-x man docstring, and only a bullet point in
the commentary ...

> sed script

That bit's pretty scary.  I supposed it could equally well de-mangle in
the buffer with some lisp, if it was to be re-done.

Message #127 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 08:36:52 +1100

Eli Zaretskii <eliz <at> gnu.org> writes:
>
> It could be, but it also isn't universally available, especially if
> you are on a non-Posix platform.

I see V7 doesn't have either :-)

    http://plan9.bell-labs.com/7thEdMan/index.html

but that -k is in posix (and specified as an ERE regexp, answering a
comment Stefan put),

    http://www.opengroup.org/onlinepubs/009695399/utilities/man.html

> Ideally, `man' should test what's available, like `grep' does, and if
> nothing is, simply not provide this feature.

I'd be open to ideas for my code at least, as long as it's not merely
defunct cp/m derivatives where there's a potential problem :).

Message #132 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: Stefan Monnier <monnier <at> IRO.UMontreal.CA>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 09:01:08 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> What man error?

    M-x man
    lib (
    Ret
    => error in process sentinel: *Man lib (*: process exited abnormally with code 2

I think "(" goes onto the command line and the shell doesn't like it.
(Only balanced parens for the section getting transformed to "man 1 lib"
etc within M-x man.)

> I think it's bad to hide the fact that a manual name is ambiguous and
> that the user have to select the necessary section instead of using an
> arbitrary default section.

Perhaps that could be an option, but if so I think I'd try to bring up a
display-completion-list thingie, to emphasise you're being asked to
choose, since the incomplete "lib (" is no good.

> For manual names that belong only to one section, removing the section
> name would be ok.

Yep, that's what I've got, to declutter.

> when the first character
> of the completion is a digit, then completions are performed on the
> format "3erl lib".  Otherwise, completions are performed on the
> format "lib (3erl)".

Yes.  There's an occasional program name starting with a digit, but you
can type "3 " or whatever with the space to get past that -- in fact if
you want a specific section I think that's a pretty natural thing to
type.

> In your first message to bug#3717, you named them "feeping creatures" :-)

You're not going to hold me to anything I said so long ago are you! :-)

The perl searching for the default page name at point creeps a bit, but
I've found it very helpful, and haven't had a better idea for where to
tie it in.


Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> "lib" is a valid name to pass to man, so completion should provide it.

That was my rationale.

> After all, M-x man
> can show *all* the pages found, so the choice of section can be
> made later.

I didn't think of that, but yes.

> Yes, a better way to do it would be to consider "3erl " "as
> a directory", i.e. the completion table should recognize it and set
> a "boundary" right there.  It doesn't need to provide completion for the
> section names.

I haven't understood the boundaries thing.  Is it as simple as making a
space or "(" a boundary point?

> You could also do it via M-x man RET 3erl C-a TAB since a * is
> implicitly added at point.

You've got to be smarter than me to think of that :).  My main idea is
that you can type M-x man "2 chmod", and likewise on the man command
line, so completion should help you with that typing.

Message #137 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 09:09:18 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> You could try to use annotations in the *Completions* buffer.

Ah yeah.

> I can't say
> in advance how convenient it would be to use them for man completions.

Could be a bit noisy, or stop you easily seeing all of a medium-long
list of completions.  Is there a conventional builtin way to
enable/disable annotations on a particular flavour of completion?
A flag or function variable would work no doubt.  But I might just
tie-in to completing-help and whatever else and let them worry about how
to select.

Message #142 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: Stefan Monnier <monnier <at> IRO.UMontreal.CA>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 00:36:23 +0200

>> For manual names that belong only to one section, removing the section
>> name would be ok.
>
> Yep, that's what I've got, to declutter.

But then you don't see additional information about section names that
may help to select the necessary manual.  So I tend to agree with your
implementation in man-completion.el that provides completions in
3 formats: without a section name, with the section name appended
in parens, and prepended at the beginning:

    "chmod"
    "chmod (1)"
    "chmod (2)"
    "1 chmod"
    "2 chmod"

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #147 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: Stefan Monnier <monnier <at> IRO.UMontreal.CA>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 10:15:23 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> But then you don't see additional information about section names that
> may help to select the necessary manual.

You mean on a unique name, like say "gunzip"?  I wasn't terribly
interested in the section number as a suffix if it's unique.  Omitting
it makes for a cleaner list; and it could be a bit confusing if the bare
name is present for duplicated pages but not present for unique ones.
But perhaps it's personal preference.

Message #152 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: jidanni <at> jidanni.org
To: juri <at> jurta.org
Cc: user42 <at> zip.com.au, monnier <at> iro.umontreal.ca,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 07:34:46 +0800

JL>     "chmod (1)"
You guys are way over my head but I remember man page name have no space
before the "(".

Message #157 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: jidanni <at> jidanni.org
Cc: juri <at> jurta.org, monnier <at> iro.umontreal.ca, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 11:24:11 +1100

jidanni <at> jidanni.org writes:
>
> I remember man page name have no space
> before the "(".

That's my preference too.  It's how cross-references appear in man
pages, so I made the completions that way too, without worrying that
"man -k" likes to output.

Message #162 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: Juri Linkov <juri <at> jurta.org>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 26 Nov 2009 21:30:56 -0500

>> I can't say in advance how convenient it would be to use them for
>> man completions.
> Could be a bit noisy, or stop you easily seeing all of a medium-long
> list of completions.  Is there a conventional builtin way to
> enable/disable annotations on a particular flavour of completion?
> A flag or function variable would work no doubt.

I've been mulling over completing-help for quite a while now and I don't
think a customization var is a good solution.  Instead, we'd want
something more dynamic.  An easy solution is to put a help-echo property
on the completion string.  Otherwise some completion-list-mode command
should be provided to toggle annotations.


        Stefan

Message #167 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 10:47:08 +0200

> From: Kevin Ryde <user42 <at> zip.com.au>
> Cc: 3717 <at> emacsbugs.donarmstrong.com
> Date: Fri, 27 Nov 2009 08:36:52 +1100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> >
> > It could be, but it also isn't universally available, especially if
> > you are on a non-Posix platform.
> 
> I see V7 doesn't have either :-)
> 
>     http://plan9.bell-labs.com/7thEdMan/index.html
> 
> but that -k is in posix (and specified as an ERE regexp, answering a
> comment Stefan put),
> 
>     http://www.opengroup.org/onlinepubs/009695399/utilities/man.html

Emacs doesn't (and shouldn't, IMO) require Posix to work well.

> > Ideally, `man' should test what's available, like `grep' does, and if
> > nothing is, simply not provide this feature.
> 
> I'd be open to ideas for my code at least, as long as it's not merely
> defunct cp/m derivatives where there's a potential problem :).

I'm not sure I understand the remark, but how about searching MANPATH
directories ourselves?  That would be much more portable, I think.

Message #172 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: Stefan Monnier <monnier <at> IRO.UMontreal.CA>, jidanni <at> jidanni.org,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 11:01:00 +0200

>> But then you don't see additional information about section names that
>> may help to select the necessary manual.
>
> You mean on a unique name, like say "gunzip"?  I wasn't terribly
> interested in the section number as a suffix if it's unique.

You are not interested in the section number for "gunzip" because you
already know that it's a command name.  I'm not interested in the
section number for known commands too.

But in the rest 90% cases, I would be terribly interested in the section
number to know if the unique name belongs to 3erl or 3form or 3menu or 3nas
or 3ncurses or 3perl or 3pm or 3readline or 3ssl or 3tiff or 3x.

> Omitting it makes for a cleaner list; and it could be a bit confusing
> if the bare name is present for duplicated pages but not present for
> unique ones.

I'd rather get rid of the bare name than of the section number appended to
the manual name.

> But perhaps it's personal preference.

We could add an option.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #177 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: jidanni <at> jidanni.org, monnier <at> iro.umontreal.ca,
        3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 27 Nov 2009 11:04:34 +0200

>> I remember man page name have no space
>> before the "(".
>
> That's my preference too.  It's how cross-references appear in man
> pages, so I made the completions that way too, without worrying that
> "man -k" likes to output.

A name with a space is more readable, but for completion
it seems a name with no space would be better.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #182 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: 3717 <at> debbugs.gnu.org
Cc: Kevin Ryde <user42 <at> zip.com.au>, jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Sat, 28 Nov 2009 19:56:38 +0200

>>> But then you don't see additional information about section names that
>>> may help to select the necessary manual.
>>
>> You mean on a unique name, like say "gunzip"?  I wasn't terribly
>> interested in the section number as a suffix if it's unique.
>
> You are not interested in the section number for "gunzip" because you
> already know that it's a command name.  I'm not interested in the
> section number for known commands too.
>
> But in the rest 90% cases, I would be terribly interested in the section
> number to know if the unique name belongs to 3erl or 3form or 3menu or 3nas
> or 3ncurses or 3perl or 3pm or 3readline or 3ssl or 3tiff or 3x.

I think with the Stefan's 2009-11-27 change we have almost perfect
implementation.  After typing `M-x man RET gunzip TAB' it stops at
"gunzip", not at "gunzip(1)" (that you can get with another TAB).
That's nice.

The only problem I see is with the "2 chmod" format completion.
Currently it's too difficult to use it.  Let's see:

  M-x man RET 2 TAB [No match]

Another attempt:

  M-x man RET 2 SPC [No match]

Only after quoting SPC you get a list of completions for the section 2:

  M-x man RET 2 C-q SPC TAB

I think it would be fine to list manuals of the section 2 after:

  M-x man RET 2 TAB

because manual names that begin with a digit are very rare.
Here I can find only one such command - "7z".  We could add this
sole name to the list of manuals from the section 7 on typing

  M-x man RET 7 TAB

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #187 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 06:49:12 +1100

Eli Zaretskii <eliz <at> gnu.org> writes:
>
> how about searching MANPATH directories ourselves?

M-x woman does that, though finding the manpath isn't necessarily easy
(with the man-db /etc/manpath.conf), and there can be pagename aliases
found by lexgrog in the pages, which don't have actual filenames.

If man can say its page names then asking it would have to be the most
reliable way.  I slightly hoped near enough to all mans could do that
these days ...

Message #192 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: 3717 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 07:14:58 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> The only problem I see is with the "2 chmod" format completion.

It's quite important too, as it's the natural format from the man
command line.

> because manual names that begin with a digit are very rare.
> Here I can find only one such command - "7z".

Debian has an "822-date" program too, I don't know of any others.
With some care it should be possible to treat them like any other name.

Message #197 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org, jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 00:54:49 +0200

>> The only problem I see is with the "2 chmod" format completion.
>
> It's quite important too, as it's the natural format from the man
> command line.
>
>> because manual names that begin with a digit are very rare.
>> Here I can find only one such command - "7z".
>
> Debian has an "822-date" program too, I don't know of any others.
> With some care it should be possible to treat them like any other name.

When I run "822-date", it says:

  822-date: warning: This program is deprecated. Please use 'date -R' instead.

So it's not important.  But nevertheless we should take care about such
rare cases.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #202 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 00:59:19 +0200

> If man can say its page names then asking it would have to be the most
> reliable way.

It should be implemented to fail gracefully to not display completions
when man can not say its page names.

> I slightly hoped near enough to all mans could do that these days ...

At least, all GNU/Linux men do that these days :-)

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #207 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Juri Linkov <juri <at> jurta.org>
Cc: 3717 <at> debbugs.gnu.org, Kevin Ryde <user42 <at> zip.com.au>
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 10:34:26 -0500

>> If man can say its page names then asking it would have to be the most
>> reliable way.
> It should be implemented to fail gracefully to not display completions
> when man can not say its page names.

AFAIK it does.


        Stefan

Message #212 received at 3717-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 3717-done <at> debbugs.gnu.org, Kevin Ryde <user42 <at> zip.com.au>
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 18:01:05 +0200

>>> If man can say its page names then asking it would have to be the most
>>> reliable way.
>> It should be implemented to fail gracefully to not display completions
>> when man can not say its page names.
>
> AFAIK it does.

Yes, I tried to emulate `man' that doesn't support the -k switch
(using a non-existent switch), and it fails gracefully by not
providing completions, i.e. the same behavior as was in Emacs 23.1.
Anyone on platforms where `man' doesn't support the -k switch,
could use woman.el anyway.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #222 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 03 Dec 2009 09:41:22 +1100

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> "boundary"

Speaking of boundaries, I wonder if perl "::" would be a good boundary,
since it's basically a directory separator in disguise.  I'll give it a
go - though I'm not a sophisticated completions user, so I wonder if
I'll notice the difference :).

    (cond ((eq (car-safe action) 'boundaries) ;; emacs23
           (let* ((suffix (cdr action))
                  ;; after last "::", or after start of string
                  ;; (page names don't have newlines, so ".*" is ok)
                  (start  (if (string-match ".*::" str) (match-end 0) 0))
                  ;; first "::", or end of string
                  (end    (string-match "::\\|\\'" suffix)))
             (cons 'boundaries (cons start end))))

Message #227 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Wed, 02 Dec 2009 19:53:20 -0500

> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>> "boundary"

> Speaking of boundaries, I wonder if perl "::" would be a good boundary,
> since it's basically a directory separator in disguise.  I'll give it a
> go - though I'm not a sophisticated completions user, so I wonder if
> I'll notice the difference :).

>     (cond ((eq (car-safe action) 'boundaries) ;; emacs23
>            (let* ((suffix (cdr action))
>                   ;; after last "::", or after start of string
>                   ;; (page names don't have newlines, so ".*" is ok)
>                   (start  (if (string-match ".*::" str) (match-end 0) 0))
>                   ;; first "::", or end of string
>                   (end    (string-match "::\\|\\'" suffix)))
>              (cons 'boundaries (cons start end))))

The `completion-boundaries' info is really a meta-information about what
`all-completions' returns.  So it doesn't make sense to only change
`bundaries' without changing the `all-completions' behavior accodingly.

This said: adding ":" to completion-pcm-word-delimiters would be easier
and would work probably as well if not better,


        Stefan

Message #232 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sat, 05 Dec 2009 09:50:00 +1100

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> This said: adding ":" to completion-pcm-word-delimiters would be easier
> and would work probably as well if not better,

Ah, I think that's what I wanted.  Add with a let binding, or globally?

Message #237 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sat, 05 Dec 2009 09:53:26 +1100

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> An easy solution is to put a help-echo property on the completion
> string.

It works straight away.  Would it be recommended basically always, or be
a touch too intrusive?  I suppose there's configs already for how
help-echo becomes tooltips etc.

Message #242 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sat, 05 Dec 2009 00:02:31 -0500

>> This said: adding ":" to completion-pcm-word-delimiters would be easier
>> and would work probably as well if not better,

> Ah, I think that's what I wanted.  Add with a let binding, or globally?

I think we can just change the default.  It could also include other
punctuation chars like / (used for pcomplete function names, for
example).


        Stefan

Message #247 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Ryde <user42 <at> zip.com.au>, 3717 <at> debbugs.gnu.org
Cc: monnier <at> iro.umontreal.ca
Subject: Re: bug#3717: M-x man completion
Date: Sat, 05 Dec 2009 11:31:54 +0200

> From: Kevin Ryde <user42 <at> zip.com.au>
> Date: Sat, 05 Dec 2009 09:53:26 +1100
> Cc: 3717 <at> emacsbugs.donarmstrong.com
> 
> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
> >
> > An easy solution is to put a help-echo property on the completion
> > string.
> 
> It works straight away.  Would it be recommended basically always, or be
> a touch too intrusive?  I suppose there's configs already for how
> help-echo becomes tooltips etc.

If you decide to go this way, please don't forget that help-echo can
be configured to be displayed in the echo area.

Message #252 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sun, 06 Dec 2009 10:12:48 +1100

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
> I think we can just change the default.

Sounds good.  It won't upset cp/m drive letters in filename completion
will it?

Message #257 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sun, 06 Dec 2009 21:26:45 -0500

>> I think we can just change the default.
> Sounds good.  It won't upset cp/m drive letters in filename completion
> will it?

I wouldn't be able to tell you.


        Stefan

Message #262 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sat, 12 Dec 2009 09:43:13 +1100

Eli Zaretskii <eliz <at> gnu.org> writes:
>
> If you decide to go this way, please don't forget that help-echo can
> be configured to be displayed in the echo area.

Which would hide the minibuffer prompt and text entry?  I think I struck
something like that in another context, a message hiding my text entry
or something like that.  Not good.

(Might be ok for completions if it was only when you've switched current
window to the completions window, or something like that ...)

Message #267 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Sat, 12 Dec 2009 11:03:30 +0200

> From: Kevin Ryde <user42 <at> zip.com.au>
> Cc: 3717 <at> emacsbugs.donarmstrong.com
> Date: Sat, 12 Dec 2009 09:43:13 +1100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> >
> > If you decide to go this way, please don't forget that help-echo can
> > be configured to be displayed in the echo area.
> 
> Which would hide the minibuffer prompt and text entry?

Maybe, I don't know.  I just meant to say that any such features need
to be tested with help-echo in echo area as well, before they are
accepted as good solutions.

Message #272 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: jidanni <at> jidanni.org
To: user42 <at> zip.com.au
Cc: juri <at> jurta.org, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Tue, 15 Dec 2009 14:18:44 +0800

I get
completion--some: Searching for program: no such file or directory, LC_CTYPE=C man
when I do M-x man ca<TAB>
Because I do (setq manual-program "LC_CTYPE=C man") in .emacs due to
various reasons... I use Debian emacs-snapshot 1:20091128-1

Message #277 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: jidanni <at> jidanni.org, 3717 <at> debbugs.gnu.org
Cc: user42 <at> zip.com.au
Subject: Re: bug#3717: M-x man completion
Date: Tue, 15 Dec 2009 03:04:30 -0500

> From: jidanni <at> jidanni.org
> Date: Tue, 15 Dec 2009 14:18:44 +0800
> Cc: 3717 <at> emacsbugs.donarmstrong.com
> Reply-To: jidanni <at> jidanni.org, 3717 <at> emacsbugs.donarmstrong.com
> 
> I get
> completion--some: Searching for program: no such file or directory, LC_CTYPE=C man
> when I do M-x man ca<TAB>
> Because I do (setq manual-program "LC_CTYPE=C man")

That's an abuse of manual-program: it is supposed to be the name of a
program, not a command string.

Message #282 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Juri Linkov <juri <at> jurta.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3717 <at> debbugs.gnu.org, jidanni <at> jidanni.org, user42 <at> zip.com.au
Subject: Re: bug#3717: M-x man completion
Date: Wed, 16 Dec 2009 02:42:17 +0200

>> I get
>> completion--some: Searching for program: no such file or directory, LC_CTYPE=C man
>> when I do M-x man ca<TAB>
>> Because I do (setq manual-program "LC_CTYPE=C man")
>
> That's an abuse of manual-program: it is supposed to be the name of a
> program, not a command string.

I wonder why such abuse works for the normal use of `M-x man',
but doesn't work for man completions that run "man -k".

I see that `Man-getpage-in-background' calls `start-process' (with
a shell command name prepended) to run "man", but `Man-completion-table'
calls `call-process' (without a shell command prepended) to run "man -k".
That's the difference.

Shouldn't `Man-completion-table' prepend a shell command name to not fail
when `manual-program' is "LC_CTYPE=C man"?  Isn't it easier just to do this
than to declare it as an abuse?

If we declare such use of `manual-program' as an abuse, what we can suggest
to use instead?

-- 
Juri Linkov
http://www.jurta.org/emacs/

Message #287 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> jurta.org>
Cc: 3717 <at> debbugs.gnu.org, jidanni <at> jidanni.org, user42 <at> zip.com.au
Subject: Re: bug#3717: M-x man completion
Date: Wed, 16 Dec 2009 06:19:04 +0200

> From: Juri Linkov <juri <at> jurta.org>
> Cc: 3717 <at> emacsbugs.donarmstrong.com,  jidanni <at> jidanni.org,  user42 <at> zip.com.au
> Date: Wed, 16 Dec 2009 02:42:17 +0200
> 
> I see that `Man-getpage-in-background' calls `start-process' (with
> a shell command name prepended) to run "man", but `Man-completion-table'
> calls `call-process' (without a shell command prepended) to run "man -k".
> That's the difference.
> 
> Shouldn't `Man-completion-table' prepend a shell command name to not fail
> when `manual-program' is "LC_CTYPE=C man"?  Isn't it easier just to do this
> than to declare it as an abuse?

I have nothing against calling `man' through the shell in all cases,
but if we do that, we need to rename the variable to something like
`man-shell-command' and document it as a "shell command that produces
manual pages".

Message #292 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 3717 <at> debbugs.gnu.org,
        jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 17 Dec 2009 08:25:11 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> shell command name prepended) to run "man",

I think that's how "-k foo" and "-l /dir/bar.1" work, because it's a bit
of a shell line, not a single arg.  Slightly dangerous if you're silly
enough to enter "; rm /my/whole/filesystem" :-).

Eli Zaretskii <eliz <at> gnu.org> writes:
>
> `man-shell-command'

I don't think it should be renamed.  If it's been a shell command
forever then just use it that way.

Message #297 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: 3717 <at> debbugs.gnu.org
Cc: jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 17 Dec 2009 08:40:17 +1100

On the subject of M-x man "-k foo" being kept secret, I thought to
revise the docstring a bit per below (formatted for reading).

I think samples of what can be entered are easier to read than words,
especially if skimming.

The "-a" bit is per man-db, but it's not posix, so I wonder if it varies
on other mans.  Did for instance BSD from years ago have the equivalent
of -a as its default anyway?


2009-12-16  Kevin Ryde  <user42 <at> zip.com.au>

	* man.el (man): Revise docstring to show -k and -l examples, and
	mention -a in the "all sections" bit.



Get a Un*x manual page and put it in a buffer.
This command is the top-level command in the man package.  It
runs a Un*x command to retrieve and clean a manpage in the
background and places the results in a `Man-mode' browsing
buffer.  See variable `Man-notify-method' for what happens when
the buffer is ready.  If a buffer already exists for this man
page, it will display immediately.

For a manpage from a certain section, use either of the following
forms.  "cat(1)" is how cross-references appear and is passed
to man as "1 cat".

    cat(1)
    1 cat

To see manpages from all sections related to a subject, put an
"all pages" option into `Man-switches', usually "-a", then
step through with `Man-next-manpage' (M-n) etc.

An explicit filename can be given.  Use -l if it might otherwise
look like a page name.

    /my/file/name.1.gz
    -l somefile.1

An "apropos" query with -k gives a buffer of matching page
names or descriptions.  The pattern argument is usually an
"egrep" style regexp.

    -k pattern

Message #302 received at 3717 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: jidanni <at> jidanni.org, 3717 <at> debbugs.gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 17 Dec 2009 08:44:02 +1100

I wrote:
>
> insinuate "-k " and "-l " so it's possible to type those things
> without needing C-q Space.

I've since thought to help any "-" option, not just -k and -l, with a
constructed table in the completion handler along these lines.

Not sure it's fantastic for "?" or "tab", but gets the right effect on
space.


        ((string-match "\\`-\\(.\\)?" str)
         ;; "-" or "-X" -- alone and with a space so you don't have to type
         ;; C-q space after an option.  "-l" or "-k" are shown as standard
         ;; options, but then add anything else so other options can be
         ;; typed.
         ;;
         ;; For formatting options like "-Tascii" could think about applying
         ;; the pagename or filename completion to the next arg, but
         ;; normally such options will go in `Man-switches'.
         ;;
         (let ((table '(("-l " . "run man on a file")
                        ("-k " . "search apropos database"))))
           (unless (member str '("-k" "-l" "-k " "-l "))
             (push (cons str "option") table)
             (push (cons (concat str " ") "option") table))
           (man-completion--complete-with-action action table str pred)))

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

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 18 Dec 2009 01:35:47 +0200

> Man-completion-table would no doubt need a shell-quote-argument or
> something to get its match string through the shell.  But I still think
> Man-completion-table might better grab the entire list of page names
> once.  On my old pc with 13,000 page names (yes, really :-) it's almost
> as slow to fetch a few matches or the whole lot.  The cost is the RAM to
> keep them all of course.

How much RAM does this need?  With my 11,000 page names as text they take
700 KB.  I think this is not that much.

-- 
Juri Linkov
http://www.jurta.org/emacs/

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

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: 3717 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 18 Dec 2009 12:00:44 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> 700 KB

More with cons cells?

> I think this is not that much.

Oh, it's about speed for me really.  If man-db was faster I expect I'd
think different (as the saying goes :-).

Another motivation for me keeping the whole lot is my perl page-at-point
helper which looks for a suffix of a page name for a shorthand of
otherwise long perl classes.  It means an immediate lookup on any
class-like thing at point, which is upcase or :: at the moment.



-- 
The sigfile one-line movie reviews series:
"Les Amants du Pont Neuf" -- fine sequel to Les Amants du Pont Huit.

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

From: Juri Linkov <juri <at> jurta.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 3717 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
	jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Thu, 17 Dec 2009 03:27:44 +0200

> I don't think it should be renamed.  If it's been a shell command
> forever then just use it that way.

I agree that it should not be renamed.  But we still have a problem that
Jidanni (who asked us to implement man completions) can't use this feature
because `Man-completion-table' currently doesn't allow a command line like
`Man-getpage-in-background' does for a long time.

-- 
Juri Linkov
http://www.jurta.org/emacs/

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

From: jidanni <at> jidanni.org
To: user42 <at> zip.com.au
Cc: juri <at> jurta.org, 3717 <at> debbugs.gnu.org, eliz <at> gnu.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 18 Dec 2009 05:59:17 +0800

All I know is these can handle command expansion just fine,

  ! runs the command dired-do-shell-command, which is an interactive
    compiled Lisp function in `dired-aux.el'.

  [and the] command compile, which is an interactive compiled Lisp
  function in `compile.el'.

OK, so you want to get more than just section 1, and 8 [$PATH commands.]
But the fact that I need to (setq manual-program "LC_CTYPE=C man")
shouldn't have anything to do with it.

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

From: Kevin Ryde <user42 <at> zip.com.au>
To: Juri Linkov <juri <at> jurta.org>
Cc: 3717 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
	jidanni <at> jidanni.org
Subject: Re: bug#3717: M-x man completion
Date: Fri, 18 Dec 2009 07:20:09 +1100

Juri Linkov <juri <at> jurta.org> writes:
>
> because `Man-completion-table' currently doesn't allow a command line

I threw down a couple of lines

        (call-process shell-file-name nil t nil
                      shell-command-switch
                      (concat manual-program " -k \"\""))

which get the right effect for me.  Not sure if Man-switches should be
worked in there.  If they're page formatting options they might be bad
with -k.

Man-completion-table would no doubt need a shell-quote-argument or
something to get its match string through the shell.  But I still think
Man-completion-table might better grab the entire list of page names
once.  On my old pc with 13,000 page names (yes, really :-) it's almost
as slow to fetch a few matches or the whole lot.  The cost is the RAM to
keep them all of course.

Previous Next

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