Subject: Improve markup in man pages

From: Mario Blättermann <[email-masked]>
Date: Sun, 13 Feb 2022 14:19:32 +0100

Hello,

the SEE ALSO sections in the man pages contain links which will be
pulled in from *.x files by help2man. While help2man evaluates the
Groff markup from --help and --version output, it doesn't bother with
the markup in the *.x files. See the attached patch. The bold
formatting of the links is especially useful in HTML output (but also
in terminal output); the links become clickable and point to the
respective man page in online collections [1]. You can test the
behavior in the German version, where the links are already properly
formatted [2].

[1] https://man.archlinux.org/man/cat.1
[2] https://man.archlinux.org/man/cat.1.de

Best Regards,
Mario
diff --git a/man/arch.x b/man/arch.x
index 0a310b41f..487318207 100644
--- a/man/arch.x
+++ b/man/arch.x
@@ -3,4 +3,5 @@ arch \- print machine hardware name (same as uname -m)
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-uname(1), uname(2)
+.BR uname (1),
+.BR uname (2)
diff --git a/man/b2sum.x b/man/b2sum.x
index 5a857ca15..bb5cabb5b 100644
--- a/man/b2sum.x
+++ b/man/b2sum.x
@@ -3,4 +3,4 @@ b2sum \- compute and check BLAKE2 message digest
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/basename.x b/man/basename.x
index e91ee57ee..a6554c217 100644
--- a/man/basename.x
+++ b/man/basename.x
@@ -3,4 +3,5 @@ basename \- strip directory and suffix from filenames
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-dirname(1), readlink(1)
+.BR dirname (1),
+.BR readlink (1)
diff --git a/man/cat.x b/man/cat.x
index 9eb38cf05..e6eb90e38 100644
--- a/man/cat.x
+++ b/man/cat.x
@@ -3,4 +3,4 @@ cat \- concatenate files and print on the standard output
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-tac(1)
+.BR tac (1)
diff --git a/man/chgrp.x b/man/chgrp.x
index a61f3089e..a3d10bc27 100644
--- a/man/chgrp.x
+++ b/man/chgrp.x
@@ -3,4 +3,5 @@ chgrp \- change group ownership
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-chown(1), chown(2)
+.BR chown (1),
+.BR chown (2)
diff --git a/man/chmod.x b/man/chmod.x
index 3ab8ed055..847ba9234 100644
--- a/man/chmod.x
+++ b/man/chmod.x
@@ -115,4 +115,4 @@ quickly when run; this is called the
 .IR "sticky bit" .
 .SH OPTIONS
 [SEE ALSO]
-chmod(2)
+.BR chmod (2)
diff --git a/man/chown.x b/man/chown.x
index ee79d1b7d..22564bd6d 100644
--- a/man/chown.x
+++ b/man/chown.x
@@ -27,4 +27,4 @@ If only a colon is given, or if the entire operand is empty, neither the
 owner nor the group is changed.
 .SH OPTIONS
 [SEE ALSO]
-chown(2)
+.BR chown (2)
diff --git a/man/chroot.x b/man/chroot.x
index fc1be5286..c21336d52 100644
--- a/man/chroot.x
+++ b/man/chroot.x
@@ -3,4 +3,4 @@ chroot \- run command or interactive shell with special root directory
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-chroot(2)
+.BR chroot (2)
diff --git a/man/comm.x b/man/comm.x
index d4d8e00da..b7ab4478e 100644
--- a/man/comm.x
+++ b/man/comm.x
@@ -3,4 +3,5 @@ comm \- compare two sorted files line by line
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-join(1), uniq(1)
+.BR join (1),
+.BR uniq (1)
diff --git a/man/dirname.x b/man/dirname.x
index 09c46e4fe..3062f220b 100644
--- a/man/dirname.x
+++ b/man/dirname.x
@@ -3,4 +3,5 @@ dirname \- strip last component from file name
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-basename(1), readlink(1)
+.BR basename (1),
+.BR readlink (1)
diff --git a/man/echo.x b/man/echo.x
index 61a36706b..be65d1640 100644
--- a/man/echo.x
+++ b/man/echo.x
@@ -3,4 +3,4 @@ echo \- display a line of text
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-printf(1)
+.BR printf (1)
diff --git a/man/env.x b/man/env.x
index c2cafbaa8..6c0a0035e 100644
--- a/man/env.x
+++ b/man/env.x
@@ -64,4 +64,6 @@ cooperating) programs."
 .RE
 
 [SEE ALSO]
