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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 18428 in the body.
You can then email your comments to 18428 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: bug-coreutils <at> gnu.org
Subject: coreutils binary breaks coreutils documentation
Date: Mon, 8 Sep 2014 11:26:52 -0600

Vincent Lefevre reported to the Debian BTS that the new documentation
shipped for the recently added coreutils binary breaks the existing
documentation for all of the coreutils utilities.

  https://bugs.debian.org/760861

Confirmed.  Perhaps the documentation node name can be changed to be
something non-conflicting with the package name?  Or perhaps only
conditionally built if the binary is built?  Or Vincent's suggestion
to use upper case.  Or...?

If correspondents wish their responses logged to the Debian bug log
please add 760861 <at> bugs.debian.org to the email recipients list.  (Two
BTS instances are a little difficult to stitch together until both bug
numbers are known.)

Bob

Original Debian report by Vincent Lefevre follows:

Subject: coreutils: in man pages, info invocation is incorrect: replace coreutils by Coreutils
Package: coreutils
Version: 8.23-2
Severity: minor

For instance, in the touch(1) man page:

  The full documentation for touch is maintained as a Texinfo manual.  If
  the info and touch programs are properly installed at  your  site,  the
  command

         info coreutils 'touch invocation'

  should give you access to the complete manual.

This is now incorrect (as of 8.23?), because it gives the page:

2.14 ‘coreutils’: Multi-call binary
===================================

‘coreutils’ invokes an individual utility, either implicitly selected by
the last component of ‘argv[0]’, or by explicitly calling ‘coreutils’
with the ‘--coreutils-prog’ option.  Synopsis:

     coreutils --coreutils-prog=PROGRAM …

The correct info invocation now is:

    info Coreutils 'touch invocation'

Note: Since the coreutils utility doesn't seem to exist in Debian, this
section could be removed, but this problem may reappear in the future.
So, it's better to use the capital letter C.

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: bug-coreutils <at> gnu.org
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Mon, 08 Sep 2014 20:12:40 +0200

Bob Proulx <bob <at> proulx.com> writes:

> For instance, in the touch(1) man page:
>
>   The full documentation for touch is maintained as a Texinfo manual.  If
>   the info and touch programs are properly installed at  your  site,  the
>   command
>
>          info coreutils 'touch invocation'
>
>   should give you access to the complete manual.
>
> This is now incorrect (as of 8.23?), because it gives the page:

"info touch" still works, which is equivalent to "info '(coreutils)touch
invocation'".

> Note: Since the coreutils utility doesn't seem to exist in Debian, this
> section could be removed, but this problem may reappear in the future.
> So, it's better to use the capital letter C.

Having info dir entries only differing in case seems like a bad idea.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #11 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 18428 <at> debbugs.gnu.org, 760861 <at> bugs.debian.org
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Mon, 08 Sep 2014 20:30:01 +0100

On 09/08/2014 07:12 PM, Andreas Schwab wrote:
> Bob Proulx <bob <at> proulx.com> writes:
> 
>> For instance, in the touch(1) man page:
>>
>>   The full documentation for touch is maintained as a Texinfo manual.  If
>>   the info and touch programs are properly installed at  your  site,  the
>>   command
>>
>>          info coreutils 'touch invocation'
>>
>>   should give you access to the complete manual.
>>
>> This is now incorrect (as of 8.23?), because it gives the page:
> 
> "info touch" still works, which is equivalent to "info '(coreutils)touch
> invocation'".
> 
>> Note: Since the coreutils utility doesn't seem to exist in Debian, this
>> section could be removed, but this problem may reappear in the future.
>> So, it's better to use the capital letter C.
> 
> Having info dir entries only differing in case seems like a bad idea.

I agree.

We could rename the node, but the bracketed form works well
without the need for any extra quoting. I.E. this is unambiguous:

  info '(coreutils) stat invocation'

The following simple patch implements that.

thanks,
Pádraig.

diff --git a/src/system.h b/src/system.h
index 162446c..00180cb 100644
--- a/src/system.h
+++ b/src/system.h
@@ -582,7 +582,8 @@ emit_ancillary_info (void)
                 last_component (program_name));
     }
   printf (_("For complete documentation, run: "
-            "info coreutils '%s invocation'\n"), last_component (program_name));
+            "info '(coreutils) %s invocation'\n"),
+          last_component (program_name));
 }

