Subject: Re: bug#18428: Bug#760861: bug#18428: Bug#760861: bug#18428: coreutils binary breaks coreutils documentation

From: Bernhard Voelker <[email-masked]>
Date: Thu, 11 Sep 2014 10:54:28 +0200

On 09/11/2014 02:31 AM, Pádraig Brady wrote:

 > Subject: [PATCH 1/2] doc: adjust reference to info nodes in man pages

...

> Subject: [PATCH 2/2] doc: reference online info pages directly from man pages

The result of both patches looks almost good:

--- a/share/man/man1/basename.1
+++ b/share/man/man1/basename.1
@@ -43,11 +43,12 @@ basename \-s .h include/stdio.h
  .TP
  basename \-a any/str1 any/str2
  \-> "str1" followed by "str2"
-.PP
-GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
-Report basename translation bugs to <http://translationproject.org/team/>
  .SH AUTHOR
  Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
+.br
+Report basename translation bugs to <http://translationproject.org/team/>
  .SH COPYRIGHT
  Copyright \(co 2014 Free Software Foundation, Inc.
  License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
@@ -57,14 +58,7 @@ There is NO WARRANTY, to the extent permitted by law.
  .SH "SEE ALSO"
  dirname(1), readlink(1)
  .PP
-The full documentation for
-.B basename
-is maintained as a Texinfo manual.  If the
-.B info
-and
-.B basename
-programs are properly installed at your site, the command
-.IP
-.B info coreutils \(aqbasename invocation\(aq
-.PP
-should give you access to the complete manual.
+.br
+Full documentation at: <http://www.gnu.org/software/coreutils/basename>
+.br
+or available locally via: info '(coreutils) basename invocation'
________________________________^_______________________________^

I think we need the \aq instead of ' here, don't we?

> * help2man: Adjust to add the "online help" link (and subsequent
> translation bugs link) to a "REPORTING BUGS" section.
> Also add the concise links for further information in --help
> to the "SEE ALSO" section, and dispense with the more verbose
> default for that.

With this, we'd deviate from stock GNU help2man again.
I haven't looked into http://www.gnu.org/software/help2man/
too much yet, but are you sure we can't do the same with
the original upstream help2man?
BTW: we are using 1.43.3 while 1.46.2 is already available.
Maybe there are a few new options which may help.

Thanks & have a nice day,
Berny