* bug#39215: Hyperlinks to man pages in doc strings
@ 2020-01-21 8:55 Stefan Kangas
2020-01-21 15:36 ` Eli Zaretskii
0 siblings, 1 reply; 14+ messages in thread
From: Stefan Kangas @ 2020-01-21 8:55 UTC (permalink / raw)
To: 39215
Severity: wishlist
Please add the possibility to write in doc strings:
man page `find'
and have it automatically converted into a hyperlink which will open
up M-x man and visit the specified man page.
The proposed feature complements the already existing functionality
with hyperlinks to info pages.[1]
For an example of where this would be useful, please see the doc
string of `dired-do-chmod'.
Best regards,
Stefan Kangas
Footnotes:
[1] See (info "(elisp)Documentation Tips")
^ permalink raw reply [flat|nested] 14+ messages in thread* bug#39215: Hyperlinks to man pages in doc strings 2020-01-21 8:55 bug#39215: Hyperlinks to man pages in doc strings Stefan Kangas @ 2020-01-21 15:36 ` Eli Zaretskii 2020-01-21 16:32 ` Stefan Kangas 0 siblings, 1 reply; 14+ messages in thread From: Eli Zaretskii @ 2020-01-21 15:36 UTC (permalink / raw) To: Stefan Kangas; +Cc: 39215 > From: Stefan Kangas <stefan@marxist.se> > Date: Tue, 21 Jan 2020 09:55:42 +0100 > > Severity: wishlist > > Please add the possibility to write in doc strings: > > man page `find' > > and have it automatically converted into a hyperlink which will open > up M-x man and visit the specified man page. 'find' has an Info manual: find.info. Why not use a hyperlink to that instead, something we already support? Many utilities have similar Info manuals, and the glibc has an Info manual as well. > The proposed feature complements the already existing functionality > with hyperlinks to info pages.[1] Nitpicking: let's not call Info manuals "pages". They are not like "man pages", which are a collection of short concise usage descriptions. ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-21 15:36 ` Eli Zaretskii @ 2020-01-21 16:32 ` Stefan Kangas 2020-01-21 16:56 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Stefan Kangas @ 2020-01-21 16:32 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 39215 Eli Zaretskii <eliz@gnu.org> writes: > 'find' has an Info manual: find.info. Why not use a hyperlink to that > instead, something we already support? Many utilities have similar > Info manuals, and the glibc has an Info manual as well. I was looking for something which would work also with BSD find (or indeed any find not from GNU findutils). My idea was to specify both. But that's just one example. Most non-GNU software don't use texinfo. They often have man pages. It would be useful to be able to add links to them. > Nitpicking: let's not call Info manuals "pages". They are not like > "man pages", which are a collection of short concise usage > descriptions. Sure, I'll try to remember to say "info manuals" in our documentation and sources. (FWIW, I think getting people to stop using that vocabulary is going to be an uphill battle, since it is so ubiquitous. We even use this nomenclature in some places in Emacs itself. Try grepping for "info pages" in our sources.) Best regards, Stefan Kangas ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-21 16:32 ` Stefan Kangas @ 2020-01-21 16:56 ` Eli Zaretskii 2020-01-22 4:03 ` Glenn Morris 2020-01-23 1:39 ` Richard Stallman 0 siblings, 2 replies; 14+ messages in thread From: Eli Zaretskii @ 2020-01-21 16:56 UTC (permalink / raw) To: Stefan Kangas; +Cc: 39215 > From: Stefan Kangas <stefan@marxist.se> > Date: Tue, 21 Jan 2020 17:32:35 +0100 > Cc: 39215@debbugs.gnu.org > > Eli Zaretskii <eliz@gnu.org> writes: > > > 'find' has an Info manual: find.info. Why not use a hyperlink to that > > instead, something we already support? Many utilities have similar > > Info manuals, and the glibc has an Info manual as well. > > I was looking for something which would work also with BSD find (or > indeed any find not from GNU findutils). My idea was to specify both. Why should we cater so much to non-GNU systems? The users of BSD can install the Info manual as well, can they not? > But that's just one example. Most non-GNU software don't use texinfo. > They often have man pages. It would be useful to be able to add links > to them. Maybe we should teach info.el to display man pages. The stand-alone Info reader that is part of the Texinfo package does that since time immemoriam. > Try grepping for "info pages" in our sources. Those places should be corrected. ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-21 16:56 ` Eli Zaretskii @ 2020-01-22 4:03 ` Glenn Morris 2020-01-22 15:45 ` Eli Zaretskii 2020-01-23 1:39 ` Richard Stallman 1 sibling, 1 reply; 14+ messages in thread From: Glenn Morris @ 2020-01-22 4:03 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Stefan Kangas, 39215 Eli Zaretskii wrote: > Maybe we should teach info.el to display man pages. The stand-alone > Info reader that is part of the Texinfo package does that since time > immemoriam. (This seems unrelated to the, IMO totally reasonable, feature request.) The info reader does a worse job of rendering man pages than the 'man' program does. I hope Emacs doesn't implement a second (on top of M-x woman) partial replacement for the man program, when one can just use M-x man. ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-22 4:03 ` Glenn Morris @ 2020-01-22 15:45 ` Eli Zaretskii 0 siblings, 0 replies; 14+ messages in thread From: Eli Zaretskii @ 2020-01-22 15:45 UTC (permalink / raw) To: Glenn Morris; +Cc: stefan, 39215 > From: Glenn Morris <rgm@gnu.org> > Cc: Stefan Kangas <stefan@marxist.se>, 39215@debbugs.gnu.org > Date: Tue, 21 Jan 2020 23:03:01 -0500 > > Eli Zaretskii wrote: > > > Maybe we should teach info.el to display man pages. The stand-alone > > Info reader that is part of the Texinfo package does that since time > > immemoriam. > > (This seems unrelated to the, IMO totally reasonable, feature request.) My reasoning was that if info.el could do that, then a hyperlink like `(find)' would "just work", without a need to invent yet another magic sequence of characters. ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-21 16:56 ` Eli Zaretskii 2020-01-22 4:03 ` Glenn Morris @ 2020-01-23 1:39 ` Richard Stallman 2020-01-23 3:14 ` Stefan Kangas 1 sibling, 1 reply; 14+ messages in thread From: Richard Stallman @ 2020-01-23 1:39 UTC (permalink / raw) To: Eli Zaretskii; +Cc: stefan, 39215 [[[ 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. ]]] > Why should we cater so much to non-GNU systems? The users of BSD can > install the Info manual as well, can they not? That is the right approach. Let's focus our work on improvements that are beneficial in the GNU system (as well as, possibly, elsewhere). -- Dr Richard Stallman 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] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-23 1:39 ` Richard Stallman @ 2020-01-23 3:14 ` Stefan Kangas 2020-01-24 2:58 ` Richard Stallman 0 siblings, 1 reply; 14+ messages in thread From: Stefan Kangas @ 2020-01-23 3:14 UTC (permalink / raw) To: Richard Stallman; +Cc: 39215 Richard Stallman <rms@gnu.org> writes: > > Why should we cater so much to non-GNU systems? The users of BSD can > > install the Info manual as well, can they not? > > That is the right approach. Let's focus our work on improvements that > are beneficial in the GNU system (as well as, possibly, elsewhere). This would benefit GNU just as much as non-GNU systems. There is a lot of free software out there that I would like to use on GNU, but that is not GNU software. Non-GNU software more often than not does not have an Info manual. So I would like to be able to link their man page instead. Best regards, Stefan Kangas ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-23 3:14 ` Stefan Kangas @ 2020-01-24 2:58 ` Richard Stallman 2021-09-25 1:07 ` Stefan Kangas 0 siblings, 1 reply; 14+ messages in thread From: Richard Stallman @ 2020-01-24 2:58 UTC (permalink / raw) To: Stefan Kangas; +Cc: 39215 [[[ 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. ]]] > There is a lot of free software out there that I would like to use on > GNU, but that is not GNU software. Non-GNU software more often than > not does not have an Info manual. So I would like to be able to link > their man page instead. Ok, you've convinced me. -- Dr Richard Stallman 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] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2020-01-24 2:58 ` Richard Stallman @ 2021-09-25 1:07 ` Stefan Kangas 2021-09-25 1:13 ` Lars Ingebrigtsen 2021-09-25 1:32 ` Phil Sainty 0 siblings, 2 replies; 14+ messages in thread From: Stefan Kangas @ 2021-09-25 1:07 UTC (permalink / raw) To: Richard Stallman; +Cc: 39215 [-- Attachment #1: Type: text/plain, Size: 393 bytes --] tags 39215 + patch thanks Richard Stallman <rms@gnu.org> writes: > > There is a lot of free software out there that I would like to use on > > GNU, but that is not GNU software. Non-GNU software more often than > > not does not have an Info manual. So I would like to be able to link > > their man page instead. > > Ok, you've convinced me. Thanks. How about the attached patch? [-- Attachment #2: 0001-Add-support-for-man-page-hyperlinks-in-doc-strings.patch --] [-- Type: text/x-diff, Size: 3589 bytes --] From 6368b2fe2e0e284da7c4ef1e4890aaff04bfb51c Mon Sep 17 00:00:00 2001 From: Stefan Kangas <stefan@marxist.se> Date: Sat, 25 Sep 2021 03:03:34 +0200 Subject: [PATCH] Add support for man page hyperlinks in doc strings * lisp/help-mode.el (help-man): New button type. (help-xref-man-regexp): New const. (help-make-xrefs): Use them to allow making man page buttons. * doc/lispref/tips.texi (Documentation Tips): Document the new hyperlink type. (Bug#39215) --- doc/lispref/tips.texi | 8 ++++++++ etc/NEWS | 5 +++++ lisp/help-mode.el | 14 ++++++++++++++ 3 files changed, 27 insertions(+) diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index a72ab88cef..1ea439b531 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -755,6 +755,14 @@ Documentation Tips See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. @end smallexample +To make a hyperlink to a man page, write the single-quoted name of the +man page, preceded by @samp{Man page}, @samp{man page}, or @samp{man +page for}. For example, + +@smallexample +See the man page `chmod' for details. +@end smallexample + To link to a customization group, write the single-quoted name of the group, preceded by @samp{customization group} (the first character in each word is case-insensitive). For example, diff --git a/etc/NEWS b/etc/NEWS index c266dddafa..fb4c37f912 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -3693,6 +3693,11 @@ Text like "customization group `whitespace'" will be made into a button. When clicked, it'll take the user to a Custom buffer displaying that customization group. ++++ +** Doc strings can now link to man pages. +Text like "man page `chmod'" will be made into a button. When +clicked, it will open a Man mode buffer displaying that man page. + +++ ** Buffers can now be created with certain hooks disabled. The functions 'get-buffer-create' and 'generate-new-buffer' accept a diff --git a/lisp/help-mode.el b/lisp/help-mode.el index 551cf7e1a3..730c69f8d6 100644 --- a/lisp/help-mode.el +++ b/lisp/help-mode.el @@ -224,6 +224,11 @@ 'help-info 'help-function #'info 'help-echo (purecopy "mouse-2, RET: read this Info node")) +(define-button-type 'help-man + :supertype 'help-xref + 'help-function #'man + 'help-echo (purecopy "mouse-2, RET: read this man page")) + (define-button-type 'help-customization-group :supertype 'help-xref 'help-function #'customize-group @@ -438,6 +443,11 @@ help-xref-info-regexp "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+['`‘]\\([^'’]+\\)['’]") "Regexp matching doc string references to an Info node.") +(defconst help-xref-man-regexp + (purecopy + "\\<[Mm]an[ \t\n]+\\(?:page\\)[ \t\n]+\\(?:for[ \t\n]\\)?['`‘\"]\\([^'’\"]+\\)['’\"]") + "Regexp matching doc string references to a man page.") + (defconst help-xref-customization-group-regexp (purecopy "\\<[Cc]ustomization[ \t\n]+[Gg]roup[ \t\n]+['`‘]\\([^'’]+\\)['’]") "Regexp matching doc string references to a customization group.") @@ -548,6 +558,10 @@ help-make-xrefs (setq data ;; possible newlines if para filled (replace-regexp-in-string "[ \t\n]+" " " data t t))) (help-xref-button 2 'help-info data)))) + ;; Man references + (save-excursion + (while (re-search-forward help-xref-man-regexp nil t) + (help-xref-button 1 'help-man (match-string 1)))) ;; Customization groups. (save-excursion (while (re-search-forward -- 2.30.2 ^ permalink raw reply related [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2021-09-25 1:07 ` Stefan Kangas @ 2021-09-25 1:13 ` Lars Ingebrigtsen 2021-09-25 2:10 ` Stefan Kangas 2021-09-25 1:32 ` Phil Sainty 1 sibling, 1 reply; 14+ messages in thread From: Lars Ingebrigtsen @ 2021-09-25 1:13 UTC (permalink / raw) To: Stefan Kangas; +Cc: Richard Stallman, 39215 Stefan Kangas <stefan@marxist.se> writes: > Thanks. How about the attached patch? [...] > * lisp/help-mode.el (help-man): New button type. > (help-xref-man-regexp): New const. > (help-make-xrefs): Use them to allow making man page buttons. > * doc/lispref/tips.texi (Documentation Tips): Document the new > hyperlink type. (Bug#39215) I think that's a really good idea. I haven't tried the patch, but skimming it, it looks good to me, so go ahead and push. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2021-09-25 1:13 ` Lars Ingebrigtsen @ 2021-09-25 2:10 ` Stefan Kangas 0 siblings, 0 replies; 14+ messages in thread From: Stefan Kangas @ 2021-09-25 2:10 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: Richard Stallman, 39215 tags 39215 fixed close 39215 28.1 thanks Lars Ingebrigtsen <larsi@gnus.org> writes: > Stefan Kangas <stefan@marxist.se> writes: > >> Thanks. How about the attached patch? > > [...] > >> * lisp/help-mode.el (help-man): New button type. >> (help-xref-man-regexp): New const. >> (help-make-xrefs): Use them to allow making man page buttons. >> * doc/lispref/tips.texi (Documentation Tips): Document the new >> hyperlink type. (Bug#39215) > > I think that's a really good idea. I haven't tried the patch, but > skimming it, it looks good to me, so go ahead and push. Thanks. I fixed the issue pointed out by Phil and have now pushed it to master as commit 0917919337. ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2021-09-25 1:07 ` Stefan Kangas 2021-09-25 1:13 ` Lars Ingebrigtsen @ 2021-09-25 1:32 ` Phil Sainty 2021-09-25 2:10 ` Stefan Kangas 1 sibling, 1 reply; 14+ messages in thread From: Phil Sainty @ 2021-09-25 1:32 UTC (permalink / raw) To: Stefan Kangas; +Cc: Richard Stallman, 39215 On 2021-09-25 13:07, Stefan Kangas wrote: > "\\<[Mm]an[ \t\n]+\\(?:page\\)[ \t\n]+\\(?:for[ > \t\n]\\)?['`‘\"]\\([^'’\"]+\\)['’\"]" Was "\\(?:page\\)[ \t\n]+" meant to be "\\(?:page[ \t\n]+\\)?" ? That would be almost the same as "for" except I note that there's no allowance for more than one whitespace char after "for", so maybe that needs changing as well? -Phil ^ permalink raw reply [flat|nested] 14+ messages in thread
* bug#39215: Hyperlinks to man pages in doc strings 2021-09-25 1:32 ` Phil Sainty @ 2021-09-25 2:10 ` Stefan Kangas 0 siblings, 0 replies; 14+ messages in thread From: Stefan Kangas @ 2021-09-25 2:10 UTC (permalink / raw) To: Phil Sainty; +Cc: Richard Stallman, 39215 Phil Sainty <psainty@orcon.net.nz> writes: > On 2021-09-25 13:07, Stefan Kangas wrote: >> "\\<[Mm]an[ \t\n]+\\(?:page\\)[ \t\n]+\\(?:for[ >> \t\n]\\)?['`‘\"]\\([^'’\"]+\\)['’\"]" > > Was "\\(?:page\\)[ \t\n]+" meant to be "\\(?:page[ \t\n]+\\)?" ? > > That would be almost the same as "for" except I note that there's > no allowance for more than one whitespace char after "for", so > maybe that needs changing as well? Thanks for this attentive reading. The intention was actually this, which should fix the issues you mention: "\\<[Mm]an[ \t\n]+page[ \t\n]+\\(?:for[ \t\n]+\\)?['`‘\"]\\([^'’\"]+\\)['’\"]") ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2021-09-25 2:10 UTC | newest] Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-01-21 8:55 bug#39215: Hyperlinks to man pages in doc strings Stefan Kangas 2020-01-21 15:36 ` Eli Zaretskii 2020-01-21 16:32 ` Stefan Kangas 2020-01-21 16:56 ` Eli Zaretskii 2020-01-22 4:03 ` Glenn Morris 2020-01-22 15:45 ` Eli Zaretskii 2020-01-23 1:39 ` Richard Stallman 2020-01-23 3:14 ` Stefan Kangas 2020-01-24 2:58 ` Richard Stallman 2021-09-25 1:07 ` Stefan Kangas 2021-09-25 1:13 ` Lars Ingebrigtsen 2021-09-25 2:10 ` Stefan Kangas 2021-09-25 1:32 ` Phil Sainty 2021-09-25 2:10 ` Stefan Kangas
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.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).