Message #14 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 18428 <at> debbugs.gnu.org, 760861 <at> bugs.debian.org
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Mon, 08 Sep 2014 22:27:29 +0100

On 09/08/2014 08:30 PM, Pádraig Brady wrote:
> On 09/08/2014 07:12 PM, Andreas Schwab wrote:
>> Bob Proulx <bob <at> proulx.com> writes:
>>
>>> For instance, in the touch(1) man page:
>>>
>>>   The full documentation for touch is maintained as a Texinfo manual.  If
>>>   the info and touch programs are properly installed at  your  site,  the
>>>   command
>>>
>>>          info coreutils 'touch invocation'
>>>
>>>   should give you access to the complete manual.
>>>
>>> This is now incorrect (as of 8.23?), because it gives the page:
>>
>> "info touch" still works, which is equivalent to "info '(coreutils)touch
>> invocation'".
>>
>>> Note: Since the coreutils utility doesn't seem to exist in Debian, this
>>> section could be removed, but this problem may reappear in the future.
>>> So, it's better to use the capital letter C.
>>
>> Having info dir entries only differing in case seems like a bad idea.
> 
> I agree.
> 
> We could rename the node, but the bracketed form works well
> without the need for any extra quoting. I.E. this is unambiguous:
> 
>   info '(coreutils) stat invocation'
> 
> The following simple patch implements that.

Another advantage of this more canonical form
is that the pinfo curses info viewer can parse it.

Pádraig.

Message #17 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: 18428 <at> debbugs.gnu.org, Andreas Schwab <schwab <at> linux-m68k.org>
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Mon, 8 Sep 2014 17:48:01 -0600

Andreas Schwab wrote:
> Bob Proulx <bob <at> proulx.com> writes:
> > For instance, in the touch(1) man page:
> >
> >   The full documentation for touch is maintained as a Texinfo manual.  If
> >   the info and touch programs are properly installed at  your  site,  the
> >   command
> >
> >          info coreutils 'touch invocation'
> >
> >   should give you access to the complete manual.
> >
> > This is now incorrect (as of 8.23?), because it gives the page:
...
> > Note: Since the coreutils utility doesn't seem to exist in Debian, this
> > section could be removed, but this problem may reappear in the future.
> > So, it's better to use the capital letter C.

Just for the record the above was written by Vincent Lefevre in his
original bug report and was not written by me.  In the above I was
simply forwarding the report.

Bob

Message #20 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: 18428 <at> debbugs.gnu.org, 760861 <at> bugs.debian.org,
 Vincent Lefevre <vincent <at> vinc17.net>
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Mon, 8 Sep 2014 18:10:35 -0600

Pádraig Brady wrote:
> Andreas Schwab wrote:
> > Bob Proulx writes:

Not me!  :-)  It was Vincent Lefevre who wrote:

> >> This is now incorrect (as of 8.23?), because it gives the page:
> > 
> > "info touch" still works, which is equivalent to "info '(coreutils)touch
> > invocation'".

I was previously unaware of the parenthetical form.

> >> Note: Since the coreutils utility doesn't seem to exist in Debian, this
> >> section could be removed, but this problem may reappear in the future.
> >> So, it's better to use the capital letter C.
> > 
> > Having info dir entries only differing in case seems like a bad idea.
> 
> I agree.

I agree too.

> We could rename the node, but the bracketed form works well
> without the need for any extra quoting. I.E. this is unambiguous:
> 
>   info '(coreutils) stat invocation'

I had not been aware of the parenthetical form.  I read through the
info documentation and found this concerning the Emacs internal info
browser:

     A node name has two forms.  A node in the current file is named by
  what appears after the `Node: ' in that node's first line.  For
  example, this node's name is `Add'.  A node in another file is named by
  `(FILENAME)NODE-WITHIN-FILE', as in `(info)Add' for this node.  If the
  file name starts with `./', then it is relative to the current
  directory; otherwise, it is relative starting from the standard
  directory for Info files of your site.  The name `(FILENAME)Top' can be
  abbreviated to just `(FILENAME)'.  By convention, the name `Top' is used
  for the "highest" node in any single file--the node whose `Up' points
  out of the file.  The `Directory' node is `(dir)', it points to a file
  `dir' which holds a large menu listing all the Info documents installed
  on your site.  The `Top' node of a document file listed in the
  `Directory' should have an `Up: (dir)' in it.

