bug#39215: Hyperlinks to man pages in doc strings

[Stefan Kangas <stefan@marxist.se>]

[-- 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