-sigaction(2), sigprocmask(2), signal(7)
+.BR sigaction (2),
+.BR sigprocmask (2),
+.BR signal (7)
diff --git a/man/expand.x b/man/expand.x
index 06c538882..00f12a091 100644
--- a/man/expand.x
+++ b/man/expand.x
@@ -3,4 +3,4 @@ expand \- convert tabs to spaces
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-unexpand(1)
+.BR unexpand (1)
diff --git a/man/groups.x b/man/groups.x
index fad68455f..dab30d276 100644
--- a/man/groups.x
+++ b/man/groups.x
@@ -3,4 +3,4 @@ groups \- print the groups a user is in
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-getent(1)
+.BR getent (1)
diff --git a/man/head.x b/man/head.x
index 53d2662de..953a2ab75 100644
--- a/man/head.x
+++ b/man/head.x
@@ -3,4 +3,4 @@ head \- output the first part of files
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-tail(1)
+.BR tail (1)
diff --git a/man/hostid.x b/man/hostid.x
index 767a3e2b0..df82fb412 100644
--- a/man/hostid.x
+++ b/man/hostid.x
@@ -3,4 +3,4 @@ hostid \- print the numeric identifier for the current host
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-gethostid(3)
+.BR gethostid (3)
diff --git a/man/join.x b/man/join.x
index f83e8ceca..b9f6afc10 100644
--- a/man/join.x
+++ b/man/join.x
@@ -3,4 +3,5 @@ join \- join lines of two files on a common field
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-comm(1), uniq(1)
+.BR comm (1),
+.BR uniq (1)
diff --git a/man/kill.x b/man/kill.x
index 920c59fdf..7b2a286bf 100644
--- a/man/kill.x
+++ b/man/kill.x
@@ -3,4 +3,4 @@ kill \- send signals to processes, or list signals
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-kill(2)
+.BR kill (2)
diff --git a/man/link.x b/man/link.x
index 2ae12bc0a..29cdcbcb3 100644
--- a/man/link.x
+++ b/man/link.x
@@ -3,4 +3,4 @@ link \- call the link function to create a link to a file
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-link(2)
+.BR link (2)
diff --git a/man/ln.x b/man/ln.x
index daba9bfd2..9d1e318be 100644
--- a/man/ln.x
+++ b/man/ln.x
@@ -3,4 +3,5 @@ ln \- make links between files
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-link(2), symlink(2)
+.BR link (2),
+.BR symlink (2)
diff --git a/man/logname.x b/man/logname.x
index 83dbc066f..c197aa38c 100644
--- a/man/logname.x
+++ b/man/logname.x
@@ -3,4 +3,4 @@ logname \- print user\'s login name
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-getlogin(3)
+.BR getlogin (3)
diff --git a/man/ls.x b/man/ls.x
index 83dd4969e..8087943f9 100644
--- a/man/ls.x
+++ b/man/ls.x
@@ -3,4 +3,4 @@ ls \- list directory contents
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-dircolors(1)
+.BR dircolors (1)
diff --git a/man/md5sum.x b/man/md5sum.x
index 3f4cc6409..c2bbc4b68 100644
--- a/man/md5sum.x
+++ b/man/md5sum.x
@@ -5,7 +5,11 @@ md5sum \- compute and check MD5 message digest
 [BUGS]
 Do not use the MD5 algorithm for security related purposes.
 Instead, use an SHA\-2 algorithm, implemented in the programs
