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

Previous Next

Full log

View this message in rfc822 format

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

Previous Next

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