[PATCH 30/31] docs: migrate man pages to hyperlinking MR macro

"G. Branden Robinson" <[email protected]> Thu, 23 Apr 2026 18:01:45 -0500
Newsgroups	gmane.editors.nano.devel
Message-ID	<20260423230145.jyk6xwnk5zzilyes@illithid>
Also promote some references to other system software to man page cross
references.

Some years ago, the man(7) package of Plan 9 from User Space and groff
1.23.0 introduced the `MR` macro.

groff_man_style(7):
   Hyperlink macros
     Man page cross references like ls(1) are best presented with MR.
     Mark email addresses with MT/ME and other sorts of URI with UR/UE.
     To hyperlink text, terminals and pager programs must support
     ECMA‐48 OSC 8 escape sequences (see grotty(1)).  When device
     support is unavailable or disabled with the U register (see section
     “Options” below), groff man renders these URIs between angle
     brackets (⟨ ⟩) after the linked text.
...
     .MR topic [manual‐section [trailing‐text]]
            (since groff 1.23) Set a man page cross reference as
            “topic(manual‐section)”.  If manual‐section is absent, the
            package omits the surrounding parentheses.  If trailing‐text
            (typically punctuation) is specified, it follows the closing
            parenthesis without intervening space.  Hyphenation is
            disabled while the cross reference is set.  topic is set in
            the font specified by the MF string.  If manual‐section is
            present, the cross reference hyperlinks to a URI of the form
            “man:topic(manual‐section)”.

                   The output driver
                   .MR grops 1
                   produces PostScript from
                   .I troff
                   output.
                   .
                   The Ghostscript program (\c
                   .MR gs 1 )
                   interprets PostScript and PDF.
...
   History
...
  ... Plan 9 from User Space’s troff introduced MR in 2020, and
  incorporated the lq and rq strings in 2025.
---
 doc/nano.1   | 29 ++++++++++++++++++++---------
 doc/nanorc.5 | 33 +++++++++++++++++++++++----------
 doc/rnano.1  |  6 ++++--
 3 files changed, 47 insertions(+), 21 deletions(-)

diff --git a/doc/nano.1 b/doc/nano.1
index 5fef601a..3b2bd237 100644
--- a/doc/nano.1
+++ b/doc/nano.1
@@ -137,7 +137,7 @@ .SS Editing
 The two lines at the bottom of the screen show some important commands;
 the built-in help (\fB\[ha]G\fR) lists all the available ones.
 The default key bindings can be changed via a \fInanorc\fR file \[em] see
-.BR nanorc (5).
+.MR nanorc 5 .
 .
 .SH Options
 .TP
@@ -169,7 +169,8 @@ .SH Options
 This can be overridden for specific elements by setting the options
 \fB\%titlecolor\fR, \fB\%statuscolor\fR, \fB\%promptcolor\fR,
 \fB\%minicolor\fR, \fB\%keycolor\fR, \fB\%numbercolor\fR, and/or
-\fB\%selectedcolor\fR in your \fInanorc\fR file.  See \fBnanorc\fR(5).
+\fB\%selectedcolor\fR in your \fInanorc\fR file.  See
+.MR nanorc 5 .
 .TP
 .B \-E
 .TQ
@@ -186,7 +187,9 @@ .SH Options
 .B \-G
 .TQ
 .B \-\-locking
-Use vim-style file locking when editing files.
+Use
+.MR vim 1 -style
+file locking when editing files.
 .TP
 .B \-H
 .TQ
@@ -209,9 +212,12 @@ .SH Options
 .B \-K
 .TQ
 .B \-\-rawsequences
-Interpret escape sequences directly, instead of asking \fIncurses\fR
+Interpret escape sequences directly, instead of asking
+.MR ncurses 3
 to translate them.  (If you need this option to get some keys to work
-properly, it means that the \fIterminfo\fR terminal description that
+properly, it means that the
+.MR terminfo 3
+terminal description that
 is used does not fully match the actual behavior of your terminal.
 This can happen when you ssh into a BSD machine, for example.)
 Using this option disables \fBnano\fR's mouse support.
@@ -446,7 +452,10 @@ .SH Options
 .TQ
 .BI \-\-speller=\[dq] "program \fR[\fIargument \fR.\|.\|.]" \[dq]
 Use this command to perform spell checking and correcting, instead of
-using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1).
+using the built-in corrector that calls
+.MR hunspell 1
+or
+.MR spell 1 .
 .TP
 .B \-t
 .TQ
@@ -590,7 +599,7 @@ .SH Files
 \fInanorc\fR (if it exists), and then the user's \fInanorc\fR (if it
 exists), either \fI\[ti]/.nanorc\fR or \%\fI$XDG_CONFIG_HOME/\:nano/\:nanorc\fR
 or \%\fI\[ti]/.config/\:nano/\:nanorc\fR, whichever is encountered first.  See
