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

[Assaf Gordon]

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>.
===


And in HTML
===
<h3><a name="help">Getting Help</a></h3>                                        
                                                                                
<ul class="help-list">                                                          
<!-- FAQ -->                                                                    
<li>Check Questions and Answers for common problems:                            
<a 
href="http://www.gnu.org/software/coreutils/faq/coreutils-faq.html";>Coreutils 
FAQ</a>
</li>                                                                           
                                                                                
<!-- Search Mailing lists -->                                                   
<li>Search the archives for previous questions and answers:                     
  <ul>                                                                          
    <li><a href="http://lists.gnu.org/archive/html/coreutils/";>coreutils 
Mailing list</a> -
     General usage and advice</li>                                              
     <li><a 
href="http://lists.gnu.org/archive/html/bug-coreutils/";>bug-coreutils Mailing 
List</a> -
     Bug reports</li>                                                           
  </ul>                                                                         
</li>                                                                           
                                                                                
<!-- address@hidden -->                                                      
<li>Send general questions to: <a 
href="mailto:address@hidden";>address@hidden</a><br/>
(Please check the FAQ &amp; mailing-list archives above before sending 
questions, many common questions have already been answered in details).
</li>                                                                           
                                                                                
<!-- Coreutils Manual -->                                                       
<li>                                                                            
Read the complete <a 
href="http://www.gnu.org/software/coreutils/manual/";>manual</a>
 (<a 
href="http://www.gnu.org/software/coreutils/manual/coreutils.html";>HTML</a>,
<a href="http://www.gnu.org/software/coreutils/manual/coreutils.pdf";>PDF</a>).  
</li>                                                                           
                                                                                
<!-- man/info pages -->                                                         
<li>                                                                            
To see program usage information, run the following on your terminal:           
<pre>                                                                           
<samp>                                                                          
man sort      (to see the 'sort' program brief manual page)                     
info sort     (to see the 'sort' program complete manual page)                  
</samp>                                                                         
</pre>                                                                          
</li>                                                                           
                                                                                
<!-- address@hidden -->                                                  
<li>                                                                            
If you think you found a bug with a GNU coreutils program, please send it to <a 
href="mailto:address@hidden";>address@hidden</a>. 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 <a href="http://www.gnu.org/help/gethelp.html";>Getting help with GNU 
software</a>.
</li>                                                                           
</ul>
===


-gordon