-sha224sum(1), sha256sum(1), sha384sum(1), sha512sum(1),
-or the BLAKE2 algorithm, implemented in b2sum(1)
+.BR sha224sum (1),
+.BR sha256sum (1),
+.BR sha384sum (1),
+.BR sha512sum (1),
+or the BLAKE2 algorithm, implemented in
+.BR b2sum (1).
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/mkdir.x b/man/mkdir.x
index 4b35013da..7c8b2fb3f 100644
--- a/man/mkdir.x
+++ b/man/mkdir.x
@@ -3,4 +3,4 @@ mkdir \- make directories
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-mkdir(2)
+.BR mkdir (2)
diff --git a/man/mkfifo.x b/man/mkfifo.x
index 7d06348a5..2d250b421 100644
--- a/man/mkfifo.x
+++ b/man/mkfifo.x
@@ -3,4 +3,4 @@ mkfifo \- make FIFOs (named pipes)
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-mkfifo(3)
+.BR mkfifo (3)
diff --git a/man/mknod.x b/man/mknod.x
index aaa3a9a89..c5d0804a3 100644
--- a/man/mknod.x
+++ b/man/mknod.x
@@ -3,4 +3,4 @@ mknod \- make block or character special files
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-mknod(2)
+.BR mknod (2)
diff --git a/man/mktemp.x b/man/mktemp.x
index 393ca742b..554600285 100644
--- a/man/mktemp.x
+++ b/man/mktemp.x
@@ -3,4 +3,6 @@ mktemp \- create a temporary file or directory
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-mkstemp(3), mkdtemp(3), mktemp(3)
+.BR mkstemp (3),
+.BR mkdtemp (3),
+.BR mktemp (3)
diff --git a/man/mv.x b/man/mv.x
index 6e32d5da0..ef322e5ae 100644
--- a/man/mv.x
+++ b/man/mv.x
@@ -3,4 +3,4 @@ mv \- move (rename) files
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-rename(2)
+.BR rename (2)
diff --git a/man/nice.x b/man/nice.x
index 952cb1073..949f8ceb4 100644
--- a/man/nice.x
+++ b/man/nice.x
@@ -3,4 +3,5 @@ nice \- run a program with modified scheduling priority
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-nice(2), renice(1)
+.BR nice (2),
+.BR renice (1)
diff --git a/man/printf.x b/man/printf.x
index 22fc5afdf..1fcfe65ba 100644
--- a/man/printf.x
+++ b/man/printf.x
@@ -3,4 +3,4 @@ printf \- format and print data
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-printf(3)
+.BR printf (3)
diff --git a/man/pwd.x b/man/pwd.x
index 65daec0a9..e81bd8fe7 100644
--- a/man/pwd.x
+++ b/man/pwd.x
@@ -3,4 +3,4 @@ pwd \- print name of current/working directory
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-getcwd(3)
+.BR getcwd (3)
diff --git a/man/readlink.x b/man/readlink.x
index 3141cd253..8a6030905 100644
--- a/man/readlink.x
+++ b/man/readlink.x
@@ -2,7 +2,11 @@
 readlink \- print resolved symbolic links or canonical file names
 [DESCRIPTION]
 .\" Add any additional description here
-Note realpath(1) is the preferred command to use
+Note
+.BR realpath (1)
+is the preferred command to use
 for canonicalization functionality.
 [SEE ALSO]
-readlink(2), realpath(1), realpath(3)
+.BR readlink (2),
+.BR realpath (1),
+.BR realpath (3)
diff --git a/man/realpath.x b/man/realpath.x
index a52fa2570..332b1c16b 100644
--- a/man/realpath.x
+++ b/man/realpath.x
@@ -3,4 +3,6 @@ realpath \- print the resolved path
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-readlink(1), readlink(2), realpath(3)
+.BR readlink (1),
+.BR readlink (2),
+.BR realpath (3)
diff --git a/man/rm.x b/man/rm.x
index 924610f5c..72791700e 100644
--- a/man/rm.x
+++ b/man/rm.x
@@ -28,4 +28,7 @@ prompts the user for whether to remove the file.  If the response is
 not affirmative, the file is skipped.
 .SH OPTIONS
 [SEE ALSO]
-unlink(1), unlink(2), chattr(1), shred(1)
+.BR unlink (1),
+.BR unlink (2),
+.BR chattr (1),
+.BR shred (1)
diff --git a/man/rmdir.x b/man/rmdir.x
index a612f8396..283396a01 100644
--- a/man/rmdir.x
+++ b/man/rmdir.x
@@ -3,4 +3,4 @@ rmdir \- remove empty directories
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-rmdir(2)
+.BR rmdir (2)
diff --git a/man/sha1sum.x b/man/sha1sum.x
index 8fd824f10..da8cabca8 100644
--- a/man/sha1sum.x
+++ b/man/sha1sum.x
@@ -5,7 +5,11 @@ sha1sum \- compute and check SHA1 message digest
 [BUGS]
 Do not use the SHA-1 algorithm for security related purposes.
 Instead, use an SHA\-2 algorithm, implemented in the programs
