bug#3717: M-x man completion

bug#3717: M-x man completion

[jidanni]

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

bug#3717: M-x man completion

[Stefan Monnier]

>>>>> "jidanni" == jidanni  <jidanni@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))))

bug#3717: M-x man completion

[Sven Joachim]

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

>>>>>> "jidanni" == jidanni  <jidanni@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

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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".

bug#4056: 23.1.50; use shell-command completion for M-x man page names

[jidanni]

Gentlemen, as you know when you do M-x man and get the prompt
   Manual entry (default blabla):
there is no TAB completion.

Well as many of the man pages are the same names as shell commands, why
not just use the same completion as shell-command and
shell-command-on-region use?

It's better than nothing, and one can still enter other names too.

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Stefan Monnier]

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

Yes, done, thank you,


        Stefan

bug#3717: M-x man completion

[Kevin Ryde]

[-- Attachment #1: Type: text/plain, Size: 1409 bytes --]

Juri Linkov <juri@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@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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: man.el.no-truncate.diff --]
[-- Type: text/x-diff, Size: 1079 bytes --]

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

bug#3717: M-x man completion

[Kevin Ryde]

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

bug#3717: M-x man completion

[Eli Zaretskii]

> From: Kevin Ryde <user42@zip.com.au>
> Date: Wed, 25 Nov 2009 09:58:09 +1100
> Cc: 3717@emacsbugs.donarmstrong.com, jidanni@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.

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Stefan Monnier]

> 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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Kevin Ryde]

Eli Zaretskii <eliz@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 :-).

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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!  :-)

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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!)

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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.

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: M-x man completion

[Eli Zaretskii]

> From: Kevin Ryde <user42@zip.com.au>
> Cc: 3717@emacsbugs.donarmstrong.com
> Date: Thu, 26 Nov 2009 09:53:28 +1100
> 
> Eli Zaretskii <eliz@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.

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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.

bug#3717: M-x man completion

[Kevin Ryde]

Eli Zaretskii <eliz@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 :).

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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@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.

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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.

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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.

bug#3717: M-x man completion

[jidanni]

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

bug#3717: M-x man completion

[Kevin Ryde]

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

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: M-x man completion

[Eli Zaretskii]

> From: Kevin Ryde <user42@zip.com.au>
> Cc: 3717@emacsbugs.donarmstrong.com
> Date: Fri, 27 Nov 2009 08:36:52 +1100
> 
> Eli Zaretskii <eliz@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.

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Kevin Ryde]

Eli Zaretskii <eliz@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 ...

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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.

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: marked as done (M-x man completion)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 833 bytes --]

Your message dated Sun, 29 Nov 2009 18:01:05 +0200
with message-id <87fx7x72qd.fsf@mail.jurta.org>
and subject line Re: bug#3717: M-x man completion
has caused the Emacs bug report #3717,
regarding M-x man completion
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
3717: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=3717
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 2199 bytes --]

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

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



[-- Attachment #3: Type: message/rfc822, Size: 2370 bytes --]

From: Juri Linkov <juri@jurta.org>
To: Stefan Monnier <monnier@iro.umontreal.ca>
Cc: 3717-done@emacsbugs.donarmstrong.com, Kevin Ryde <user42@zip.com.au>
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 18:01:05 +0200
Message-ID: <87fx7x72qd.fsf@mail.jurta.org>

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

bug#4056: marked as done (23.1.50; use shell-command completion for M-x man page names)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 875 bytes --]

Your message dated Sun, 29 Nov 2009 18:01:05 +0200
with message-id <87fx7x72qd.fsf@mail.jurta.org>
and subject line Re: bug#3717: M-x man completion
has caused the Emacs bug report #3717,
regarding 23.1.50; use shell-command completion for M-x man page names
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
3717: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=3717
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 2368 bytes --]

From: jidanni@jidanni.org
Cc: emacs-pretest-bug@gnu.org
Subject: 23.1.50; use shell-command completion for M-x man page names
Date: Thu, 06 Aug 2009 09:47:43 +0800
Message-ID: <87hbwld874.fsf@jidanni.org>

Gentlemen, as you know when you do M-x man and get the prompt
   Manual entry (default blabla):
there is no TAB completion.

Well as many of the man pages are the same names as shell commands, why
not just use the same completion as shell-command and
shell-command-on-region use?

It's better than nothing, and one can still enter other names too.


[-- Attachment #3: Type: message/rfc822, Size: 2370 bytes --]

From: Juri Linkov <juri@jurta.org>
To: Stefan Monnier <monnier@iro.umontreal.ca>
Cc: 3717-done@emacsbugs.donarmstrong.com, Kevin Ryde <user42@zip.com.au>
Subject: Re: bug#3717: M-x man completion
Date: Sun, 29 Nov 2009 18:01:05 +0200
Message-ID: <87fx7x72qd.fsf@mail.jurta.org>

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

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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))))

