Subject: bug#53977: closed (Re: bug#53977: Improve markup in man pages)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 14 Feb 2022 23:01:02 +0000

Your bug report

#53977: Improve markup in man pages

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
53977: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=53977
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#53977: Improve markup in man pages
From: Pádraig Brady <[email-masked]>
To: Mario Blättermann <[email-masked]>, [email-masked]
Cc: [email-masked], Brendan O'Dea <[email-masked]>
Date: Mon, 14 Feb 2022 23:00:22 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

On 14/02/2022 13:52, Mario Blättermann wrote:
> Hello Pádraig,
> 
> Am Mo., 14. Feb. 2022 um 13:15 Uhr schrieb Pádraig Brady <[email-masked]>:
>>
>> On 13/02/2022 13:19, Mario Blättermann wrote:
>>> 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
>>
>> Sorry. I'm still not convinced on this.
>> It seems like a layering violation to stipulate a style here.
>> The renderer should have enough context to highlight appropriately.
>> See for example:
>>
>> https://man7.org/linux/man-pages/man1/sort.1.html
>>
> 
> Maybe some renderers are smart enough to highlight this. But it
> shouldn't be up to the developers of such renderers to apply missing
> formattings virtually.

Thanks for the consideration on this.
I'm not strongly against hardcoding the formatting,
but I do think it's worth discussing the need.

Note we discussed this previously at:
https://lists.gnu.org/archive/html/coreutils/2021-01/msg00008.html

The summary there was things have trended over time
from a mixture of none,italic,bold style references
to mostly bold.

>> Note the man7.org renderer only highlights the SEE ALSO references,
>> when ideally it would highlight all instances of this pattern.
>> Anyway handling references outside of the SEE ALSO section,
>> is another reason to have the renderer do this consistently.
>> See for example all the appropriately highlighted references in:
>>
>> http://man.he.net/?topic=sort&section=all
>> https://man.cx/sort
>>
> Yes, but this doesn't work in all imaginable cases, because the
> renderer needs to be able to evaluate if it is a link or not. In your
> example, "shuf" is a link because it is tagged with the section
> number, but this wouldn't, then "shuf" would be as plain as other
> words. See the "diff3.1" man page [1]: > > -e, --ed
> output ed script incorporating changes from OLDFILE to YOURFILE into MYFILE
> 
> If "ed" would be "ed(1)" then it would be detected as a command name
> here, but it isn't.

But it isn't bold either.
I suggest this page should be updated to use "ed(1)".

> Well, the best solution would be to dig in the
> Help2man code and try to improve the detection of parts worth to be
> formatted - provided solid Perl skills. But this would be outside of
> the topic of this bug report;

Yes a `help2man --bold-refs` option seems useful.
It give the option to apply the formatting,
and more centrally, rather than inconsistently sprinkled
through all man pages.
Also this would be the only way to consistently
style all references in coreutils, since some are output
to the terminal through --help.

> let's go back to the SEE ALSO links. The
> man page man-pages(7) says [2]:
> 
> »The name of the command, and its options, should always be formatted in bold.«
>  
> In fact, the SEE ALSO links are also command names, although not the
> command the current man page describes. 

The bold here is pertaining to styling of the headers of the page,
rather than to any command references in general IMHO.
In general bold text interspersed in other text on the terminal
can be quite distracting to read. Some terminals can make it
bigger, brighter, blurrier, ...

> Let's have a look at other projects [that hardcode bold references]
 > grub, grep, kernel.

I see Paul added the grep markup recently in a seemingly unrelated change:
https://git.savannah.gnu.org/gitweb/?p=grep.git;a=commit;h=fe630c9f

> I could mention lots of similar examples, but just open an arbitrary
> man page in your terminal with "man", not in Vim; you will see that
> (almost …) all SEE ALSO links are formatted bold.

I did check also, and see lots of inconsistencies.
BTW re vim, the match for references is:
   syn match manReference "\f\+([1-9][a-z]\=)"

> With the bold
> formatting (and correct placing of the section number), you make sure
> that *all* renderers, both the simple ones like "man" in the terminal
> and the advanced HTML/DVI/PDF/whatever renderers, format the links
> correctly.

"correctly" is a strong word here.

> [1] https://man.cx/diff3#heading3
> [2] https://man.archlinux.org/man/man-pages.7.en#Formatting_conventions_for_manual_pages_describing_commands
> [3] https://git.savannah.gnu.org/cgit/grub.git/tree/docs/man/grub-editenv.h2m
> [4] https://git.savannah.gnu.org/cgit/grep.git/tree/doc/grep.in.1#n1359
> [5] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man1/mtrace.1#n64
> [6] https://github.com/freebsd/freebsd-src/blob/main/usr.bin/sort/sort.1.in#L580

I've attached a patch to implement help2man --bold-refs.
Brendan is that something that might be added to official help2man?

coreutils enables this by default for generated man pages,
and it can be disabled if needed with:
   ./configure --disable-bold-man-page-references

Also attached is an ancillary patch I noticed with wrong section for exec(3p)

Marking this bug as done.

cheers,
Pádraig

From c197d7cdd8333b93cc220d7c8e8f712ba431ff4c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Mon, 14 Feb 2022 21:36:29 +0000
Subject: [PATCH] doc: use bold style for man page references

