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

2009-09-19 Thread Pádraig Brady
Jim Meyering wrote:
 Pádraig Brady wrote:
 Eric Blake wrote:
 According to Pádraig Brady on 9/18/2009 8:21 AM:
 I'd vote for removing the translation help line unconditionally
 Hmm.  The GNU Coding Standards don't mention the translation bug report
 line, but the gettext manual recommends including it for any program with
 i18n output.  After all, translation bugs really are better directed to
 the language team that had the translation issue, rather than the
 developer that can't even understand the language in question.
 Hmm, I wary about adding too much text.

 Perhaps we should leave things as they are.
 If someone is looking for more info than is given in --help
 they'll look at the man page from which they'll be directed
 to the texinfo docs.

 I can, however, agree that the translation line does not add much in the C
 locale, and probably not in en_ locales.
 Note currently the translation line is not added in the C locale
 (and hence is not in the default man pages).
 
 I confess that I am not quite sure that removing the translation
 line is a good move.
 
 What do you think about suppressing it also for en* locales
 instead of removing it altogether?
 
 An alternative: don't emit it into --help, but do insert it
 into the man page.

OK I'll update the patch to add the translation line
if strncmp(LC_MESSAGES, en_, 3). I.E. the unusual case
of LC_MESSAGES=C will get the translation message, which
will mean it's included in the man page also.

cheers,
Pádraig.





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

2009-09-18 Thread C de-Avillez
On Thu, 2009-09-17 at 11:59 -0700, Micah Cowan wrote:
 -BEGIN PGP SIGNED MESSAGE-
 Hash: SHA1
 
 C de-Avillez wrote:
  So. Would it be an acceptable idea to add, to the '--help', a warning
  that this is *not* the full documentation?
  
  Say, like:
  
  This is an abridged documentation. The full documentation for blahblah
  is maintained as a Texinfo manual. If the info and date programs are
  properly installed at your site, the command
  
info coreutils 'blahblah invocation'
  
 should give you access to the complete manual.
 
 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?

Cheers



signature.asc
Description: This is a digitally signed message part


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

2009-09-18 Thread Jim Meyering
C de-Avillez wrote:

 On Thu, 2009-09-17 at 11:59 -0700, Micah Cowan wrote:
 -BEGIN PGP SIGNED MESSAGE-
 Hash: SHA1

 C de-Avillez wrote:
  So. Would it be an acceptable idea to add, to the '--help', a warning
  that this is *not* the full documentation?
 
  Say, like:
 
  This is an abridged documentation. The full documentation for blahblah
  is maintained as a Texinfo manual. If the info and date programs are
  properly installed at your site, the command
 
info coreutils 'blahblah invocation'
 
 should give you access to the complete manual.

 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?

I'm tempted to say add a one-liner, but there are already *four*
lines at the end of even the smallest --help output message, e.g.,

$ sync --help
Usage: sync [OPTION]
Force changed blocks to disk, update the super block.

  --help display this help and exit
  --version  output version information and exit

Report sync bugs to bug-coreutils@gnu.org
GNU coreutils home page: http://www.gnu.org/software/coreutils/
General help using GNU software: http://www.gnu.org/gethelp/
Report sync translation bugs to http://translationproject.org/team/

I guess you'd like to see this added:

  For complete documentation, run info coreutils 'sync invocation'

Maybe.
Though I'm tempted to remove the Report ... translation bugs...
line when using the C (or maybe all of en_*, too) locale.

Other opinions?




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

2009-09-18 Thread Jim Meyering
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.




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

2009-09-18 Thread C de-Avillez
On Fri, 18 Sep 2009 17:34:31 +0200
Jim Meyering j...@meyering.net 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 hgg...@ubuntu.com
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

---
 src/system.h |   13 ++---
 1 files changed, 2 insertions(+), 11 deletions(-)

diff --git a/src/system.h b/src/system.h
index a15c298..1ecdcff 100644
--- a/src/system.h
+++ b/src/system.h
@@ -646,17 +646,8 @@ 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
-- 
1.6.3.3