-.BR nanorc (5)
+.MR nanorc 5
 for more information on the possible contents of those files.
 .P
 See \fI/usr/\:share/\:nano/\fR and \fI/\:usr/\:share/\:nano/\:extra/\fR
@@ -618,7 +627,9 @@ .SH Notes
 These unlisted bindings work in any locale.
 .P
 When you want to copy marked text from \fBnano\fR to the system's clipboard,
-see one of the examples in the \fBnanorc\fR(5) man page.
+see one of the examples in the
+.MR nanorc 5
+man page.
 .P
 If no alternative spell checker command is specified on the command
 line nor in one of the \fInanorc\fR files, \fBnano\fR checks the
@@ -662,6 +673,6 @@ .SS Homepage
 .UE
 .
 .P
-.BR nanorc (5)
+.MR nanorc 5
 .P
 \fI/usr/share/doc/nano/\fR (or equivalent on your system)
diff --git a/doc/nanorc.5 b/doc/nanorc.5
index 040c4e6a..8c697d49 100644
--- a/doc/nanorc.5
+++ b/doc/nanorc.5
@@ -202,7 +202,9 @@ .SH Options
 (Any line with an anchor additionally gets a mark in the margin.)
 .TP
 .B set locking
-Use vim-style file locking when editing files.
+Use
+.MR vim 1 -style
+file locking when editing files.
 .TP
 .B set magic
 When neither the file's name nor its first line give a clue,
@@ -304,11 +306,14 @@ .SH Options
 email, and to rewrap blocks of line comments when writing source code.
 .TP
 .B set rawsequences
-Interpret escape sequences directly, instead of asking \fIncurses\fR
+Interpret escape sequences directly, instead of asking
+.MR ncurses 3
 to translate them.  (If you need this option to get some keys to work
-properly, it means that the \fIterminfo\fR terminal description that is used
-does not fully match the actual behavior of your terminal.  This can
-happen when you ssh into a BSD machine, for example.)
+properly, it means that the
+.MR terminfo 3
+terminal description that
+is used does not fully match the actual behavior of your terminal.
+This can happen when you ssh into a BSD machine, for example.)
 Using this option disables \fBnano\fR's mouse support.
 .TP
 .B set rebinddelete
@@ -357,7 +362,10 @@ .SH Options
 .TP
 .BI "set speller \[dq]" "program \fR[\fIargument \fR.\|.\|.]" \[dq]
 Use the given \fIprogram\fR to do spell checking and correcting, instead of
-using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1).
+using the built-in corrector that calls
+.MR hunspell 1
+or
+.MR spell 1 .
 .TP
 .B set spotlightcolor \fR[\fBbold,\fR][\fBitalic,\fR]\fIfgcolor\fB,\fIbgcolor\fR
 Use this color combination for highlighting a search match.
@@ -512,7 +520,9 @@ .SS "Syntax highlighting"
 .BI "magic \[dq]" regex "\[dq] " \fR.\|.\|.
 If no \fIfileregex\fR matched and no \fBheader\fR regex matched
 either, then compare this \fIregex\fR (or regexes) against the
-result of querying the \fBmagic\fR database about the current
+result of querying the
+.MR magic 5
+database about the current
 file, to determine whether this syntax should be used for it.
 (This querying is done only when \fIlibmagic\fR is actually installed
 on the system and \fB\-\-magic\fR or \[lq]\fBset magic\fR\[rq] was given.)
@@ -753,8 +763,11 @@ .SS "Rebinding keys"
 output of the program replaces the buffer (or the marked region).
 .TP
 .B speller
-Invokes a spell-checking program, either the default \fBhunspell\fR(1) or GNU
-\fBspell\fR(1), or the one defined by \fB\-\-speller\fR or \[lq]\fBset speller\fR\[rq].
+Invokes a spell-checking program, either the default
+.MR hunspell 1
+or GNU
+.MR spell 1 ,
+or the one defined by \fB\-\-speller\fR or \[lq]\fBset speller\fR\[rq].
 .TP
 .B formatter
 Invokes a full-buffer-processing program (if the active syntax defines one).
@@ -1147,7 +1160,7 @@ .SH Files
 (and for less common file types in the \fIextra/\fR subdirectory).
 .
 .SH See also
-.BR nano (1)
+.MR nano 1
 .TP
 .UR https://\:nano\-editor\:.org/\:cheatsheet\:.html
 .UE
diff --git a/doc/rnano.1 b/doc/rnano.1
index b7c78fc0..40dfed88 100644
--- a/doc/rnano.1
+++ b/doc/rnano.1
@@ -68,7 +68,9 @@ .SH Options
 .B \-\-help
 Show the available command-line options and exit.
 .P
-For all existing options, see the \fBnano\fR(1) man page.
+For all existing options, see the
+.MR nano 1
+man page.
 .
 .SH Bugs
 Please report bugs via
@@ -83,4 +85,4 @@ .SS Homepage
 .UE
 .
 .P
-.BR nano (1)
+.MR nano 1
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)