It's more common to use bold style than not,
for references to other man pages.
Ideally each man page renderer would highlight references,
but currently some rely on styles in the page itself.

* man/help2man: Implement a --bold-refs option that
will mark up references like "name(1)" with bold
style around the "name" component.
* man/local.mk: Pass --bold-refs to our help2man unless disabled.
* configure.ac: Add a --disable-bold-man-page-references option.
Addresses https://bugs.gnu.org/53977
---
 configure.ac | 14 ++++++++++++++
 man/help2man | 11 ++++++++++-
 man/local.mk |  5 ++++-
 3 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/configure.ac b/configure.ac
index 453baccff..7e4afc96f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -114,6 +114,20 @@ if test "$gl_single_binary" = 'symlinks'; then
 fi
 AM_CONDITIONAL([SINGLE_BINARY], [test "$gl_single_binary" != no])
 
+AC_ARG_ENABLE([bold-man-page-references],
+  [AS_HELP_STRING([--disable-bold-man-page-references],
+     [When generating man pages, do not apply bold style around any
+      references like name(1) etc.])],
+  [gl_bold_manpages=yes ;
+   case $enableval in
+     no|yes) gl_bold_manpages=$enableval ;;
+     *)      AC_MSG_ERROR([bad value $enableval for bold-man-page-references.
+                           Options are: yes, no.]) ;;
+   esac],
+  [gl_bold_manpages=yes]
+)
+AM_CONDITIONAL([BOLD_MAN_REFS], [test "$gl_bold_manpages" != no])
+
 AC_ARG_ENABLE([gcc-warnings],
   [AS_HELP_STRING([--enable-gcc-warnings@<:@=TYPE@:>@],
     [control generation of GCC warnings.  The TYPE 'no' disables
diff --git a/man/help2man b/man/help2man
index 99a1c9263..581f69ddd 100755
--- a/man/help2man
+++ b/man/help2man
@@ -78,6 +78,7 @@ Usage: %s [OPTION]... EXECUTABLE
  -p, --info-page=TEXT    name of Texinfo manual
  -N, --no-info           suppress pointer to Texinfo manual
  -l, --libtool           exclude the `lt-' from the program name
+ -b, --bold-refs         apply bold style to references
      --help              print this help, then exit
      --version           print version number, then exit
 
@@ -99,7 +100,7 @@ my $help_option = '--help';
 my $version_option = '--version';
 my $discard_stderr = 1;
 my ($opt_name, @opt_include, $opt_output, $opt_info, $opt_no_info, $opt_libtool,
-    $version_text);
+    $opt_bold_refs, $version_text);
 
 my %opt_def = (
     'n|name=s'		 => \$opt_name,
@@ -113,6 +114,7 @@ my %opt_def = (
     'p|info-page=s'	 => \$opt_info,
     'N|no-info'		 => \$opt_no_info,
     'l|libtool'		 => \$opt_libtool,
+    'b|bold-refs'	 => \$opt_bold_refs,
     'help'		 => sub { print $help_info; exit },
     'version'		 => sub { print $version_info; exit },
     'h|help-option=s'	 => \$help_option,
@@ -714,6 +716,13 @@ for my $sect (@pre, (grep !$filter{$_}, @sections), @post)
 
 	for ($include{$sect})
 	{
+            # Add bold style around referenced pages.
+            if ($opt_bold_refs)
+            {
+                # This will ignore entries already marked up (with \)
+                s/(^|\s|,)([\[\w\x83]+)\(([1-9][[:lower:]]?)\)/$1\\fB$2\\fP($3)/g;
+            }
+
 	    # Replace leading dot, apostrophe, backslash and hyphen
 	    # tokens.
 	    s/\x80/\\&./g;
diff --git a/man/local.mk b/man/local.mk
index 0822536c8..46ed35a40 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -24,7 +24,10 @@ run_help2man = $(SHELL) $(srcdir)/man/dummy-man
 else
 ## Graceful degradation for systems lacking perl.
 if HAVE_PERL
-run_help2man = $(PERL) -- $(srcdir)/man/help2man
+if BOLD_MAN_REFS
+help2man_OPTS=--bold-refs
+endif
+run_help2man = $(PERL) -- $(srcdir)/man/help2man $(help2man_OPTS)
 else
 run_help2man = $(SHELL) $(srcdir)/man/dummy-man
 endif
-- 
2.26.2

From a32abefbee4df120e5bba888b3a202c728aff128 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Mon, 14 Feb 2022 22:56:18 +0000
Subject: [PATCH] doc: env: fix man page reference of exec(2) to exec(3p)

* man/env.x: Change exec() reference from section 2 to 3p.
---
 man/env.x | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/env.x b/man/env.x
index c2cafbaa8..6dcbba57a 100644
--- a/man/env.x
+++ b/man/env.x
@@ -54,7 +54,7 @@ sh \-c 'env \-\-default-signal=PIPE seq inf | head \-n1'
 .PP
 
 [NOTES]
-POSIX's exec(2) pages says:
+POSIX's exec(3p) pages says:
 .RS
 "many existing applications wrongly assume that they start with certain
 signals set to the default action and/or unblocked.... Therefore, it is best
-- 
2.26.2

Subject: Improve markup in man pages
From: Mario Blättermann <[email-masked]>
To: [email-masked]
Date: Sun, 13 Feb 2022 14:19:32 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

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)