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

From: Pádraig Brady <[email-masked]>
Date: Thu, 11 Sep 2014 01:31:35 +0100

On 09/09/2014 03:52 PM, Michael Stone wrote:
> On Tue, Sep 09, 2014 at 03:31:35PM +0100, Pádraig Brady wrote:
>> It's useful to many, but I agree most don't bother with it
>> due to the awkward non intuitive default info reader _interface_
>> (though pinfo is a bit better in that regard).
> 
> Right. I've heard the argument for 15 years that info docs are really good, it's just the interface. :) In all that time, a better interface hasn't really caught on, and the web happened.
> 
>> Though it would be better to have direct links.
>> Now the above full node URL is too long/awkward, so I've just now setup redirects,
>> so the following proposed new trailers for ls --help and man pages should work:
>>
>> ls --help:
>>  ...
>>  Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
>>  Full installed documentation: info '(coreutils) ls invocation'
> 
> A huge improvement. I suspect that this might also help the info docs show up in google, instead of being below the fold. Alternative wording:
> 
>   Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
>   or available locally via: info '(coreutils) ls invocation'
> 
> To make it more clear it's the same thing available different ways.

Done in the attached which I'll push later.

thanks,
Pádraig.

>From e4627416b4be078a184372b9b0582517612a3c39 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Tue, 9 Sep 2014 02:05:45 +0100
Subject: [PATCH 1/2] doc: adjust reference to info nodes in man pages

old form: coreutils '$cmd invocation'
new form: '(coreutils) $cmd invocation'

The old form erroneously referenced the node for the 'coreutils'
multi-call program.  Now that problematic node name was renamed
in commit v8.23-18-g72e470b, but the newer less ambiguous form
also has the advantage of working with the pinfo viewer for example.
Full discussion at http://bugs.gnu.org/18428

* man/local.mk: Adjust man page references to texinfo nodes.
* src/system.h: Adjust --help references to texinfo nodes.
---
 man/dummy-man |    2 +-
 man/local.mk  |    2 +-
 src/system.h  |    3 ++-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/man/dummy-man b/man/dummy-man
index dca2b67..bf31912 100755
--- a/man/dummy-man
+++ b/man/dummy-man
@@ -69,5 +69,5 @@ The full documentation for
 is maintained as a Texinfo manual, which should be accessible
 on your system via the command
 .IP
-.B info coreutils $bs(aq$progname invocation$bs(aq
+.B info $bs(aq(coreutils) $progname invocation$bs(aq
 END
diff --git a/man/local.mk b/man/local.mk
index f4b213f..f2d1357 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -102,7 +102,7 @@ man/dynamic-deps.mk: Makefile
 		     --source='$(PACKAGE_STRING)'			\
 		     --include=$(srcdir)/man/$$name.x			\
 		     --output=$$t/$$name.1 $$t/$$argv			\
-		     --info-page='coreutils \(aq'$$name' invocation\(aq' \
+		     --info-page='\(aq(coreutils) '$$name' invocation\(aq' \
 	  && sed \
 	       -e 's|$*\.td/||g' \
 	       -e '/For complete documentation/d' \
diff --git a/src/system.h b/src/system.h
index 162446c..00180cb 100644
--- a/src/system.h
+++ b/src/system.h
@@ -582,7 +582,8 @@ emit_ancillary_info (void)
                 last_component (program_name));
     }
   printf (_("For complete documentation, run: "
-            "info coreutils '%s invocation'\n"), last_component (program_name));
+            "info '(coreutils) %s invocation'\n"),
+          last_component (program_name));
 }
 
 static inline void
-- 
1.7.7.6

>From 0b96a07dd2576fc4a3c64aee48307f3707b38cd8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Wed, 10 Sep 2014 11:53:50 +0100
Subject: [PATCH 2/2] doc: reference online info pages directly from man pages