I didn't find any other documentation of the format but that appears
to be explicit and it does work.

> The following simple patch implements that.

Seems like the best choice to me.

Note that IIRC originally the pointer was:

  info touch

But that failed due to shortcomings in variously implemented
install-info commands that I don't remember now.  Therefore this was
changed to "info -f coreutils touch" IIRC and then later mutated again
to "info coreutils 'touch invocation'" to get more canonical.

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.

Bob

Message #23 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Vincent Lefevre <vincent <at> vinc17.net>
To: Bob Proulx <bob <at> proulx.com>
Cc: 18428 <at> debbugs.gnu.org, 760861 <at> bugs.debian.org
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Tue, 9 Sep 2014 02:32:53 +0200

On 2014-09-08 18:10:35 -0600, Bob Proulx wrote:
> Note that IIRC originally the pointer was:
> 
>   info touch
> 
> But that failed due to shortcomings in variously implemented
> install-info commands that I don't remember now.

There were actually several (Debian-specific?) problems with this form.

  https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=483554

> Therefore this was changed to "info -f coreutils touch" IIRC and
> then later mutated again to "info coreutils 'touch invocation'" to
> get more canonical.
> 
> But I think in recent years the install-info problems have been fixed.

If this is the following bug:

  https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=139569

it was fixed in Debian in September 2009. The simple form now seems
to be OK.

-- 
Vincent Lefèvre <vincent <at> vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Message #26 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Vincent Lefevre <vincent <at> vinc17.net>, 760861 <at> bugs.debian.org
Cc: 18428 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: Bug#760861: bug#18428: coreutils binary breaks coreutils
 documentation
Date: Tue, 09 Sep 2014 01:51:23 +0100

On 09/09/2014 01:32 AM, Vincent Lefevre wrote:
> On 2014-09-08 18:10:35 -0600, Bob Proulx wrote:
>> Note that IIRC originally the pointer was:
>>
>>   info touch
>>
>> But that failed due to shortcomings in variously implemented
>> install-info commands that I don't remember now.
> 
> There were actually several (Debian-specific?) problems with this form.
> 
>   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=483554
> 
>> Therefore this was changed to "info -f coreutils touch" IIRC and
>> then later mutated again to "info coreutils 'touch invocation'" to
>> get more canonical.
>>
>> But I think in recent years the install-info problems have been fixed.
> 
> If this is the following bug:
> 
>   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=139569
> 
> it was fixed in Debian in September 2009. The simple form now seems
> to be OK.

There is also ambiguity in the shorter form:

  info stat
  info '(coreutils) stat invocation'

Likewise for chmod, chown, kill, link, mkdir, ...

So we'll stick with the longer form
(which is likely to be cut n pasted in any case)

thanks,
Pádraig.

Message #29 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Pádraig Brady <P <at> draigBrady.com>, 
 Vincent Lefevre <vincent <at> vinc17.net>, 760861 <at> bugs.debian.org
Cc: 18428 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#18428: Bug#760861: bug#18428: coreutils binary breaks
 coreutils documentation
Date: Mon, 08 Sep 2014 20:55:23 -0700

[Message part 1 (text/plain, inline)]

Pádraig Brady wrote:
> So we'll stick with the longer form
> (which is likely to be cut n pasted in any case)

While this sounds like a win, I still like the idea of renaming the 
troublesome info node, as there is a lot of advice out there to use the 
old forms for 'info' and it's probably better to support that advice, at 
least for a while, than to make it immediately stop working.

I noticed other problems that are at least somewhat related to the 
recent coreutils multi-binary executable changes, and fixed some of 
these problems with the attached patches.  (I ran out of energy before 
fixing the rest.  :-)  Patch 2 renames the troublesome node.

Come to think of it, how about removing the 'coreutils' command 
entirely?  Why should users invoke 'coreutils' directly?  We could move 
it to libexec and remove it from the documentation.

[0001-doc-mention-which-commands-are-optional.patch (text/plain, attachment)]

[0002-doc-rename-coreutils-invocation-to-Multi-call-invoca.patch (text/plain, attachment)]

[0003-maint-prefer-return-status-to-exit-status-in-main.patch (text/plain, attachment)]

