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

diff --git a/configure.ac b/configure.ac
index 453baccff7c1ad32b8553dd54b31393ba9e631aa..7e4afc96f5206e1f8f443de5f2d00dd30755d493 100644 (file)
--- 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 99a1c9263d329deb871b930c507eba472244e91b..581f69ddde15c5a549a0cc54fa12aa98844763f3 100755 (executable)
--- 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 0822536c8838644e598a28e4d31bd1a968cb97ed..46ed35a4063aab22b9062ee479594d31b345d5a9 100644 (file)
--- 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