Re: coreutils FAQ link in manpages and/or --help output

[Pádraig Brady]

On 02/25/2013 11:23 PM, Assaf Gordon wrote:
> Philipp Thomas wrote, On 02/25/2013 01:18 PM:
>> Am 25.02.13 19:07, schrieb Pádraig Brady:
>>
>>> $ truncate --help | tail -n4
>>> GNU coreutils online help: <http://www.gnu.org/software/coreutils/#help>
>>> For complete documentation, run: info coreutils 'truncate invocation'
>>>
>>> Then the "online help section" can verbosely list,
>>> bug email, faq, online manual, ... without restrictions to screen width etc.
>>
>> +1 from me
> 
> I also like this idea very much.
> 
> But I'd go a step further, and ask to make the Coreutils webpage more 
> approachable.
> The current page ( http://www.gnu.org/software/coreutils/ ) is no-doubt 
> exhaustive 
> and accurate - but I find it a bit un-inviting:
> Each section has a long paragraph, and one needs to read a lot of each to get 
> to the relevant links.
> I humbly think it sacrifices being helpful for being very detailed and 
> technical.
> 
> If we're adding a new "help" section, perhaps consider something like the 
> following, which is a short bullet-list of all the important links, with the 
> first word being a verb indicating what to do.
> There will be some (a lot?) of redundancy between the "Quick help" and the 
> rest of the page, but for new-comers, or people who need help and don't want 
> to read long English text, it might be more helpful?
> 
> 
> ===
> Getting Help
> 
> * Check Questions and Answers for common problems: Coreutils FAQ<URL>
>       
> * Search the archives for previous questions and answers:
>    * coreutils Mailing list<URL> - General usage and advice
>    * bug-coreutils Mailing List<URL> - Bug reports
> 
> * Send general questions to: address@hidden
>   (Please check the FAQ & mailing-list archives above before sending 
>    questions, many common questions have already been answered in details).
> 
> * Read the complete manual (HTML<URL>, PDF<URL>).
> 
> * To see program usage information, run the following on your terminal:
>     man sort      (to see the 'sort' program brief manual page)
>     info sort     (to see the 'sort' program complete manual page)
> 
> * If you think you found a bug with a GNU coreutils program, please send it 
> to address@hidden.
>   Before sending the bug, please consult the FAQ and Mailing list archives 
> (above) - 
>   many times these perceived bugs are simply due to wrong program usage.
>   To learn more about reporting bugs, see Getting help with GNU software<URL>.
> ===

I've adjusted the above to only reference online resources,
and ensure the links are at the end of each line.
The result is now at http://www.gnu.org/software/coreutils/

The corresponding commit to reduce the amount of info
printed at the bottom of each --help is as follows.
Note I didn't bother with the #help id (I left it in the page though)
since I've added this to the top of the page, as it's generally
helpful to have those links at the top of the page anyway.

thanks,
Pádraig.

commit c3c490bab73a07f2c7ee34e2b2aaf8c1f12224a2
Author: Pádraig Brady <address@hidden>
Date:   Thu Feb 28 02:07:28 2013 +0000

    doc: move some of the info from all --help message online

    * src/system.h (emit_ancillary_info): Link to the bug report email
    addresses and general help URLs oneline rather than specifying directly.
    This give us greater scope to present better info like describing
    the difference between address@hidden and address@hidden etc.

diff --git a/src/system.h b/src/system.h
index 0605a2f..94c968f 100644
--- a/src/system.h
+++ b/src/system.h
@@ -564,11 +564,7 @@ Otherwise, units default to 1024 bytes (or 512 if 
POSIXLY_CORRECT is set).\n\
 static inline void
 emit_ancillary_info (void)
 {
-  printf (_("\nReport %s bugs to %s\n"), last_component (program_name),
-          PACKAGE_BUGREPORT);
-  printf (_("%s home page: <%s>\n"), PACKAGE_NAME, PACKAGE_URL);
-  fputs (_("General help using GNU software: <http://www.gnu.org/gethelp/>\n"),
-         stdout);
+  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);