[0004-maint-avoid-file-scope-names-of-the-form-_-a-z.patch (text/plain, attachment)]

Message #34 received at 18428-done <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: 18428-done <at> debbugs.gnu.org
Cc: Alex Deymo <deymo <at> chromium.org>, Mike Frysinger <vapier <at> gentoo.org>
Subject: Re: bug#18428: Bug#760861: bug#18428: coreutils binary breaks
 coreutils documentation
Date: Tue, 09 Sep 2014 10:50:14 +0100

[Message part 1 (text/plain, inline)]

On 09/09/2014 04:55 AM, Paul Eggert wrote:
> Subject: [PATCH 1/4] doc: mention which commands are optional

I was thinking that the bst way to do that would be to adjust things
so that the node wasn't installed if the command wasn't.  But it's better
to have this info generally available online also, so +1

> Subject: [PATCH 2/4] doc: rename "coreutils invocation" to "Multi-call

I had done essentially this in my local patch :) so +1

One caveat is that `coreutils --help` is now not accurate
in its presented texinfo node name.  Though I wouldn't
worry about that TBH, especially if relegating coreutils(1)
to a helper command in libexec.  Now some systems may very well like the
explicit option of `coreutils $cmd ...`, but since we need the
--coreutils-prog option too I'd be on for keeping this as a helper command.

I've attached the now optional patch to adjust node names,
which I'm 60:40 for applying since it works with pinfo.

> Subject: [PATCH 3/4] maint: prefer 'return status;' to 'exit (status);' in 'main'

simpler so +1
There were a couple of syntax-check errors with this,
fixed in the attached.

> Subject: [PATCH 4/4] maint: avoid file-scope names of the form _[a-z]*

+1

Marking this bug as done...

thanks!
Pádraig.

[multicall-info.patch (text/x-patch, attachment)]

Message #37 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Michael Stone <mstone <at> debian.org>
To: Bob Proulx <bob <at> proulx.com>, 760861 <at> bugs.debian.org
Cc: 18428 <at> debbugs.gnu.org
Subject: Re: Bug#760861: bug#18428: coreutils binary breaks coreutils
 documentation
Date: Tue, 9 Sep 2014 08:51:18 -0400

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. 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. 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. Maybe point people 
at https://www.gnu.org/software/coreutils/manual/html_node/ ? 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

Mike Stone

Message #40 received at 18428 <at> debbugs.gnu.org (full text, mbox):

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: Re: 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.

Message #43 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Michael Stone <mstone <at> debian.org>
To: Pádraig Brady <P <at> draigBrady.com>, 760861 <at> bugs.debian.org
Cc: 18428 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: Bug#760861: bug#18428: Bug#760861: bug#18428: coreutils binary
 breaks coreutils documentation
Date: Tue, 9 Sep 2014 10:52:21 -0400

On Tue, Sep 09, 2014 at 03:31:35PM +0100, Pádraig Brady wrote:
>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).

Right. I've heard the argument for 15 years that info docs are really 
good, it's just the interface. :) In all that time, a better interface 
hasn't really caught on, and the web happened.

>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'

A huge improvement. I suspect that this might also help the info docs 
show up in google, instead of being below the fold. Alternative wording:

  Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
  or available locally via: info '(coreutils) ls invocation'

To make it more clear it's the same thing available different ways.

Mike Stone

Message #46 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Michael Stone <mstone <at> debian.org>, Pádraig Brady
 <P <at> draigBrady.com>, 760861 <at> bugs.debian.org
Cc: 18428 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#18428: Bug#760861: bug#18428: Bug#760861: bug#18428: coreutils
 binary breaks coreutils documentation
Date: Tue, 09 Sep 2014 12:58:14 -0400

On 09/09/2014 10:52 AM, Michael Stone wrote:
> On Tue, Sep 09, 2014 at 03:31:35PM +0100, Pádraig Brady wrote:
>> 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).
>
> Right. I've heard the argument for 15 years that info docs are really good, it's just the interface. :) In all that time, a better interface hasn't really caught on, and the web happened.
>
>> 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'
>
> A huge improvement. I suspect that this might also help the info docs show up in google, instead of being below the fold. Alternative wording:
>
>    Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
>    or available locally via: info '(coreutils) ls invocation'
>

