Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Alan Mackenzie]

Hi, Emacs!

Whilst amending programs.texi (to incorporate changes from CC Mode 5.31),
I hit a problem with Info.  I've inserted the cross reference:

    @xref{Sample .emacs File,,, ccmode, the CC Mode Manual}.

, and makeinfo'd it.  When I load the info file, this xref fails with the
error message "No such node or anchor: Sample".  [BTW: on the same
file.info, Emacs 21.3 says much the same: "No such anchor in tag table or
node in tag table or file: Sample".]

Putting point on this xref typing <CR>, and edebuggering through info.el,
this happens:

(i) <CR> is bound to `Info-follow-nearest-node', and this gets called.
(ii) This calls (Info-try-follow-nearest-node nil).

(iii) Info-t-f-n-n extracts the node name (but WITHOUT "ccmode"), and
does:  (Info-follow-reference "Sample .emacs File" nil).

Up to now, this is well and good.  But my poor little brain can't cope
with what now follows:

(v) Info-follow-reference makes a regexp out of "Sample .emacs File"
prefixed by "*note":  "\\*note[ \t\n]+Sample[ \t\n]+\\.emacs[ \t\n]+File".

(vi) Info-f-r now searches forwards and backwards in the original info
buffer for this regexp, and finds it (again).  It then calls
(Info-extract-menu-node-name t)  [The "t" here is the parameter
@code{multi-line}.]

(vii) Info-extract-menu-node-name now tries to extract the node name
(again).  It builds a exquisite regexp, and uses it to "look-at" the
buffer at point to extract the node name (again) as (match-string 2).

HERE IS THE BUG:  In building the regexp, it inserts a "[^.]" component
here:

    (concat Info-menu-entry-name-re ":\\(:\\|"
            (Info-following-node-name-re
             (cond
              (index-node "^,\t\n")
              (multi-line "^.,\t")     <=================== info.el L2195
;;;
;;;                         ^
;;;                         |
;;;                      OUTCH!!
;;;
              (t          "^.,\t\n")))
            "\\)"
            (if index-node
                "\\.\\(?:[ \t\n]+(line +\\([0-9]+\\))\\)?"
              ""))

Thus the regexp search truncates "Sample .emacs File" after "Sample".

These functions and their parameters aren't commented, so it's difficult
to understand exactly what they're supposed to do.  In particular, I've
no idea why multi-line (whatever that might mean) excludes "." from
permissible node names.  Can somebody help me here, please?

And surely, moving point to the @xref, partially extracting the node name
(i.e. without the (optional) filename "ccmode"), building a regexp from
this, searching for this regexp to find where we were anyway, then
extracting the target node name (again) from where this regexp matches is
silly.

-- 
Alan Mackenzie (Munich, Germany)

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Eli Zaretskii]

> Date: Sun, 11 Dec 2005 18:37:49 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> 
> Whilst amending programs.texi (to incorporate changes from CC Mode 5.31),
> I hit a problem with Info.  I've inserted the cross reference:
> 
>     @xref{Sample .emacs File,,, ccmode, the CC Mode Manual}.
> 
> , and makeinfo'd it.  When I load the info file, this xref fails with the
> error message "No such node or anchor: Sample".  [BTW: on the same
> file.info, Emacs 21.3 says much the same: "No such anchor in tag table or
> node in tag table or file: Sample".]

The problem here is with your usage of Texinfo: node names cannot
contain periods.  The Texinfo manual says:

   * Unfortunately, you cannot use periods, commas, colons or
     parentheses within a node name; these confuse the Texinfo
     processors.  Perhaps this limitation will be removed some day, too.

So there you are: don't do that ;-)

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Alan Mackenzie]

On Sun, 11 Dec 2005, Eli Zaretskii wrote:

>> Date: Sun, 11 Dec 2005 18:37:49 +0000 (GMT)
>> From: Alan Mackenzie <acm@muc.de>

>> Whilst amending programs.texi (to incorporate changes from CC Mode
>> 5.31), I hit a problem with Info.  I've inserted the cross reference:
>> 
>>     @xref{Sample .emacs File,,, ccmode, the CC Mode Manual}.

>> , and makeinfo'd it.  When I load the info file, this xref fails with
>> the error message "No such node or anchor: Sample".  [BTW: on the same
>> file.info, Emacs 21.3 says much the same: "No such anchor in tag table
>> or node in tag table or file: Sample".]

>The problem here is with your usage of Texinfo: node names cannot
>contain periods.  The Texinfo manual says:
>
>   * Unfortunately, you cannot use periods, commas, colons or
>     parentheses within a node name; these confuse the Texinfo
>     processors.  Perhaps this limitation will be removed some day, too.
>
>So there you are: don't do that ;-)

Hey, that's not fair!  We've had a node called "Sample .emacs File" in
the CC Mode manual since 22nd February 1995, and that was before I could
even spell "Emacs".  ;-(

And, so far as I know, we've _NEVER_ had any problems with it.  It has
simply worked.  More to the point, makeinfo has never given a warning
about it.

Damn!  :-)

By the way, WHY can't we have periods in node names?  OK, we need commas
to separate the arguments of the @xref and info node, we need colons to
delimit the node name, we need parens to give an info filename.  But why
periods?  Over ten years of "@node Sample .emacs File" suggests that the
restriction isn't really necessary.  What would break if the prohibition
on periods were tracked down and removed?

-- 
Alan.

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Robert J. Chassell]

   ... We've had a node called "Sample .emacs File" in the CC Mode
   manual since 22nd February 1995 ...

And possibly Info searched for that node as "Sample" ...  That is the
only node in that manual that starts with the word "Sample".

The Texinfo manual has included a warning about the characters that a
node name may contain since at least 1987 and probably earlier.  I
don't remember dot specifically, but I do remember thinking that the
rule was to use characters that are not in regexps.

In any event, the customary solution is to name the node and the title
differently.  As is said in  (texinfo)Node Line Tips , `try to pick
node names that are informative but short'.  The node name might be
`Sample' and the chapter or section title `Sample @code{.emacs} File'.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Alan Mackenzie]

Hi, Robert!

On Mon, 12 Dec 2005, Robert J. Chassell wrote:

>   ... We've had a node called "Sample .emacs File" in the CC Mode
>   manual since 22nd February 1995 ...

>And possibly Info searched for that node as "Sample" ...  That is the
>only node in that manual that starts with the word "Sample".

>The Texinfo manual has included a warning about the characters that a
>node name may contain since at least 1987 and probably earlier.  I don't
>remember dot specifically, but I do remember thinking that the rule was
>to use characters that are not in regexps.

OK.  The warning in that manual is somewhat inconspicuous.  On the page
"node" we have:

      To create a node, write an `@node' command at the beginning of a
    line, and follow it with up to four arguments, separated by commas, on
    the rest of the same line.

, with no mention of colons, parens or periods.  In the sub-node
"Choosing Node and Pointer Names", there is no mention of the
restriction.  Only in (the relatively obscurely named) "Node Line
Requirements" is this restriction mentioned.  This seems suboptimal.

>In any event, the customary solution is to name the node and the title
>differently.  As is said in  (texinfo)Node Line Tips , `try to pick node
>names that are informative but short'.  The node name might be `Sample'
>and the chapter or section title `Sample @code{.emacs} File'.

OK, thanks.

>    Robert J. Chassell                         

-- 
Alan Mackenzie (Munich, Germany)

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Eli Zaretskii]

> Date: Mon, 12 Dec 2005 09:32:55 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> Cc: emacs-devel@gnu.org
> 
> OK.  The warning in that manual is somewhat inconspicuous.  On the page
> "node" we have:
> 
>       To create a node, write an `@node' command at the beginning of a
>     line, and follow it with up to four arguments, separated by commas, on
>     the rest of the same line.
> 
> , with no mention of colons, parens or periods.  In the sub-node
> "Choosing Node and Pointer Names", there is no mention of the
> restriction.  Only in (the relatively obscurely named) "Node Line
> Requirements" is this restriction mentioned.  This seems suboptimal.

Did you try index search (the `i' command)?  There are at least two
index entries that should have helped you find this text in a blink:
"Period in nodename" and "Node names, invalid characters in".  Index
search is The Right Way of finding something in an Info manual quickly
and efficiently.

That said, if you think this information should be referenced from
less obscure places, please submit a bug report to the Texinfo
bug-reporting mailing list.

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Richard M. Stallman]

    And, so far as I know, we've _NEVER_ had any problems with it.  It has
    simply worked.  More to the point, makeinfo has never given a warning
    about it.

There are situations in which it would not work.
Specifically, if you try to follow a menu item like this,

  * Init Example: Sample .emacs File.

Info would look for a node called `Sample '.

There is no way to detect that there is a problem with that
menu item (except that it will probably fail to find that
node), so we decided to put in a warning for using a node
name that is susceptible to the problem.

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Eli Zaretskii]

> Date: Sun, 11 Dec 2005 21:28:43 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> cc: emacs-devel@gnu.org
> 
> >   * Unfortunately, you cannot use periods, commas, colons or
> >     parentheses within a node name; these confuse the Texinfo
> >     processors.  Perhaps this limitation will be removed some day, too.
> >
> >So there you are: don't do that ;-)
> 
> Hey, that's not fair!

Who said life's fair? where's that written? ;-)

