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/