* Completion of links to man pages
@ 2023-10-04 11:40 Max Nikulin
2023-10-05 11:40 ` Ihor Radchenko
2023-12-09 11:32 ` Ihor Radchenko
0 siblings, 2 replies; 23+ messages in thread
From: Max Nikulin @ 2023-10-04 11:40 UTC (permalink / raw)
To: emacs-orgmode
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))
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: Completion of links to man pages 2023-10-04 11:40 Completion of links to man pages Max Nikulin @ 2023-10-05 11:40 ` Ihor Radchenko 2023-10-05 12:20 ` Max Nikulin 2023-10-05 15:52 ` Eli Zaretskii 2023-12-09 11:32 ` Ihor Radchenko 1 sibling, 2 replies; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 11:40 UTC (permalink / raw) To: Max Nikulin; +Cc: emacs-orgmode, emacs-devel [ 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 11:40 ` Ihor Radchenko @ 2023-10-05 12:20 ` Max Nikulin 2023-10-05 12:48 ` Ihor Radchenko 2023-10-05 15:52 ` Eli Zaretskii 1 sibling, 1 reply; 23+ messages in thread From: Max Nikulin @ 2023-10-05 12:20 UTC (permalink / raw) To: emacs-orgmode; +Cc: emacs-devel 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). ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 12:20 ` Max Nikulin @ 2023-10-05 12:48 ` Ihor Radchenko 2023-10-05 15:59 ` Max Nikulin 0 siblings, 1 reply; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 12:48 UTC (permalink / raw) To: Max Nikulin; +Cc: emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 12:48 ` Ihor Radchenko @ 2023-10-05 15:59 ` Max Nikulin 2023-10-05 16:15 ` Ihor Radchenko 0 siblings, 1 reply; 23+ messages in thread From: Max Nikulin @ 2023-10-05 15:59 UTC (permalink / raw) To: emacs-orgmode; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 15:59 ` Max Nikulin @ 2023-10-05 16:15 ` Ihor Radchenko 2023-10-05 16:37 ` Eli Zaretskii 2023-10-06 3:58 ` Max Nikulin 0 siblings, 2 replies; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 16:15 UTC (permalink / raw) To: Max Nikulin; +Cc: emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:15 ` Ihor Radchenko @ 2023-10-05 16:37 ` Eli Zaretskii 2023-10-05 16:55 ` Ihor Radchenko 2023-10-06 3:58 ` Max Nikulin 1 sibling, 1 reply; 23+ messages in thread From: Eli Zaretskii @ 2023-10-05 16:37 UTC (permalink / raw) To: Ihor Radchenko; +Cc: manikulin, emacs-orgmode, emacs-devel > 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? ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:37 ` Eli Zaretskii @ 2023-10-05 16:55 ` Ihor Radchenko 2023-10-05 17:13 ` Eli Zaretskii 0 siblings, 1 reply; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 16:55 UTC (permalink / raw) To: Eli Zaretskii; +Cc: manikulin, emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:55 ` Ihor Radchenko @ 2023-10-05 17:13 ` Eli Zaretskii 2023-10-05 17:30 ` Ihor Radchenko ` (2 more replies) 0 siblings, 3 replies; 23+ messages in thread From: Eli Zaretskii @ 2023-10-05 17:13 UTC (permalink / raw) To: Ihor Radchenko; +Cc: manikulin, emacs-orgmode, emacs-devel > 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 17:13 ` Eli Zaretskii @ 2023-10-05 17:30 ` Ihor Radchenko [not found] ` <ufnvit$12ho$1@ciao.gmane.io> 2023-10-07 11:14 ` Michael Albinus 2 siblings, 0 replies; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 17:30 UTC (permalink / raw) To: Eli Zaretskii; +Cc: manikulin, emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
[parent not found: <ufnvit$12ho$1@ciao.gmane.io>]
* Re: Completion of links to man pages [not found] ` <ufnvit$12ho$1@ciao.gmane.io> @ 2023-10-06 21:37 ` Richard Stallman 0 siblings, 0 replies; 23+ messages in thread From: Richard Stallman @ 2023-10-06 21:37 UTC (permalink / raw) To: Max Nikulin; +Cc: emacs-devel, emacs-orgmode [[[ 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) ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 17:13 ` Eli Zaretskii 2023-10-05 17:30 ` Ihor Radchenko [not found] ` <ufnvit$12ho$1@ciao.gmane.io> @ 2023-10-07 11:14 ` Michael Albinus 2 siblings, 0 replies; 23+ messages in thread From: Michael Albinus @ 2023-10-07 11:14 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Ihor Radchenko, manikulin, emacs-orgmode, emacs-devel 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:15 ` Ihor Radchenko 2023-10-05 16:37 ` Eli Zaretskii @ 2023-10-06 3:58 ` Max Nikulin 1 sibling, 0 replies; 23+ messages in thread From: Max Nikulin @ 2023-10-06 3:58 UTC (permalink / raw) To: emacs-orgmode; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 11:40 ` Ihor Radchenko 2023-10-05 12:20 ` Max Nikulin @ 2023-10-05 15:52 ` Eli Zaretskii 2023-10-05 16:05 ` Ihor Radchenko 1 sibling, 1 reply; 23+ messages in thread From: Eli Zaretskii @ 2023-10-05 15:52 UTC (permalink / raw) To: Ihor Radchenko; +Cc: manikulin, emacs-orgmode, emacs-devel > 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? ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 15:52 ` Eli Zaretskii @ 2023-10-05 16:05 ` Ihor Radchenko 2023-10-05 16:33 ` Eli Zaretskii 0 siblings, 1 reply; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 16:05 UTC (permalink / raw) To: Eli Zaretskii; +Cc: manikulin, emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:05 ` Ihor Radchenko @ 2023-10-05 16:33 ` Eli Zaretskii 2023-10-05 16:53 ` Ihor Radchenko 0 siblings, 1 reply; 23+ messages in thread From: Eli Zaretskii @ 2023-10-05 16:33 UTC (permalink / raw) To: Ihor Radchenko; +Cc: manikulin, emacs-orgmode, emacs-devel > 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:33 ` Eli Zaretskii @ 2023-10-05 16:53 ` Ihor Radchenko 2023-10-05 17:11 ` Eli Zaretskii 0 siblings, 1 reply; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 16:53 UTC (permalink / raw) To: Eli Zaretskii; +Cc: manikulin, emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 16:53 ` Ihor Radchenko @ 2023-10-05 17:11 ` Eli Zaretskii 2023-10-05 17:36 ` Ihor Radchenko 2023-10-06 3:16 ` Max Nikulin 0 siblings, 2 replies; 23+ messages in thread From: Eli Zaretskii @ 2023-10-05 17:11 UTC (permalink / raw) To: Ihor Radchenko; +Cc: manikulin, emacs-orgmode, emacs-devel > 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 17:11 ` Eli Zaretskii @ 2023-10-05 17:36 ` Ihor Radchenko 2023-10-06 3:16 ` Max Nikulin 1 sibling, 0 replies; 23+ messages in thread From: Ihor Radchenko @ 2023-10-05 17:36 UTC (permalink / raw) To: Eli Zaretskii; +Cc: manikulin, emacs-orgmode, emacs-devel 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-05 17:11 ` Eli Zaretskii 2023-10-05 17:36 ` Ihor Radchenko @ 2023-10-06 3:16 ` Max Nikulin 1 sibling, 0 replies; 23+ messages in thread From: Max Nikulin @ 2023-10-06 3:16 UTC (permalink / raw) To: emacs-orgmode; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: Completion of links to man pages 2023-10-04 11:40 Completion of links to man pages Max Nikulin 2023-10-05 11:40 ` Ihor Radchenko @ 2023-12-09 11:32 ` Ihor Radchenko 2023-12-13 15:20 ` [PATCH] ol-man.el: Enable completion Max Nikulin 1 sibling, 1 reply; 23+ messages in thread From: Ihor Radchenko @ 2023-12-09 11:32 UTC (permalink / raw) To: Max Nikulin; +Cc: emacs-orgmode 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH] ol-man.el: Enable completion 2023-12-09 11:32 ` Ihor Radchenko @ 2023-12-13 15:20 ` Max Nikulin 2023-12-14 15:09 ` Ihor Radchenko 0 siblings, 1 reply; 23+ messages in thread From: Max Nikulin @ 2023-12-13 15:20 UTC (permalink / raw) To: emacs-orgmode [-- 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 ^ permalink raw reply related [flat|nested] 23+ messages in thread
* Re: [PATCH] ol-man.el: Enable completion 2023-12-13 15:20 ` [PATCH] ol-man.el: Enable completion Max Nikulin @ 2023-12-14 15:09 ` Ihor Radchenko 0 siblings, 0 replies; 23+ messages in thread From: Ihor Radchenko @ 2023-12-14 15:09 UTC (permalink / raw) To: Max Nikulin; +Cc: emacs-orgmode 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> ^ permalink raw reply [flat|nested] 23+ messages in thread
end of thread, other threads:[~2023-12-14 15:07 UTC | newest]
Thread overview: 23+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-10-04 11:40 Completion of links to man pages Max Nikulin
2023-10-05 11:40 ` Ihor Radchenko
2023-10-05 12:20 ` Max Nikulin
2023-10-05 12:48 ` Ihor Radchenko
2023-10-05 15:59 ` Max Nikulin
2023-10-05 16:15 ` Ihor Radchenko
2023-10-05 16:37 ` Eli Zaretskii
2023-10-05 16:55 ` Ihor Radchenko
2023-10-05 17:13 ` Eli Zaretskii
2023-10-05 17:30 ` Ihor Radchenko
[not found] ` <ufnvit$12ho$1@ciao.gmane.io>
2023-10-06 21:37 ` Richard Stallman
2023-10-07 11:14 ` Michael Albinus
2023-10-06 3:58 ` Max Nikulin
2023-10-05 15:52 ` Eli Zaretskii
2023-10-05 16:05 ` Ihor Radchenko
2023-10-05 16:33 ` Eli Zaretskii
2023-10-05 16:53 ` Ihor Radchenko
2023-10-05 17:11 ` Eli Zaretskii
2023-10-05 17:36 ` Ihor Radchenko
2023-10-06 3:16 ` Max Nikulin
2023-12-09 11:32 ` Ihor Radchenko
2023-12-13 15:20 ` [PATCH] ol-man.el: Enable completion Max Nikulin
2023-12-14 15:09 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).