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>