bug#3717: M-x man completion

[Stefan Monnier]

> Stefan Monnier <monnier@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

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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?

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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.

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: M-x man completion

[Eli Zaretskii]

> From: Kevin Ryde <user42@zip.com.au>
> Date: Sat, 05 Dec 2009 09:53:26 +1100
> Cc: 3717@emacsbugs.donarmstrong.com
> 
> Stefan Monnier <monnier@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.

bug#3717: M-x man completion

[Kevin Ryde]

Stefan Monnier <monnier@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?

bug#3717: M-x man completion

[Stefan Monnier]

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

bug#3717: M-x man completion

[Kevin Ryde]

Eli Zaretskii <eliz@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 ...)

bug#3717: M-x man completion

[Eli Zaretskii]

> From: Kevin Ryde <user42@zip.com.au>
> Cc: 3717@emacsbugs.donarmstrong.com
> Date: Sat, 12 Dec 2009 09:43:13 +1100
> 
> Eli Zaretskii <eliz@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.

bug#3717: M-x man completion

[jidanni]

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

bug#3717: M-x man completion

[Eli Zaretskii]

> From: jidanni@jidanni.org
> Date: Tue, 15 Dec 2009 14:18:44 +0800
> Cc: 3717@emacsbugs.donarmstrong.com
> Reply-To: jidanni@jidanni.org, 3717@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.

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Cc: 3717@emacsbugs.donarmstrong.com,  jidanni@jidanni.org,  user42@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".

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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@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.

bug#3717: M-x man completion

[Kevin Ryde]

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

bug#3717: M-x man completion

[Kevin Ryde]

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

bug#3717: M-x man completion

[Juri Linkov]

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

bug#3717: M-x man completion

[Kevin Ryde]

Juri Linkov <juri@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.

bug#4056: completion--some: Searching for program: no such file or directory, LC_CTYPE=C man

[jidanni]

reopen 4056
found 4056 1:20100118-1
thanks
Help, as of debian-snapshot 1:20100118-1 I am still getting
      completion--some: Searching for program: no such file or directory, LC_CTYPE=C man
when I hit M-x man bla<TAB>
just because I have (setq manual-program "LC_CTYPE=C man") in
http://jidanni.org/comp/configuration/.emacs .

bug#4056: Searching for program: no such file or directory, LC_CTYPE=C man

[jidanni]

Can someone please send me the workaround!!

bug#4056: Searching for program: no such file or directory, LC_CTYPE=C man

[Kenichi Handa]

In article <874olr1r7z.fsf@jidanni.org>, jidanni@jidanni.org writes:

> Can someone please send me the workaround!!

How about making this shell script "man.sh" somewher in your PATH,

#!/bin/sh
LC_CTYPE=C man $@

and set manual-program to "man.sh"?

---
Kenichi Handa
handa@m17n.org

bug#4056: Searching for program: no such file or directory, LC_CTYPE=C man

[jidanni]

K> How about making this shell script "man.sh" somewher in your PATH...
OK, thanks!

bug#4056: Searching for program: no such file or directory, LC_CTYPE=C man

[Stefan Monnier]

> Can someone please send me the workaround!!

I've just installed the patch below which should silence those errors
(tho the error will still be there and will prevent completion from
working).



        Stefan


=== modified file 'lisp/man.el'
--- lisp/man.el	2010-01-13 08:35:10 +0000
+++ lisp/man.el	2010-02-11 15:54:21 +0000
@@ -771,8 +771,13 @@
           ;; quote anything.
           (let ((process-environment (copy-sequence process-environment)))
             (setenv "COLUMNS" "999") ;; don't truncate long names
+            ;; manual-program might not even exist.  And since it's
+            ;; run differently in Man-getpage-in-background, an error
+            ;; here may not necessarily mean that we'll also get an
+            ;; error later.
+            (ignore-errors
             (call-process manual-program nil '(t nil) nil
-                          "-k" (concat "^" prefix)))
+                            "-k" (concat "^" prefix))))
           (goto-char (point-min))
           (while (re-search-forward "^\\([^ \t\n]+\\)\\(?: ?\\((.+?)\\)\\(?:[ \t]+- \\(.*\\)\\)?\\)?" nil t)
             (push (propertize (concat (match-string 1) (match-string 2))

bug#4056: Searching for program: no such file or directory, LC_CTYPE=C man

[jidanni]

>>>>> "SM" == Stefan Monnier <monnier@iro.umontreal.ca> writes:

SM> (tho the error will still be there and will prevent completion from
SM> working).

Well OK but maybe the bug should not be closed completely then.