BTW,
 "http://gnu.org/s/"  redirects to "http://www.gnu.org/software/" ,
so
 http://gnu.org/s/coreutils/ls

also works.

Message #49 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Assaf Gordon <assafgordon <at> gmail.com>
Cc: 18428 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>,
 Michael Stone <mstone <at> debian.org>
Subject: Re: bug#18428: Bug#760861: bug#18428: Bug#760861: bug#18428: coreutils
 binary breaks coreutils documentation
Date: Tue, 09 Sep 2014 19:25:18 +0100

On 09/09/2014 05:58 PM, Assaf Gordon wrote:
> On 09/09/2014 10:52 AM, Michael Stone wrote:
>> On Tue, Sep 09, 2014 at 03:31:35PM +0100, Pádraig Brady wrote:
>>> 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).
>>
>> Right. I've heard the argument for 15 years that info docs are really good, it's just the interface. :) In all that time, a better interface hasn't really caught on, and the web happened.
>>
>>> 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'
>>
>> A huge improvement. I suspect that this might also help the info docs show up in google, instead of being below the fold. Alternative wording:
>>
>>    Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
>>    or available locally via: info '(coreutils) ls invocation'
>>
> 
> BTW,
>  "http://gnu.org/s/"  redirects to "http://www.gnu.org/software/" ,
> so
>  http://gnu.org/s/coreutils/ls
> 
> also works.

Oh nice one. Note the redirections here are:

  gnu.org       -- perm --> www.gnu.org
  www.gnu.org/s -- temp --> www.gnu.org/software
  www......./ls -- temp --> www.gnu.org/software/coreutils/...#ls-invocation

So to avoid the first permanent redirection I'll probably go with:

  http://www.gnu.org/s/coreutils/ls

thanks,
Pádraig.

Message #52 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Vincent Lefevre <vincent <at> vinc17.net>
To: Assaf Gordon <assafgordon <at> gmail.com>, 760861 <at> bugs.debian.org
Cc: 18428 <at> debbugs.gnu.org, Pádraig Brady <P <at> draigBrady.com>,
 Bob Proulx <bob <at> proulx.com>, Michael Stone <mstone <at> debian.org>
Subject: Re: Bug#760861: bug#18428: Bug#760861: bug#18428: Bug#760861:
 bug#18428: coreutils binary breaks coreutils documentation
Date: Tue, 9 Sep 2014 20:49:04 +0200

On 2014-09-09 12:58:14 -0400, Assaf Gordon wrote:
> BTW,
>  "http://gnu.org/s/"  redirects to "http://www.gnu.org/software/" ,
> so
>  http://gnu.org/s/coreutils/ls
> 
> also works.

But isn't it better to avoid a redirection (if possible)?

-- 
Vincent Lefèvre <vincent <at> vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Message #55 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: 760861 <at> bugs.debian.org, 18428 <at> debbugs.gnu.org,
 Assaf Gordon <assafgordon <at> gmail.com>, Vincent Lefevre <vincent <at> vinc17.net>
Subject: Re: Bug#760861: bug#18428: Bug#760861: bug#18428: Bug#760861:
 bug#18428: coreutils binary breaks coreutils documentation
Date: Tue, 9 Sep 2014 13:27:27 -0600

Vincent Lefevre wrote:
> Assaf Gordon wrote:
> > BTW,
> >  "http://gnu.org/s/"  redirects to "http://www.gnu.org/software/" ,
> > so
> >  http://gnu.org/s/coreutils/ls
> > 
> > also works.
> 
> But isn't it better to avoid a redirection (if possible)?

I think it is better to use the canonical form.  This will be the
documented interface.  The short redirect in this case is really a
typing aide.  But the reason it redirects is so that the canonical
form is presented to the user for bookmarking and other purposes.

If we are playing golf and trying to reduce the number of characters
at the expense of readability then the logical conclusion is that we
should use a tinyurl such as http://tinyurl.com/osczpn8 or
http://bit.ly/1p3QK7a and that obviously isn't good.  Let's use the
canonical form.

Bob

Message #58 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Michael Stone <mstone <at> debian.org>
Cc: 18428 <at> debbugs.gnu.org
Subject: Re: Bug#760861: bug#18428: Bug#760861: bug#18428: coreutils binary
 breaks coreutils documentation