> We've had a node called "Sample .emacs File" in
> the CC Mode manual since 22nd February 1995, and that was before I could
> even spell "Emacs".  ;-(
> 
> And, so far as I know, we've _NEVER_ had any problems with it.  It has
> simply worked.

Worked with what Info reader?  Different readers have different code
to extract a node name from cross-references and menu lines, so each
one of them will react differently.  I think the standalone reader
(the one distributed with Texinfo) had grave problems with such nodes
several versions ago.  The Emacs's Info reader has changed
considerably between v21.x and now.  If you really wish to dig into
this, you will probably find that one of these changes is responsible
for the breakage.

But the fact remains that node names cannot have periods.

> More to the point, makeinfo has never given a warning about it.

That could be worth reporting to the Texinfo mailing list.  I CC'ed
Karl berry, who maintains Texinfo.

> By the way, WHY can't we have periods in node names?  OK, we need commas
> to separate the arguments of the @xref and info node, we need colons to
> delimit the node name, we need parens to give an info filename.  But why
> periods?

Because in the produced Info manual, the period is also one of the
delimiters of the node name in menu items and cross-references.
Consider this:

  *Note Foo: Bar.

Here `Bar' is the name of a node, and it is delimited by the colon and
the period.  `Foo' is what was in the second argument of the @xref
directive.

> Over ten years of "@node Sample .emacs File" suggests that the
> restriction isn't really necessary.

I think it is necessary; you've just been lucky: you never used a
cross-reference with its second argument non-empty.  When the second
argument is empty, the node name is delimited by "::", which, in the
Emacs Info reader, is enough to extract the node name.

Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.

[Karl Berry]

    > More to the point, makeinfo has never given a warning about it.

So many documents do not follow this convention that I think it would do
more harm than good to have a warning about it.  As has been noted, in
practice there are many circumstances where a period works out ok.  The
manual disallows it because I don't wish to try to enumerate when it is
ok and when it isn't.

The right fix (as I've said before) is to change Info format to allow
arbitrary characters in node names.  We've discussed this at some
length, but no implementation has been done :(.

karl