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