* 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: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
* 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
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).