signature.asc
Description: PGP signature


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

2009-09-18 Thread Pádraig Brady
C de-Avillez wrote:
 On Fri, 18 Sep 2009 17:34:31 +0200
 Jim Meyering j...@meyering.net 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 hgg...@ubuntu.com
 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?= p...@draigbrady.com
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





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

2009-09-18 Thread Eric Blake
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

According to Pádraig Brady on 9/18/2009 8:21 AM:
 I'd vote for removing the translation help line unconditionally

Hmm.  The GNU Coding Standards don't mention the translation bug report
line, but the gettext manual recommends including it for any program with
i18n output.  After all, translation bugs really are better directed to
the language team that had the translation issue, rather than the
developer that can't even understand the language in question.

I can, however, agree that the translation line does not add much in the C
locale, and probably not in en_ locales.

- --
Don't work too hard, make some time for fun as well!

Eric Blake e...@byu.net
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkq0EFIACgkQ84KuGfSFAYAVQACgku+I609SvnCe1GV3gR5eHbG/
pccAnRr0cDob8rdmidMUOttcF3IqtrQ1
=pkPz
-END PGP SIGNATURE-




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

2009-09-18 Thread C de-Avillez
On Fri, 18 Sep 2009 23:42:31 +0100
Pádraig Brady p...@draigbrady.com wrote:

 -emit_bug_reporting_address (void)
 +emit_ancillary_info (void)

Hi Pádraig,

Thank you for getting the details done. Well, it really seems I still
have a lot to learn on coreutils.

But there is an issue in the change above: pretty much all sources
have, hardcoded, calls to emit_bug_reporting_address. So, the end
result:

1. a lot of warnings like below (well, 'hard_locale' happens only
about 10 times):

who.c: In function 'usage':
who.c:668: warning: implicit declaration of function 
'emit_bug_reporting_address'
who.c: In function 'main':
who.c:791: warning: implicit declaration of function 'hard_locale'

2. since the modules are hardcoded to emit_bug_reporting_address, the
new message does not appear in the --help output;

3. on the other hand, it seems the Perl change is OK ;-)

Sorry, my presence is being required at the dinner table.

Cheers,


signature.asc
Description: PGP signature


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

2009-09-18 Thread Pádraig Brady
Eric Blake wrote:
 According to Pádraig Brady on 9/18/2009 8:21 AM:
 I'd vote for removing the translation help line unconditionally
 
 Hmm.  The GNU Coding Standards don't mention the translation bug report
 line, but the gettext manual recommends including it for any program with
 i18n output.  After all, translation bugs really are better directed to
 the language team that had the translation issue, rather than the
 developer that can't even understand the language in question.

Hmm, I wary about adding too much text.

Perhaps we should leave things as they are.
If someone is looking for more info than is given in --help
they'll look at the man page from which they'll be directed
to the texinfo docs.

 I can, however, agree that the translation line does not add much in the C
 locale, and probably not in en_ locales.

Note currently the translation line is not added in the C locale
(and hence is not in the default man pages).

cheers,
Pádraig.




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

2009-09-18 Thread Pádraig Brady
C de-Avillez wrote:
 On Fri, 18 Sep 2009 23:42:31 +0100
 Pádraig Brady p...@draigbrady.com wrote:
 
 -emit_bug_reporting_address (void)
 +emit_ancillary_info (void)
 
 Hi Pádraig,
 
 Thank you for getting the details done. Well, it really seems I still
 have a lot to learn on coreutils.
 
 But there is an issue in the change above: pretty much all sources
 have, hardcoded, calls to emit_bug_reporting_address.

Sorry, the last was an abridged patch for quick review.
Full patch attached.

cheers,
Pádraig.

