Subject: Re: bug#18428: coreutils binary breaks coreutils documentation

From: Bob Proulx <[email-masked]>
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