-sha224sum(1), sha256sum(1), sha384sum(1), sha512sum(1),
-or the BLAKE2 algorithm, implemented in b2sum(1)
+.BR sha224sum (1),
+.BR sha256sum (1),
+.BR sha384sum (1),
+.BR sha512sum (1),
+or the BLAKE2 algorithm, implemented in
+.BR b2sum (1).
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/sha224sum.x b/man/sha224sum.x
index 38a64d29c..263bdff2f 100644
--- a/man/sha224sum.x
+++ b/man/sha224sum.x
@@ -3,4 +3,4 @@ sha224sum \- compute and check SHA224 message digest
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/sha256sum.x b/man/sha256sum.x
index 4ad8b3508..1f2a5592f 100644
--- a/man/sha256sum.x
+++ b/man/sha256sum.x
@@ -3,4 +3,4 @@ sha256sum \- compute and check SHA256 message digest
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/sha384sum.x b/man/sha384sum.x
index a8c09cd62..4a55f1f14 100644
--- a/man/sha384sum.x
+++ b/man/sha384sum.x
@@ -3,4 +3,4 @@ sha384sum \- compute and check SHA384 message digest
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/sha512sum.x b/man/sha512sum.x
index 308bf51ee..bbe0c18a6 100644
--- a/man/sha512sum.x
+++ b/man/sha512sum.x
@@ -3,4 +3,4 @@ sha512sum \- compute and check SHA512 message digest
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-cksum(1)
+.BR cksum (1)
diff --git a/man/sleep.x b/man/sleep.x
index f1343e81a..51886b5a3 100644
--- a/man/sleep.x
+++ b/man/sleep.x
@@ -3,4 +3,4 @@ sleep \- delay for a specified amount of time
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-sleep(3)
+.BR sleep (3)
diff --git a/man/sort.x b/man/sort.x
index 8d8c67dab..4cbec52fb 100644
--- a/man/sort.x
+++ b/man/sort.x
@@ -3,4 +3,5 @@ sort \- sort lines of text files
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-shuf(1), uniq(1)
+.BR shuf (1),
+.BR uniq (1)
diff --git a/man/stat.x b/man/stat.x
index b9f8c68e4..e2c7547b5 100644
--- a/man/stat.x
+++ b/man/stat.x
@@ -3,4 +3,6 @@ stat \- display file or file system status
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-stat(2), statfs(2), statx(2)
+.BR stat (2),
+.BR statfs (2),
+.BR statx (2)
diff --git a/man/sync.x b/man/sync.x
index 18ee3fc44..285dcdce0 100644
--- a/man/sync.x
+++ b/man/sync.x
@@ -6,4 +6,7 @@ sync \- Synchronize cached writes to persistent storage
 Persistence guarantees vary per system.
 See the system calls below for more details.
 [SEE ALSO]
-fdatasync(2), fsync(2), sync(2), syncfs(2)
+.BR fdatasync (2),
+.BR fsync (2),
+.BR sync (2),
+.BR syncfs (2)
diff --git a/man/tac.x b/man/tac.x
index 677da2f82..86ccab728 100644
--- a/man/tac.x
+++ b/man/tac.x
@@ -3,4 +3,5 @@ tac \- concatenate and print files in reverse
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-cat(1), rev(1)
+.BR cat (1),
+.BR rev (1)
diff --git a/man/tail.x b/man/tail.x
index 68f27820c..617a41f70 100644
--- a/man/tail.x
+++ b/man/tail.x
@@ -3,4 +3,4 @@ tail \- output the last part of files
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-head(1)
+.BR head (1)
diff --git a/man/timeout.x b/man/timeout.x
index ddb309251..c9d00039c 100644
--- a/man/timeout.x
+++ b/man/timeout.x
@@ -3,6 +3,6 @@ timeout \- run a command with a time limit
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-kill(1)
+.BR kill (1)
 [BUGS]
 Some platforms don't currently support timeouts beyond the year 2038.
diff --git a/man/truncate.x b/man/truncate.x
index 27a54b97d..0078a4308 100644
--- a/man/truncate.x
+++ b/man/truncate.x
@@ -3,4 +3,6 @@ truncate \- shrink or extend the size of a file to the specified size
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-dd(1), truncate(2), ftruncate(2)
+.BR dd (1),
+.BR truncate (2),
+.BR ftruncate (2)
diff --git a/man/uname.x b/man/uname.x
index b27e86f1d..6200dde89 100644
--- a/man/uname.x
+++ b/man/uname.x
@@ -3,4 +3,5 @@ uname \- print system information
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-arch(1), uname(2)
+.BR arch (1),
+.BR uname (2)
diff --git a/man/unexpand.x b/man/unexpand.x
index 08bc2ad44..319b539b1 100644
--- a/man/unexpand.x
+++ b/man/unexpand.x
@@ -3,4 +3,4 @@ unexpand \- convert spaces to tabs
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-expand(1)
+.BR expand (1)
diff --git a/man/uniq.x b/man/uniq.x
index 013cef334..e1f90157d 100644
--- a/man/uniq.x
+++ b/man/uniq.x
@@ -3,4 +3,6 @@ uniq \- report or omit repeated lines
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-comm(1), join(1), sort(1)
+.BR comm (1),
+.BR join (1),
+.BR sort (1)
diff --git a/man/unlink.x b/man/unlink.x
index d12cc2e84..14a7e27b3 100644
--- a/man/unlink.x
+++ b/man/unlink.x
@@ -3,4 +3,4 @@ unlink \- call the unlink function to remove the specified file
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-unlink(2)
+.BR unlink (2)
diff --git a/man/users.x b/man/users.x
index d15001ebb..5ffcf3805 100644
--- a/man/users.x
+++ b/man/users.x
@@ -3,4 +3,5 @@ users \- print the user names of users currently logged in to the current host
 [DESCRIPTION]
 .\" Add any additional description here
 [SEE ALSO]
-getent(1), who(1)
+.BR getent (1),
+.BR who (1)