From 7147430636c9fa773718839ac8d3ee943a33dd75 Mon Sep 17 00:00:00 2001
From: =?utf-8?q?P=C3=A1draig=20Brady?= p...@draigbrady.com
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
---
 man/help2man|6 ++
 src/base64.c|2 +-
 src/basename.c  |2 +-
 src/cat.c   |2 +-
 src/chcon.c |2 +-
 src/chgrp.c |2 +-
 src/chmod.c |2 +-
 src/chown.c |2 +-
 src/chroot.c|2 +-
 src/cksum.c |2 +-
 src/comm.c  |3 ++-
 src/cp.c|2 +-
 src/csplit.c|2 +-
 src/cut.c   |2 +-
 src/date.c  |2 +-
 src/dd.c|2 +-
 src/df.c|2 +-
 src/dircolors.c |2 +-
 src/dirname.c   |2 +-
 src/du.c|2 +-
 src/echo.c  |2 +-
 src/env.c   |2 +-
 src/expand.c|2 +-
 src/expr.c  |2 +-
 src/factor.c|2 +-
 src/fmt.c   |2 +-
 src/fold.c  |2 +-
 src/getlimits.c |2 +-
 src/groups.c|2 +-
 src/head.c  |2 +-
 src/hostid.c|2 +-
 src/hostname.c  |2 +-
 src/id.c|2 +-
 src/install.c   |2 +-
 src/join.c  |3 ++-
 src/kill.c  |2 +-
 src/link.c  |2 +-
 src/ln.c|2 +-
 src/logname.c   |2 +-
 src/ls.c|3 ++-
 src/md5sum.c|2 +-
 src/mkdir.c |2 +-
 src/mkfifo.c|2 +-
 src/mknod.c |2 +-
 src/mktemp.c|2 +-
 src/mv.c|2 +-
 src/nice.c  |2 +-
 src/nl.c|2 +-
 src/nohup.c |2 +-
 src/od.c|2 +-
 src/paste.c |2 +-
 src/pathchk.c   |2 +-
 src/pinky.c |3 ++-
 src/pr.c|3 ++-
 src/printenv.c  |2 +-
 src/printf.c|2 +-
 src/ptx.c   |2 +-
 src/pwd.c   |2 +-
 src/readlink.c  |2 +-
 src/rm.c|2 +-
 src/rmdir.c |2 +-
 src/runcon.c|2 +-
 src/seq.c   |2 +-
 src/setuidgid.c |2 +-
 src/shred.c |2 +-
 src/shuf.c  |2 +-
 src/sleep.c |2 +-
 src/sort.c  |3 ++-
 src/split.c |2 +-
 src/stat.c  |2 +-
 src/stdbuf.c|2 +-
 src/stty.c  |2 +-
 src/su.c|2 +-
 src/sum.c   |2 +-
 src/sync.c  |2 +-
 src/system.h|   17 -
 src/tac.c   |2 +-
 src/tail.c  |2 +-
 src/tee.c   |2 +-
 src/test.c  |2 +-
 src/timeout.c   |2 +-
 src/touch.c |2 +-
 src/tr.c|2 +-
 src/true.c  |2 +-
 src/truncate.c  |2 +-
 src/tsort.c |2 +-
 src/tty.c   |2 +-
 src/uname.c |2 +-
 src/unexpand.c  |2 +-
 src/uniq.c  |3 ++-
 src/unlink.c|2 +-
 src/uptime.c|2 +-
 src/users.c |2 +-
 src/wc.c|2 +-
 src/who.c   |3 ++-
 src/whoami.c|2 +-
 src/yes.c   |2 +-
 97 files changed, 113 insertions(+), 108 deletions(-)

diff --git a/man/help2man b/man/help2man
index 7b7ce7a..3b19c64 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/base64.c b/src/base64.c
index c7cf034..0bca87c 100644
--- a/src/base64.c
+++ b/src/base64.c
@@ -81,7 +81,7 @@ When decoding, the input may contain newlines in addition to the bytes of\n\
 the formal base64 alphabet.  Use --ignore-garbage to attempt to recover\n\
 from any other non-alphabet bytes in the encoded stream.\n),
  stdout);
