[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 0917919 1/2: Add support for man page hyperlinks in doc strings
From: |
Stefan Kangas |
Subject: |
master 0917919 1/2: Add support for man page hyperlinks in doc strings |
Date: |
Fri, 24 Sep 2021 22:02:22 -0400 (EDT) |
branch: master
commit 091791933704cd706f90c1685ac4b35f51c98199
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>
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 | 9 +++++++--
lisp/help-mode.el | 14 ++++++++++++++
3 files changed, 29 insertions(+), 2 deletions(-)
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index a72ab88..1ea439b 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -755,6 +755,14 @@ anchor}. The Info file name defaults to @samp{emacs}.
For example,
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 2f8fbc7..31b09da 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3698,8 +3698,13 @@ initial frame used in batch mode.
+++
** Doc strings can now link to customization groups.
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.
+button. When clicked, it will open 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.
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 551cf7e..0b404fe 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -224,6 +224,11 @@ The format is (FUNCTION ARGS...).")
'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 @@ when help commands related to multilingual environment
(e.g.,
"\\<[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 @@ that."
(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