Date: Thu, 11 Sep 2014 01:31:35 +0100

[Message part 1 (text/plain, inline)]

On 09/09/2014 03:52 PM, Michael Stone wrote:
> On Tue, Sep 09, 2014 at 03:31:35PM +0100, Pádraig Brady wrote:
>> 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).
> 
> Right. I've heard the argument for 15 years that info docs are really good, it's just the interface. :) In all that time, a better interface hasn't really caught on, and the web happened.
> 
>> 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'
> 
> A huge improvement. I suspect that this might also help the info docs show up in google, instead of being below the fold. Alternative wording:
> 
>   Full documentation online at: <http://www.gnu.org/software/coreutils/ls>
>   or available locally via: info '(coreutils) ls invocation'
> 
> To make it more clear it's the same thing available different ways.

Done in the attached which I'll push later.

thanks,
Pádraig.

[online-info.patch (text/x-patch, attachment)]

Message #61 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>, 
 Michael Stone <mstone <at> debian.org>
Cc: 18428 <at> debbugs.gnu.org
Subject: Re: bug#18428: Bug#760861: bug#18428: Bug#760861: bug#18428: coreutils
 binary breaks coreutils documentation
Date: Thu, 11 Sep 2014 10:54:28 +0200

On 09/11/2014 02:31 AM, Pádraig Brady wrote:

> Subject: [PATCH 1/2] doc: adjust reference to info nodes in man pages

...

> Subject: [PATCH 2/2] doc: reference online info pages directly from man pages

The result of both patches looks almost good:

--- a/share/man/man1/basename.1
+++ b/share/man/man1/basename.1
@@ -43,11 +43,12 @@ basename \-s .h include/stdio.h
 .TP
 basename \-a any/str1 any/str2
 \-> "str1" followed by "str2"
-.PP
-GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
-Report basename translation bugs to <http://translationproject.org/team/>
 .SH AUTHOR
 Written by David MacKenzie.
+.SH "REPORTING BUGS"
+GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
+.br
+Report basename translation bugs to <http://translationproject.org/team/>
 .SH COPYRIGHT
 Copyright \(co 2014 Free Software Foundation, Inc.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
@@ -57,14 +58,7 @@ There is NO WARRANTY, to the extent permitted by law.
 .SH "SEE ALSO"
 dirname(1), readlink(1)
 .PP
-The full documentation for
-.B basename
-is maintained as a Texinfo manual.  If the
-.B info
-and
-.B basename
-programs are properly installed at your site, the command
-.IP
-.B info coreutils \(aqbasename invocation\(aq
-.PP
-should give you access to the complete manual.
+.br
+Full documentation at: <http://www.gnu.org/software/coreutils/basename>
+.br
+or available locally via: info '(coreutils) basename invocation'
________________________________^_______________________________^

I think we need the \aq instead of ' here, don't we?


> * help2man: Adjust to add the "online help" link (and subsequent
> translation bugs link) to a "REPORTING BUGS" section.
> Also add the concise links for further information in --help
> to the "SEE ALSO" section, and dispense with the more verbose
> default for that.

With this, we'd deviate from stock GNU help2man again.
I haven't looked into http://www.gnu.org/software/help2man/
too much yet, but are you sure we can't do the same with
the original upstream help2man?
BTW: we are using 1.43.3 while 1.46.2 is already available.
Maybe there are a few new options which may help.

Thanks & have a nice day,
Berny

Message #64 received at 18428 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>
Cc: 18428 <at> debbugs.gnu.org, Michael Stone <mstone <at> debian.org>
Subject: Re: bug#18428: coreutils binary breaks coreutils documentation
Date: Thu, 11 Sep 2014 11:00:39 +0100

On 09/11/2014 09:54 AM, Bernhard Voelker wrote:
> +or available locally via: info '(coreutils) basename invocation'
> ________________________________^_______________________________^
> 
> I think we need the \aq instead of ' here, don't we?

Good catch!

Interestingly it renders as a standard ' quote in the shell these days,
but converting to PDF at least, introduces the non copy and pasteable
curly quotes.

So I've added a s/'/\aq(/ and pushed.

thanks!
Pádraig.

p.s. I just diffed the latest help2man and there was nothing
significantly different or useful.  We can sync that up easily
at some stage in the future.

Previous Next

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