* Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
@ 2005-12-11 18:37 Alan Mackenzie
2005-12-11 19:58 ` Eli Zaretskii
0 siblings, 1 reply; 9+ messages in thread
From: Alan Mackenzie @ 2005-12-11 18:37 UTC (permalink / raw)
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)
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-11 18:37 Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual} Alan Mackenzie
@ 2005-12-11 19:58 ` Eli Zaretskii
2005-12-11 21:28 ` Alan Mackenzie
0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2005-12-11 19:58 UTC (permalink / raw)
Cc: emacs-devel
> 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 ;-)
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-11 19:58 ` Eli Zaretskii
@ 2005-12-11 21:28 ` Alan Mackenzie
2005-12-12 0:58 ` Robert J. Chassell
` (2 more replies)
0 siblings, 3 replies; 9+ messages in thread
From: Alan Mackenzie @ 2005-12-11 21:28 UTC (permalink / raw)
Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-11 21:28 ` Alan Mackenzie
@ 2005-12-12 0:58 ` Robert J. Chassell
2005-12-12 9:32 ` Alan Mackenzie
2005-12-12 5:23 ` Richard M. Stallman
2005-12-12 5:39 ` Eli Zaretskii
2 siblings, 1 reply; 9+ messages in thread
From: Robert J. Chassell @ 2005-12-12 0:58 UTC (permalink / raw)
... 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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-12 0:58 ` Robert J. Chassell
@ 2005-12-12 9:32 ` Alan Mackenzie
2005-12-12 20:59 ` Eli Zaretskii
0 siblings, 1 reply; 9+ messages in thread
From: Alan Mackenzie @ 2005-12-12 9:32 UTC (permalink / raw)
Cc: emacs-devel
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)
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-12 9:32 ` Alan Mackenzie
@ 2005-12-12 20:59 ` Eli Zaretskii
0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2005-12-12 20:59 UTC (permalink / raw)
Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-11 21:28 ` Alan Mackenzie
2005-12-12 0:58 ` Robert J. Chassell
@ 2005-12-12 5:23 ` Richard M. Stallman
2005-12-12 5:39 ` Eli Zaretskii
2 siblings, 0 replies; 9+ messages in thread
From: Richard M. Stallman @ 2005-12-12 5:23 UTC (permalink / raw)
Cc: eliz, emacs-devel
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-11 21:28 ` Alan Mackenzie
2005-12-12 0:58 ` Robert J. Chassell
2005-12-12 5:23 ` Richard M. Stallman
@ 2005-12-12 5:39 ` Eli Zaretskii
2005-12-12 23:44 ` Karl Berry
2 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2005-12-12 5:39 UTC (permalink / raw)
Cc: karl, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual}.
2005-12-12 5:39 ` Eli Zaretskii
@ 2005-12-12 23:44 ` Karl Berry
0 siblings, 0 replies; 9+ messages in thread
From: Karl Berry @ 2005-12-12 23:44 UTC (permalink / raw)
Cc: acm, emacs-devel
> 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
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2005-12-12 23:44 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-12-11 18:37 Info bug with @xref{Sample .emacs File, , , ccmode, the CC Mode Manual} Alan Mackenzie
2005-12-11 19:58 ` Eli Zaretskii
2005-12-11 21:28 ` Alan Mackenzie
2005-12-12 0:58 ` Robert J. Chassell
2005-12-12 9:32 ` Alan Mackenzie
2005-12-12 20:59 ` Eli Zaretskii
2005-12-12 5:23 ` Richard M. Stallman
2005-12-12 5:39 ` Eli Zaretskii
2005-12-12 23:44 ` Karl Berry
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.