Re: (man|info) pages and --help
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
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
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
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
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
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
-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
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
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
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
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
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
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
-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-