Completion of links to man pages

Completion of links to man pages

[Max Nikulin]

Hi,

I am unsure if the code below is appropriate for :complete property of 
"man" link. It does not rely on any double-dash functions or variables, 
but it still uses some implementation details since there is no suitable 
high level functions in man.el and woman.el from Emacs.

(defun org-man-complete (&optional _arg)
   "Helper for completion of links to man pages."
   (concat
    "man:"
    (let ((completion-ignore-case t)) ; See `man' comments.
      (funcall
       (if (eq org-man-command 'woman)
           #'org-man--complete-woman
         #'org-man--complete-man)
       "Manual entry: "))))

(defun org-man--complete-man (prompt)
   (require 'man)
   (let (Man-completion-cache)
     (completing-read
      prompt
      'Man-completion-table)))

(defun org-man--init-woman-cache (&optional re-cache)
   (unless (and (not re-cache)
                (or
                 (and woman-expanded-directory-path
                      woman-topic-all-completions)
                 (woman-read-directory-cache)))
     (setq woman-expanded-directory-path
           (woman-expand-directory-path woman-manpath woman-path))
     (setq woman-totic-all-completions
           (woman-topic-all-completions woman-expand-directory-path))
     (woman-write-directory-cache)))

(defun org-man--complete-woman (prompt)
   (require 'woman)
   (org-man--init-woman-cache)
   (completing-read prompt woman-topic-all-completions))

Re: Completion of links to man pages

[Ihor Radchenko]

[ CCing emacs-devel ]

Max Nikulin <manikulin@gmail.com> writes:

> I am unsure if the code below is appropriate for :complete property of 
> "man" link. It does not rely on any double-dash functions or variables, 
> but it still uses some implementation details since there is no suitable 
> high level functions in man.el and woman.el from Emacs.

Without docstrings, we cannot rely even on single-dash functions.

To emacs-devel: Would it be of interest to expose man/woman completion
API?

> (defun org-man-complete (&optional _arg)
>    "Helper for completion of links to man pages."
>    (concat
>     "man:"
>     (let ((completion-ignore-case t)) ; See `man' comments.

`completion-ignore-case' is not set in woman.

>       (funcall
>        (if (eq org-man-command 'woman)
>            #'org-man--complete-woman
>          #'org-man--complete-man)
>        "Manual entry: "))))
>
> (defun org-man--complete-man (prompt)
>    (require 'man)
>    (let (Man-completion-cache)
>      (completing-read
>       prompt
>       'Man-completion-table)))

> (defun org-man--init-woman-cache (&optional re-cache)
>    (unless (and (not re-cache)
>                 (or
>                  (and woman-expanded-directory-path
>                       woman-topic-all-completions)
>                  (woman-read-directory-cache)))
>      (setq woman-expanded-directory-path
>            (woman-expand-directory-path woman-manpath woman-path))
>      (setq woman-totic-all-completions
>            (woman-topic-all-completions woman-expand-directory-path))
>      (woman-write-directory-cache)))
>
> (defun org-man--complete-woman (prompt)
>    (require 'woman)
>    (org-man--init-woman-cache)
>    (completing-read prompt woman-topic-all-completions))

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Max Nikulin]

On 05/10/2023 18:40, Ihor Radchenko wrote:
> [ CCing emacs-devel ]
> 
> To emacs-devel: Would it be of interest to expose man/woman completion
> API?

Since Org mode supports a couple of previous Emacs versions, I would 
avoid cross-posting. I just sent a draft to evaluate if code can be 
added to Org.

>>      (let ((completion-ignore-case t)) ; See `man' comments.
> 
> `completion-ignore-case' is not set in woman.

There are enough inconsistencies between man and woman, I am unsure if 
all of them should be mirrored in Org mode.

Frankly speaking, I am unsure if woman should be supported in Org at 
all. My early experience with woman.el was not nice. I tried M-x woman 
RET ssh RET (openssh).

Re: Completion of links to man pages

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> To emacs-devel: Would it be of interest to expose man/woman completion
>> API?
>
> Since Org mode supports a couple of previous Emacs versions, I would 
> avoid cross-posting. I just sent a draft to evaluate if code can be 
> added to Org.

Previous Emacs versions are not a concern, because we can rely on the
implementation details there. It is the new Emacs versions where
implementation details may change that are the concern. That's why I
decided to consult emacs-devel - if we cannot rely on these details, we
will add maintenance burden upon us to track internal implementation
changes in man/woman.

>>>      (let ((completion-ignore-case t)) ; See `man' comments.
>> 
>> `completion-ignore-case' is not set in woman.
>
> There are enough inconsistencies between man and woman, I am unsure if 
> all of them should be mirrored in Org mode.

They are already mirrored. Mostly. Consider the same Org file opened by
different users with `org-man-command' set to 'man and 'woman.

> Frankly speaking, I am unsure if woman should be supported in Org at 
> all. My early experience with woman.el was not nice. I tried M-x woman 
> RET ssh RET (openssh).

woman is not trying to be complete. See [[info:woman#Introduction]].

For Org support, we already support it, and it would be a feature
regression if we remove it.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Max Nikulin]

On 05/10/2023 19:48, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>> Frankly speaking, I am unsure if woman should be supported in Org at
>> all. My early experience with woman.el was not nice. I tried M-x woman
>> RET ssh RET (openssh).
> 
> woman is not trying to be complete. See [[info:woman#Introduction]].
> 
> For Org support, we already support it, and it would be a feature
> regression if we remove it.

World has changed since woman.el was developed. Are there systems with 
man pages available, but no man command nowadays? Android with man pages 
copied by its user?

I see a little value in a tool that can not handle a wide spread case 
when a better one is available. Features, that were unique for woman, 
have been implemented for man.

In WoMan I have not found a way to open <man:man(7)> directly without an 
additional prompt for the page section.

man.el has a lot of options how to select window for a man page. It is 
not the case for woman. For Org internal link types same/other window is 
controlled by prefix argument (however `org-open-at-point' doc string 
describes another meaning of prefix argument: if link should be opened 
in Emacs or an external application). I am unsure what is proper 
behavior of man links opened from Org, should Org try to make behavior 
consistent or it should let packages to act as they wish.

Re: Completion of links to man pages

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> On 05/10/2023 19:48, Ihor Radchenko wrote:
>> Max Nikulin writes:
>> 
>>> Frankly speaking, I am unsure if woman should be supported in Org at
>>> all. My early experience with woman.el was not nice. I tried M-x woman
>>> RET ssh RET (openssh).
>> 
>> woman is not trying to be complete. See [[info:woman#Introduction]].
>> 
>> For Org support, we already support it, and it would be a feature
>> regression if we remove it.
>
> World has changed since woman.el was developed. Are there systems with 
> man pages available, but no man command nowadays? Android with man pages 
> copied by its user?

MS-DOS, for example. Or old Windows versions. Emacs can work on many
systems and there is no reason to avoid supporting more OSes when we do
not have to.

> I see a little value in a tool that can not handle a wide spread case 
> when a better one is available. Features, that were unique for woman, 
> have been implemented for man.

Which is why `org-man-command' is set to 'man by default.

> In WoMan I have not found a way to open <man:man(7)> directly without an 
> additional prompt for the page section.

> man.el has a lot of options how to select window for a man page. It is 
> not the case for woman.
> ... For Org internal link types same/other window is 
> controlled by prefix argument (however `org-open-at-point' doc string 
> describes another meaning of prefix argument: if link should be opened 
> in Emacs or an external application). I am unsure what is proper 
> behavior of man links opened from Org, should Org try to make behavior 
> consistent or it should let packages to act as they wish.

These two sound like feature requests for WoMan. These features might also
benefit Org, if implemented.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-orgmode@gnu.org, emacs-devel@gnu.org
> Date: Thu, 05 Oct 2023 16:15:07 +0000
> 
> Max Nikulin <manikulin@gmail.com> writes:
> 
> > World has changed since woman.el was developed. Are there systems with 
> > man pages available, but no man command nowadays? Android with man pages 
> > copied by its user?
> 
> MS-DOS, for example.

What we here call "MNS-DOS" (which is actually the DJGPP development
environment used to compile the MS-DOS build of Emacs) does have the
man command:

  http://www.delorie.com/pub/djgpp/current/v2apps/man13br2.zip

> Or old Windows versions.

The Windows port of the above is available from the ezwinports site.

> > In WoMan I have not found a way to open <man:man(7)> directly without an 
> > additional prompt for the page section.
> 
> > man.el has a lot of options how to select window for a man page. It is 
> > not the case for woman.
> > ... For Org internal link types same/other window is 
> > controlled by prefix argument (however `org-open-at-point' doc string 
> > describes another meaning of prefix argument: if link should be opened 
> > in Emacs or an external application). I am unsure what is proper 
> > behavior of man links opened from Org, should Org try to make behavior 
> > consistent or it should let packages to act as they wish.
> 
> These two sound like feature requests for WoMan. These features might also
> benefit Org, if implemented.

I don't think woman.el is being developed, or is it?

Re: Completion of links to man pages

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Ihor Radchenko <yantar92@posteo.net>
>> Cc: emacs-orgmode@gnu.org, emacs-devel@gnu.org
>> Date: Thu, 05 Oct 2023 16:15:07 +0000
>> 
>> Max Nikulin <manikulin@gmail.com> writes:
>> 
>> > World has changed since woman.el was developed. Are there systems with 
>> > man pages available, but no man command nowadays? Android with man pages 
>> > copied by its user?
> ...
> What we here call "MNS-DOS" (which is actually the DJGPP development
> environment used to compile the MS-DOS build of Emacs) does have the
> man command:
>
>   http://www.delorie.com/pub/djgpp/current/v2apps/man13br2.zip
> ...
> The Windows port of the above is available from the ezwinports site.

> ...
> I don't think woman.el is being developed, or is it?

Do you mean that woman.el will be obsoleted?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: manikulin@gmail.com, emacs-orgmode@gnu.org, emacs-devel@gnu.org
> Date: Thu, 05 Oct 2023 16:55:02 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Ihor Radchenko <yantar92@posteo.net>
> >> Cc: emacs-orgmode@gnu.org, emacs-devel@gnu.org
> >> Date: Thu, 05 Oct 2023 16:15:07 +0000
> >> 
> >> Max Nikulin <manikulin@gmail.com> writes:
> >> 
> >> > World has changed since woman.el was developed. Are there systems with 
> >> > man pages available, but no man command nowadays? Android with man pages 
> >> > copied by its user?
> > ...
> > What we here call "MNS-DOS" (which is actually the DJGPP development
> > environment used to compile the MS-DOS build of Emacs) does have the
> > man command:
> >
> >   http://www.delorie.com/pub/djgpp/current/v2apps/man13br2.zip
> > ...
> > The Windows port of the above is available from the ezwinports site.
> 
> > ...
> > I don't think woman.el is being developed, or is it?
> 
> Do you mean that woman.el will be obsoleted?

AFAIU, it already is, de-facto.  Unless someone steps forward and
volunteers to develop woman.el so as to add all the many missing
features that Groff has added during the last years, woman.el will
continue to bitrot.

Re: Completion of links to man pages

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Do you mean that woman.el will be obsoleted?
>
> AFAIU, it already is, de-facto.  Unless someone steps forward and
> volunteers to develop woman.el so as to add all the many missing
> features that Groff has added during the last years, woman.el will
> continue to bitrot.

Good to know. Then, I do not see much point adding woman support in the
discussed ol-man patch.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Max Nikulin]

On 06/10/2023 00:13, Eli Zaretskii wrote:
>> From: Ihor Radchenko
>> Do you mean that woman.el will be obsoleted?
> 
> AFAIU, it already is, de-facto.  Unless someone steps forward and
> volunteers to develop woman.el so as to add all the many missing
> features that Groff has added during the last years, woman.el will
> continue to bitrot.

It seems, I was not the only person who had an impression that `woman' 
is the Emacs way to read man pages. I have no idea concerning its 
origin, perhaps some pages and comments I had seen on the net.

I have realized that namely `man' is recommended:
(info "(emacs) Man Page")
> Note that M-x woman doesn’t yet support the latest features of modern
> man pages, so we recommend using M-x man if that is available on your
> system.

Absence of an active hyperlink to WoMan manual at
https://www.gnu.org/software/emacs/manual/html_node/emacs/Man-Page.html
might be considered as a means to discourage its usage.

Re: Completion of links to man pages

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It seems, I was not the only person who had an impression that `woman' 
  > is the Emacs way to read man pages. I have no idea concerning its 
  > origin, perhaps some pages and comments I had seen on the net.

This suggests that running M-x woman should display a message saying to
use M-x man instead.

The message could add this

   The name M-x man refers to the old Unix command `man', which is
   short for "manual".  Its purpose is to read pages of the manual.
   Mx- woman was a joke based on that name.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Completion of links to man pages

[Max Nikulin]

On 07/10/2023 04:37, Richard Stallman wrote:
> This suggests that running M-x woman should display a message saying to 
> use M-x man instead.

In my opinion it would be annoying for those who rely on WoMan (if they 
exist). Description of `man' and `woman' is well balanced in (info 
"emacs"), but other docs may be improved.

- `man' and `woman' doc string may say that namely `man' is recommended, 
however if the "man" command is unavailable on a particular platform 
then they may try `woman'.
- (info "woman") and woman.el package comments should recommend `man' 
and may contain a call for developers to improve parsing in WoMan and 
perhaps to share more code and settings with man.el to get more 
consistent behavior. Some features of WoMan described as its advantage 
have been implemented in man.el since that time.

Re: Completion of links to man pages

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

Hi,

>> > I don't think woman.el is being developed, or is it?
>>
>> Do you mean that woman.el will be obsoleted?
>
> AFAIU, it already is, de-facto.  Unless someone steps forward and
> volunteers to develop woman.el so as to add all the many missing
> features that Groff has added during the last years, woman.el will
> continue to bitrot.

In my long-term TODO there is adding support for man pages on remote
hosts. This is counted for man.el, no plans for woman.el. See discussion
at bug#46911. (Unfortunately, no progress yet).

Just a data point.

Best regards, Michael.

Re: Completion of links to man pages

[Max Nikulin]

On 05/10/2023 23:15, Ihor Radchenko wrote:
> Max Nikulin writes:
>> World has changed since woman.el was developed. Are there systems with
>> man pages available, but no man command nowadays? Android with man pages
>> copied by its user?
> 
> MS-DOS, for example. Or old Windows versions. Emacs can work on many
> systems and there is no reason to avoid supporting more OSes when we do
> not have to.

I am curious if users running Org mode on MS-DOS or Windows and reading 
man pages using WoMan exist. I mentioned Android since it may be handy 
to have man pages in your pocket. However being on-line (in its modern 
meaning, not when man pages appeared), it might be more convenient to 
use https://manpages.debian.org/ https://man.archlinux.org/man/ due much 
better heuristics for cross-references than used in man.el.

Re: Completion of links to man pages

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-orgmode@gnu.org, emacs-devel@gnu.org
> Date: Thu, 05 Oct 2023 11:40:44 +0000
> 
> To emacs-devel: Would it be of interest to expose man/woman completion
> API?

How is it different from the "M-x man" completion we already have?

Re: Completion of links to man pages

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> To emacs-devel: Would it be of interest to expose man/woman completion
>> API?
>
> How is it different from the "M-x man" completion we already have?

M-x man will display the man page, while we just need `completing-read'
from the same source M-x man or M-x woman use.

The use-case is when users want to create an Org link to man page.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: manikulin@gmail.com, emacs-orgmode@gnu.org, emacs-devel@gnu.org
> Date: Thu, 05 Oct 2023 16:05:02 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> To emacs-devel: Would it be of interest to expose man/woman completion
> >> API?
> >
> > How is it different from the "M-x man" completion we already have?
> 
> M-x man will display the man page, while we just need `completing-read'
> from the same source M-x man or M-x woman use.

Sorry, I don't understand: "M-x man" does provide completion.

And what do you mean by "`completing-read' from the same source M-x
man or M-x woman use"?

IOW, I think I have no clue of what are you trying to accomplish,
sorry.

Re: Completion of links to man pages

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> > How is it different from the "M-x man" completion we already have?
>> 
>> M-x man will display the man page, while we just need `completing-read'
>> from the same source M-x man or M-x woman use.
>
> Sorry, I don't understand: "M-x man" does provide completion.

Yes, but one cannot replicate the same completion dialogue
programmatically in future-compatible way.

> And what do you mean by "`completing-read' from the same source M-x
> man or M-x woman use"?
>
> IOW, I think I have no clue of what are you trying to accomplish,
> sorry.

We aim to create Org links like [[man:ls]].
To create a link in Org, the interface is C-c C-l (org-insert-link),
which then prompts for link type (man:) and link path (ls).
When querying for the path, we want to have the same completion
COLLECTION as M-x man/woman has.

For now, as you can see in the quoted code from my initial message, we
have to partially replicate the code from man.el and woman.el:

(defun org-man--complete-man (prompt)
   (require 'man)
   (let (Man-completion-cache) ;; <- implementation detail in man.el
     (completing-read
      prompt
      'Man-completion-table)))

(defun org-man--init-woman-cache (&optional re-cache) ;; <- implementation detail in woman.el
   (unless (and (not re-cache)
		(or
		 (and woman-expanded-directory-path
		      woman-topic-all-completions)
		 (woman-read-directory-cache)))
     (setq woman-expanded-directory-path
	   (woman-expand-directory-path woman-manpath woman-path))
     (setq woman-totic-all-completions
	   (woman-topic-all-completions woman-expand-directory-path))
     (woman-write-directory-cache)))

(defun org-man--complete-woman (prompt)
   (require 'woman)
   (org-man--init-woman-cache)
   (completing-read prompt woman-topic-all-completions))

However, `Man-completion-table' is not documented (no docstring),
`woman-topic-all-completions' is tricky to use - we have to copy-paste
cache initialization code and later make sure that we keep things up to
date to upstream.

What I am asking here is to provide a stable Elisp API for the above use
case. Currently, we have to rely on implementation details.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: manikulin@gmail.com, emacs-orgmode@gnu.org, emacs-devel@gnu.org
> Date: Thu, 05 Oct 2023 16:53:57 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> > How is it different from the "M-x man" completion we already have?
> >> 
> >> M-x man will display the man page, while we just need `completing-read'
> >> from the same source M-x man or M-x woman use.
> >
> > Sorry, I don't understand: "M-x man" does provide completion.
> 
> Yes, but one cannot replicate the same completion dialogue
> programmatically in future-compatible way.

What do you mean by that?  "M-x man" does this:

  (interactive
   (list (let* ((default-entry (Man-default-man-entry))
		;; ignore case because that's friendly for bizarre
		;; caps things like the X11 function names and because
		;; "man" itself is case-insensitive on the command line
		;; so you're accustomed not to bother about the case
		;; ("man -k" is case-insensitive similarly, so the
		;; table has everything available to complete)
		(completion-ignore-case t)
		Man-completion-cache    ;Don't cache across calls.
		(input (completing-read
			(format-prompt "Manual entry"
                                       (and (not (equal default-entry ""))
                                            default-entry))
                        'Man-completion-table
			nil nil nil 'Man-topic-history default-entry)))

This uses completing-read, as I think you wanted.

> > And what do you mean by "`completing-read' from the same source M-x
> > man or M-x woman use"?
> >
> > IOW, I think I have no clue of what are you trying to accomplish,
> > sorry.
> 
> We aim to create Org links like [[man:ls]].
> To create a link in Org, the interface is C-c C-l (org-insert-link),
> which then prompts for link type (man:) and link path (ls).
> When querying for the path, we want to have the same completion
> COLLECTION as M-x man/woman has.

Why cannot you reuse Man-completion-table?

> For now, as you can see in the quoted code from my initial message, we
> have to partially replicate the code from man.el and woman.el:
> 
> (defun org-man--complete-man (prompt)
>    (require 'man)
>    (let (Man-completion-cache) ;; <- implementation detail in man.el
>      (completing-read
>       prompt
>       'Man-completion-table)))

And why is that a problem?

> However, `Man-completion-table' is not documented (no docstring),

If the only thing that's missing is its doc string, that is easy to
add.

> What I am asking here is to provide a stable Elisp API for the above use
> case. Currently, we have to rely on implementation details.

From where I stand, we have already a stable API tested by years of
use.  What is maybe missing is some documentation to allow its easier
use, that's all.

Re: Completion of links to man pages

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Yes, but one cannot replicate the same completion dialogue
>> programmatically in future-compatible way.
>
> What do you mean by that?  "M-x man" does this:
>
>   (interactive
>    (list (let* ((default-entry (Man-default-man-entry))
> 		;; ignore case because that's friendly for bizarre
> 		;; caps things like the X11 function names and because
> 		;; "man" itself is case-insensitive on the command line
> 		;; so you're accustomed not to bother about the case
> 		;; ("man -k" is case-insensitive similarly, so the
> 		;; table has everything available to complete)
> 		(completion-ignore-case t)
> 		Man-completion-cache    ;Don't cache across calls.
> 		(input (completing-read
> 			(format-prompt "Manual entry"
>                                        (and (not (equal default-entry ""))
>                                             default-entry))
>                         'Man-completion-table
> 			nil nil nil 'Man-topic-history default-entry)))
>
> This uses completing-read, as I think you wanted.
> ...
> Why cannot you reuse Man-completion-table?
>
>> For now, as you can see in the quoted code from my initial message, we
>> have to partially replicate the code from man.el and woman.el:
>> 
>> (defun org-man--complete-man (prompt)
>>    (require 'man)
>>    (let (Man-completion-cache) ;; <- implementation detail in man.el
>>      (completing-read
>>       prompt
>>       'Man-completion-table)))
>
> And why is that a problem?

Because we also need to bind (completion-ignore-case t) and
(Man-completion-cache nil). Ideally, these details should not be
something we need to know. It would be better if man.el provided some
kind of API function like `man-completing-read' that takes care about
these details, which are apparently necessary to avoid bug#13160 and
bug#3717.

>> However, `Man-completion-table' is not documented (no docstring),
>
> If the only thing that's missing is its doc string, that is easy to
> add.

Docstring would certainly help. Otherwise, we have to guess what that
function does.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Completion of links to man pages

[Max Nikulin]

On 06/10/2023 00:11, Eli Zaretskii wrote:
>  From where I stand, we have already a stable API tested by years of
> use.  What is maybe missing is some documentation to allow its easier
> use, that's all.

In some cases it is no API but just an interactive command. Sometimes it 
can be used from other code, sometimes it requires to copy-paste enough 
implementation details to achieve a similar effect.

While man.el requires "just" resetting cache and disabling case 
sensitivity, woman.el needs to initialize cache before invoking a 
completion function. When woman.el is considered in isolation, it is not 
an issue that `woman-file-name' is not decomposed into smaller functions 
since there is no need to reuse parts of its code. However it becomes an 
obstacle when another package tries to interact with woman.

Side note: I am afraid of behavior divergence for `man' and 
`org-insert-link' in future, but I have not figured out what API I would 
expect.

Re: Completion of links to man pages

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> I am unsure if the code below is appropriate for :complete property of 
> "man" link. It does not rely on any double-dash functions or variables, 
> but it still uses some implementation details since there is no suitable 
> high level functions in man.el and woman.el from Emacs.
>
> (defun org-man-complete (&optional _arg)
>    "Helper for completion of links to man pages."
>    (concat
>     "man:"
>     (let ((completion-ignore-case t)) ; See `man' comments.
>       (funcall
>        (if (eq org-man-command 'woman)
>            #'org-man--complete-woman
>          #'org-man--complete-man)
>        "Manual entry: "))))
>
> (defun org-man--complete-man (prompt)
>    (require 'man)
>    (let (Man-completion-cache)
>      (completing-read
>       prompt
>       'Man-completion-table)))
> ...

Considering that the discussion on emacs-devel concluded that woman is
obsolete, that no interest has been shown in introducing a stable
completion API, and that the "man" part of the above code is reasonably
simple, I think that the above two functions would be an OK addition to
ol-man (with woman part of `org-man-complete' removed).

Max, may you convert this into a patch?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

[PATCH] ol-man.el: Enable completion

[Max Nikulin]

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

On 09/12/2023 18:32, Ihor Radchenko wrote:
> Considering that the discussion on emacs-devel concluded that woman is
> obsolete, that no interest has been shown in introducing a stable
> completion API, and that the "man" part of the above code is reasonably
> simple, I think that the above two functions would be an OK addition to
> ol-man (with woman part of `org-man-complete' removed).
> 
> Max, may you convert this into a patch?

See attachments

[-- Attachment #2: 0001-ol-man.el-Enable-completion.patch --]
[-- Type: text/x-patch, Size: 2111 bytes --]

From d52265f6242b21561d5f96ae94afb1da37af1ce3 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Mon, 9 Oct 2023 18:47:04 +0700
Subject: [PATCH 1/2] ol-man.el: Enable completion

* lisp/ol-man.el (org-man-complete): New function implementing
completion for man pages using `Man-completion-table'.  Set this
function as the `:complete' property of "man" links.

Ihor Radchenko. Re: Completion of links to man pages.
Sat, 09 Dec 2023 11:32:39 +0000.
<https://list.orgmode.org/877clnsjag.fsf@localhost>
---
 etc/ORG-NEWS   |  6 ++++++
 lisp/ol-man.el | 12 ++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 9858df045..6c81221c1 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -729,6 +729,12 @@ respected.
 Images dropped also respect the value of ~org-yank-image-save-method~
 when ~org-yank-dnd-method~ is =attach=.
 
+*** Add completion for links to man pages
+
+Completion is enabled for links to man pages added using ~org-insert-link~:
+=C-c C-l man RET emacscl TAB= to get =emacsclient=.  Of course, the ~ol-man~
+library should be loaded first.
+
 ** New functions and changes in function arguments
 *** ~org-fold-hide-drawer-all~ is now interactive
 
diff --git a/lisp/ol-man.el b/lisp/ol-man.el
index b0701c689..f5533c5a5 100644
--- a/lisp/ol-man.el
+++ b/lisp/ol-man.el
@@ -34,6 +34,7 @@ (org-assert-version)
 (require 'ol)
 
 (org-link-set-parameters "man"
+                         :complete #'org-man-complete
 			 :follow #'org-man-open
 			 :export #'org-man-export
 			 :store #'org-man-store-link)
@@ -99,6 +100,17 @@ (defun org-man-export (link description backend)
      ((eq backend 'md) (format "[%s](%s)" desc path))
      (t path))))
 
+(defun org-man-complete (&optional _arg)
+  "Complete man pages for `org-insert-link'."
+  (require 'man)
+  (concat
+   "man:"
+   (let ((completion-ignore-case t) ; See `man' comments.
+         (Man-completion-cache)) ; See `man' implementation.
+     (completing-read
+      "Manual entry: "
+      'Man-completion-table))))
+
 (provide 'ol-man)
 
 ;;; ol-man.el ends here
-- 
2.39.2


[-- Attachment #3: 0002-ol-man.el-Mark-WoMan-link-handler-as-obsolete.patch --]
[-- Type: text/x-patch, Size: 1055 bytes --]

From d7ea42febd19825622c9779e197c37c4d9fd0435 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Wed, 13 Dec 2023 22:03:36 +0700
Subject: [PATCH 2/2] ol-man.el: Mark WoMan link handler as obsolete

lisp/ol-man.el (org-man-command): Add label suggesting against
the WoMan package as a viewer for man pages.  It has enough bugs.

Eli Zaretskii to emacs-orgmode. Re: Completion of links to man pages.
Thu, 05 Oct 2023 19:33:26 +0300.
<https://list.orgmode.org/orgmode/83sf6p2fgu.fsf@gnu.org>
---
 lisp/ol-man.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/ol-man.el b/lisp/ol-man.el
index f5533c5a5..633280942 100644
--- a/lisp/ol-man.el
+++ b/lisp/ol-man.el
@@ -42,7 +42,7 @@ (org-link-set-parameters "man"
 (defcustom org-man-command 'man
   "The Emacs command to be used to display a man page."
   :group 'org-link
-  :type '(choice (const man) (const woman)))
+  :type '(choice (const man) (const :tag "WoMan (obsolete)" woman)))
 
 (defun org-man-open (path _)
   "Visit the manpage on PATH.
-- 
2.39.2

Re: [PATCH] ol-man.el: Enable completion

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> Max, may you convert this into a patch?
>
> See attachments

Thanks!
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=7c9a5216b
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b8d27bb4e

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>