Re: (man|info) pages and --help

[Pádraig Brady]

C de-Avillez wrote:
> On Fri, 18 Sep 2009 17:34:31 +0200
> Jim Meyering <address@hidden> wrote:
> 
>> Pádraig Brady wrote:
>>
>>> Alfred M. Szmidt wrote:
>>>>    > Is there anyone who's unaware that --help doesn't provide
>>>>    > complete documentation?
>>>>
>>>>    I would not expect anyone to *not* know that help output is
>>>>    abridged.  But I would rather have them go straight into 'info'
>>>>    than wasting time on 'man', only to be redirected to 'info'.
>>>>
>>>>    Usually one looks at the '--help' output first. If we redirect
>>>> on 'man', why not there?
>>>>
>>>> Because man pages are secondary on GNU systems, the offical spot
>>>> has always been info.  The redirection is only for convience for
>>>> old timers who still use man.
>>> While that may be the official line, practically nobody reads info
>>> pages, and if they do it's indirectly through google.
>>>
>>> I'd vote for removing the translation help line unconditionally
>>> (I notice it's not mentioned in man pages) and replace with:
>>>
>>> For complete documentation, run: info coreutils '$cmd invocation'
>> Seconded.
> 
> Is this, then, good?
> 
> From c16d6e93cdc94e890ad653d4caa994ea4c315a50 Mon Sep 17 00:00:00 2001
> From: C de-Avillez <address@hidden>
> Date: Fri, 18 Sep 2009 12:16:50 -0500
> Subject: [PATCH] --help: link to 'info' for complete docs
>  * src/system.h:
>    - take out the translation line
>    - add a reference to 'info' for complete documentation

We also need to tweak help2man and I've changed the
function name in system.h since we're now not just
outputting bug addresses. The interesting part of
the patch is below. I'd appreciate a quick review of
the perl change in help2man.

cheers,
Pádraig.

From: =?utf-8?q?P=C3=A1draig=20Brady?= <address@hidden>
Date: Fri, 18 Sep 2009 23:06:21 +0100
Subject: [PATCH] doc: mention the texinfo documentation in --help

* src/system.h: Rename emit_bug_reporting_address() to
emit_ancillary_info() and update it to remove the translation
project address and instead mention how to invoke the
texinfo documentation for each command.  Also move the
"hard-locale.h" include to the 8 files that now use it.
* man/help2man: Strip the newly added texinfo reference from the
--help output as a more verbose version is already added by help2man.
Suggestion from C de-Avillez
---
 97 files changed, 113 insertions(+), 108 deletions(-)

diff --git a/man/help2man b/man/help2man
index 7b7ce7a..9a15eaf 100755
--- a/man/help2man
+++ b/man/help2man
@@ -373,6 +373,7 @@ my $PAT_AUTHOR              = _('Written +by');
 my $PAT_OPTIONS                = _('Options');
 my $PAT_EXAMPLES       = _('Examples');
 my $PAT_FREE_SOFTWARE  = _('This +is +free +software');
+my $PAT_INFO           = _('For +complete +documentation');

 # Start a new paragraph (if required) for these.
 s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR)/$1\n\n$2/og;
@@ -392,6 +393,11 @@ while (length)
        $sect = _('EXAMPLES');
        next;
     }
+    # Skip any texinfo reference as that's handled separately
+    if (s/($PAT_INFO).*\n//o)
+    {
+       next;
+    }

     # Copyright section
     if (/^Copyright +[(\xa9]/)
diff --git a/src/system.h b/src/system.h
index a15c298..a81020c 100644
--- a/src/system.h
+++ b/src/system.h
@@ -635,9 +635,8 @@ Otherwise, units default to 1024 bytes (or 512 if 
POSIXLY_CORRECT is set).\n\
 "), program);
 }

-#include "hard-locale.h"
 static inline void
-emit_bug_reporting_address (void)
+emit_ancillary_info (void)
 {
   printf (_("\nReport %s bugs to %s\n"), last_component (program_name),
           PACKAGE_BUGREPORT);
@@ -646,17 +645,9 @@ emit_bug_reporting_address (void)
           PACKAGE_NAME, PACKAGE);
   fputs (_("General help using GNU software: <http://www.gnu.org/gethelp/>\n"),
          stdout);
-
-  if (hard_locale (LC_MESSAGES))
-    {
-      /* TRANSLATORS: Replace LANG_CODE in this URL with your language code
-         <http://translationproject.org/team/LANG_CODE.html> to form one of
-         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));
-    }
+  printf (_("\
+For complete documentation, run: info coreutils '%s invocation'\n\
+"), last_component (program_name));
 }

 #include "inttostr.h"