bug#18428: Bug#760861: bug#18428: coreutils binary breaks coreutils documentation

[Pádraig Brady]

On 09/09/2014 01:51 PM, Michael Stone wrote:
> On Mon, Sep 08, 2014 at 06:10:35PM -0600, Bob Proulx wrote:
>> But I think in recent years the install-info problems have been fixed.
>> Perhaps we don't need to do any of this anymore?  Or perhaps finally
>> getting to the canonical (FILENAME)NODE-WITHIN-FILE form we have
>> finally arrived at the end and should stop there.
> 
> The real solution is to stop pretending that the info documentation is useful.

It's useful to many, but I agree most don't bother with it
due to the awkward non intuitive default info reader _interface_
(though pinfo is a bit better in that regard).

I guess it comes down to people wanting quick notes in the shell
for which they use man, and for longer reading/research they prefer the browser.
As the info _content_ is available for the latter online, this is why I remained
focused in keeping the content up to date and complete.

> We get a lot of bug reports about the man pages & help output, not so many 
> about the info docs. It could be because the info docs are perfect, I suspect 
> it's because they're rarely consulted.

I contend the content is fine and good, though the terminal interface is
generally not used.

> Sometimes we can point to the info doc and close a man page bug with a 
> satisfied sense
> of "they should have read the documentation". But I'm just not sure that 
> documentation
> that seems to exist solely to win a fight over whether behavior is documented 
> is actually helpful.

Agreed.

> Maybe point people at 
> https://www.gnu.org/software/coreutils/manual/html_node/ ?

Personally I use this function:

  cinfo() { xdg-open 
"http://www.gnu.org/software/coreutils/manual/html_node/$1-invocation.html#$1-invocation";;
 }

which I use like `cinfo dd`, though that's another command and not
portable enough currently.

Recently enough we have directed users more to the online info
in the --help output of all commands like:

  GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
  For complete documentation, run: info '(coreutils) ls invocation'

compared to the man page trailer of:
    GNU  coreutils  online  help:  <http://www.gnu.org/software/coreutils/>
  ....
  SEE ALSO
    The full documentation for ls is maintained as a  Texinfo  manual.   If
    the  info and ls programs are properly installed at your site, the command
           info coreutils 'ls invocation'
    should give you access to the complete manual.

Though it would be better to have direct links.
Now the above full node URL is too long/awkward, so I've just now setup 
redirects,
so the following proposed new trailers for ls --help and man pages should work:

ls --help:
  ...
  Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
  Full installed documentation: info '(coreutils) ls invocation'

man ls:
  ...
  SEE ALSO
    Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
    Full installed documentation: info '(coreutils) ls invocation'

> Even better would be if it were interactive. E.g., the postgresql project has 
> some really
> nice online docs per-version which allow people to add comments: 
> http://www.postgresql.org/docs/9.3/interactive/index.html

Something to consider for the future.

thanks,
Pádraig.