* src/system.h (emit_ancillary_info): Add a direct reference
to the corresponding online info documentation.  Corresponding
redirects were put in place on www.gnu.org to allow for concise links.
* 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.
---
 man/help2man |   23 +++++++++++++++++++++--
 src/system.h |   13 ++++++++-----
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/man/help2man b/man/help2man
index bfeb989..47aa2a7 100755
--- a/man/help2man
+++ b/man/help2man
@@ -405,16 +405,19 @@ s/\\/\x82/g;
 # "(?:[\\w-]+ +)?" in the bug reporting pattern is used to indicate an
 # optional word, so that either "Report bugs" or "Report _program_ bugs" will
 # be matched.
-my $PAT_BUGS          = _('Report +(?:[\w-]+ +)?bugs|Email +bug +reports +to');
+my $PAT_BUGS          = _('Report +(?:[\w-]+ +)?bugs|' .
+                          'Email +bug +reports +to|' .
+                          '.* +online +help:');
 my $PAT_AUTHOR        = _('Written +by');
 my $PAT_OPTIONS       = _('Options');
 my $PAT_ENVIRONMENT   = _('Environment');
 my $PAT_FILES         = _('Files');
 my $PAT_EXAMPLES      = _('Examples');
 my $PAT_FREE_SOFTWARE = _('This +is +free +software');
+my $PAT_SEE_ALSO      = _('Full +documentation');
 
 # Start a new paragraph (if required) for these.
-s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR) /$1\n\n$2 /og;
+s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR|$PAT_SEE_ALSO) /$1\n\n$2 /og;
 
 # Convert iso-8859-1 copyright symbol or (c) to nroff
 # character.
@@ -462,6 +465,12 @@ while (length)
 	$sect = _('AUTHOR');
     }
 
+    elsif (/^($PAT_SEE_ALSO)/o)
+    {
+	$sect = _('SEE ALSO');
+	$opt_no_info = 1;
+    }
+
     # Examples, indicated by an indented leading $, % or > are
     # rendered in a constant width font.
     if (/^( +)([\$\%>] )\S/)
@@ -588,6 +597,16 @@ while (length)
 	    #   ...
 	    s/\n([[:upper:]])/\n.br\n$1/g;
 	}
+	elsif ($sect eq _('SEE ALSO'))
+	{
+	    # Handle external references of the form:
+	    #
+	    #   GNU <package> online resources: <addr>
+	    #   Full documentation at: <addr>
+	    #   or available locally via: info ...
+	    #
+	    s/\n(.)/\n.br\n$1/g;
+	}
     }
 
     # Check if matched paragraph contains /pat/.
diff --git a/src/system.h b/src/system.h
index 00180cb..1682b32 100644
--- a/src/system.h
+++ b/src/system.h
@@ -567,7 +567,10 @@ Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT is set).\n\
 static inline void
 emit_ancillary_info (void)
 {
+  char const * program = last_component (program_name);
+
   printf (_("\n%s online help: <%s>\n"), PACKAGE_NAME, PACKAGE_URL);
+
   /* Don't output this redundant message for English locales.
      Note we still output for 'C' so that it gets included in the man page.  */
   const char *lc_messages = setlocale (LC_MESSAGES, NULL);
@@ -578,12 +581,12 @@ emit_ancillary_info (void)
          the URLs at http://translationproject.org/team/.  Otherwise, replace
          the entire URL with your translation team's email address.  */
       printf (_("Report %s translation bugs to "
-                "<http://translationproject.org/team/>\n"),
-                last_component (program_name));
+                "<http://translationproject.org/team/>\n"), program);
     }
-  printf (_("For complete documentation, run: "
-            "info '(coreutils) %s invocation'\n"),
-          last_component (program_name));
+  printf (_("Full documentation at: <%s%s>\n"),
+          PACKAGE_URL, program);
+  printf (_("or available locally via: info '(coreutils) %s invocation'\n"),
+          program);
 }
 
 static inline void
-- 
1.7.7.6