diff options
author | Pádraig Brady <P@draigBrady.com> | 2022-02-14 21:36:29 +0000 |
---|---|---|
committer | Pádraig Brady <P@draigBrady.com> | 2022-02-15 17:07:22 +0000 |
commit | 63228501e68875cc072bf479d491ec39ffa01ba3 (patch) | |
tree | 17f46782cbdb89a1f1c8fdaa0c4e2d8846c747b9 | |
parent | 041dfff5db1f09c92435e46b65931b04364c37f6 (diff) | |
download | coreutils-63228501e68875cc072bf479d491ec39ffa01ba3.tar.gz |
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
-rw-r--r-- | configure.ac | 14 | ||||
-rwxr-xr-x | man/help2man | 11 | ||||
-rw-r--r-- | 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 |