-  emit_bug_reporting_address ();
+  

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

2009-09-18 Thread Jim Meyering
Pádraig Brady wrote:
...
 Subject: [PATCH] doc: mention the texinfo documentation in --help

Thanks!
Good catch on moving hard-locale.h inclusions back.

 * 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
...
 diff --git a/man/help2man b/man/help2man
...
 +my $PAT_INFO = _('For +complete +documentation');

You might want to make this regexp more specific,
just in case, to avoid accidentally filtering out
unrelated lines.  Then again maybe not ;-)
I have a hard time imagining a sentence starting
like that in --help that should *not* be filtered out.

  # 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));
  }




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

2009-09-18 Thread Jim Meyering
Pádraig Brady wrote:
 Eric Blake wrote:
 According to Pádraig Brady on 9/18/2009 8:21 AM:
 I'd vote for removing the translation help line unconditionally

 Hmm.  The GNU Coding Standards don't mention the translation bug report
 line, but the gettext manual recommends including it for any program with
 i18n output.  After all, translation bugs really are better directed to
 the language team that had the translation issue, rather than the
 developer that can't even understand the language in question.

 Hmm, I wary about adding too much text.

 Perhaps we should leave things as they are.
 If someone is looking for more info than is given in --help
 they'll look at the man page from which they'll be directed
 to the texinfo docs.

 I can, however, agree that the translation line does not add much in the C
 locale, and probably not in en_ locales.

 Note currently the translation line is not added in the C locale
 (and hence is not in the default man pages).

I confess that I am not quite sure that removing the translation
line is a good move.

What do you think about suppressing it also for en* locales
instead of removing it altogether?

An alternative: don't emit it into --help, but do insert it
into the man page.




(man|info) pages and --help

2009-09-17 Thread C de-Avillez
c.f.: https://bugs.launchpad.net/bugs/430953

I have been thinking about this, and discussed it a bit on our (Ubuntu)
bugs IRC channel (#ubuntu-bugs).

I understand the move to 'info', and the decision to make the man pages
a summary, taken off the '--help'. But, to old UNIX users -- those that
were taught 'read the man page' -- and mostly to users that use other
systems, like AIX, HP/UX, Solaris, etc, the idea of looking at 'info'
will not occur.

Hell, I myself every so often forget about it.

So. Would it be an acceptable idea to add, to the '--help', a warning
that this is *not* the full documentation?

Say, like:

This is an abridged documentation. The full documentation for blahblah
is maintained as a Texinfo manual. If the info and date programs are
properly installed at your site, the command

  info coreutils 'blahblah invocation'

   should give you access to the complete manual.

Thank you.

..Carl..


 


signature.asc
Description: This is a digitally signed message part


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

2009-09-17 Thread Micah Cowan
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

C de-Avillez wrote:
 So. Would it be an acceptable idea to add, to the '--help', a warning
 that this is *not* the full documentation?
 
 Say, like:
 
 This is an abridged documentation. The full documentation for blahblah
 is maintained as a Texinfo manual. If the info and date programs are
 properly installed at your site, the command
 
   info coreutils 'blahblah invocation'
 
should give you access to the complete manual.

Is there anyone who's unaware that --help doesn't provide complete
documentation? I can't think of any program that provides complete
document via --help; the closest is software like Subversion, Git or
Mercurial, where they provide you access to extensive documentation via
svn help command-style inquiries. Indeed, the whole point behind
- --help is usually to generate very brief usage information. Though a
shorter, one-sentence message directing the user to the full Texinfo
documentation could be useful.

- --
Micah J. Cowan
Programmer, musician, typesetting enthusiast, gamer.
Maintainer of GNU Wget and GNU Teseq
http://micah.cowan.name/
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkqyhyYACgkQ7M8hyUobTrEoSwCdHodPi2KGyRoodcQIPaK62wGw
cHEAnj7sNx0iGvaIo+nLU2kgP8SDIX9W
=ssgG
-END PGP SIGNATURE-