GNU bug report logs - #18428
coreutils binary breaks coreutils documentation

Previous Next

Full log

View this message in rfc822 format

From: Pádraig Brady <P <at> draigBrady.com>
To: Michael Stone <mstone <at> debian.org>
Cc: 18428 <at> debbugs.gnu.org, 760861 <at> bugs.debian.org, Bob Proulx <bob <at> proulx.com>
Subject: bug#18428: Bug#760861: bug#18428: coreutils binary breaks coreutils documentation
Date: Tue, 09 Sep 2014 15:31:35 +0100

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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.