Hi Gavin,
Gavin Smith wrote:
> The reason is the role of the "." character in Info syntax. It terminates
> the node name in an index entry, so in the index entry
>
> * verify.h: assert.h. (line 6)
>
> the node name is taken as "assert", not "assert.h".
Yup, I see this is what happens in scan.c lines 1328..1331, with this
backtrace:
#0 scan_reference_target (entry=0x5555555cae80, node=0x5555555c11e0,
in_parentheses=0) at scan.c:1321
#1 0x0000555555574e74 in scan_node_contents (node=0x5555555c11e0,
fb=0x5555555c4a20, tag_ptr=0x5555555c4c78) at scan.c:1601
#2 0x0000555555572435 in info_node_of_tag_ext (fb=0x5555555c4a20,
input_tag_ptr=0x5555555c4c78, fast=0) at nodes.c:1278
#3 0x000055555557259a in info_node_of_tag (fb=0x5555555c4a20,
tag_ptr=0x5555555c4c78) at nodes.c:1313
#4 0x0000555555571e16 in info_get_node_of_file_buffer
(file_buffer=0x5555555c4a20, nodename=0x5555555c6710 "Concept index")
at nodes.c:1071
#5 0x0000555555571ba2 in info_get_node_with_defaults (filename_in=0x0,
nodename_in=0x5555555c58f0 "Concept index",
defaults=0x5555555c5530) at nodes.c:993
#6 0x000055555557a555 in info_select_reference (window=0x5555555bf490,
entry=0x5555555c5750) at session.c:2075
#7 0x000055555557b064 in info_menu_or_ref_item (window=0x5555555bf490,
menu_item=1, xref=1, ask_p=0) at session.c:2432
#8 0x000055555557bab5 in info_select_reference_this_line
(window=0x5555555bf490, count=1) at session.c:2760
#9 0x0000555555576c48 in info_read_and_dispatch () at session.c:253
#10 0x0000555555576b8a in info_session (ref_list=0x5555555bed90,
user_filename=0x0, error=0x0) at session.c:221
#11 0x0000555555568a46 in main (argc=0, argv=0x7fffffffd448) at info.c:1088
and with node->flags = N_IsIndex.
> So we could change the code in info to only recognize the "." as ending
> the node name if it is followed by a whitespace character.
This would make references in the index work. But what about references
generated by @ref or @pxref? It is better to design things in such a way
that all kinds of references work equally well.
> If I insert the DEL quoting characters into the file, then the link
> works properly.
Yes, 'info' understands this DEL as so-called INFO_QUOTE character.
This would be a more robust solution than having code decide ad-hoc
what is a terminator and what is not.
But Emacs doesn't! If I use the attached modified info file in Emacs,
Emacs
1. displays these characters as ^? instead of hiding them,
2. complains when I select this reference in the index.
It is a pity that Emacs and 'info' have gone out-of-sync in this way.
Eli, do you think it would be possible for Emacs to interpret this
kind of syntax (^?NODENAME^? for a node name that contains dots or commas)?
> Follow the menu entry name with a single colon, and follow the node
> name with tab, comma, newline, or the two characters period and space
> (@samp{. }).
>
> This text was added in commit 7d6ecb6d (Karl Berry, 2008-05-12),
> referencing node names containing "config.status".
Does this apply only to menu entries, or also to @ref and @pxref ?
> +2024-12-30 Gavin Smith <gavinsmith0...@gmail.com>
> +
> + ". " terminator for index entry node name
> +
> + * info/scan.c (scan_reference_target):
> + First check for a ". " and ".\n" terminator for node name in menu,
> + rather than just a ".". This allows index entries referring to
> + nodes with "." in their names. Report from Bruno Haible.
Thanks. That is likely the best solution if Emacs would not want to support
the ^?NODENAME^? syntax.
Bruno
This is hello.info, produced by makeinfo version 7.2 from hello.texi.
This manual is for GNU Hello (version 2.12.1.12-24225d-dirty, 11 July
2024), which prints a friendly greeting (and serves as an example GNU
package).
Copyright ?? 1992-2024 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts. A copy of the license is included in
the section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Basics
START-INFO-DIR-ENTRY
* Hello: (hello). Hello, GNU world.
END-INFO-DIR-ENTRY
File: hello.info, Node: Top, Next: Overview, Up: (dir)
GNU Hello
*********
This manual is for GNU Hello (version 2.12.1.12-24225d-dirty, 11 July
2024), which prints a friendly greeting (and serves as an example GNU
package).
* Menu:
* Overview:: General purpose and information.
* Sample output:: Sample output from ???hello???.
* Invoking hello:: How to run ???hello???.
* assert:: The assert function.
* assert.h:: The <assert.h> header.
* Reporting bugs:: Sending bug reports and feature suggestions.
* Concept index:: Index of concepts.
File: hello.info, Node: Overview, Next: Sample output, Prev: Top, Up: Top
1 Overview
**********
The GNU ???hello??? program (<https://www.gnu.org/software/hello/>) produces
a familiar, friendly greeting. It allows nonprogrammers to use a
classic computer science tool which would otherwise be unavailable to
them. Because it is protected by the GNU General Public License, users
are free (in perpetuity) to share and change it.
Not to spoil the joke, but of course the practical purpose of GNU
Hello is to serve as a minimal example of a GNU package. So, although
most manuals don't need to discuss the implementation of the programs
they document, that is part of the goal here.
First, GNU Hello follows the GNU coding standards (*note Preface:
(standards)Top.) and GNU maintainer standards (*note Preface:
(maintain)Top.). These are the basic documents which all GNU packages
should adhere to.
The Hello package also implements recommended development practices
not embodied in the standards, using other GNU packages and features:
??? It uses Automake (*note Introduction: (automake)Top.) and hence
also Autoconf (*note Introduction: (autoconf)Top.) for
configuration.
??? It uses Gnulib (*note Introduction: (gnulib)Top.) to enhance
portability and avoid duplication of common sources. Both
???gnulib-tool??? and ???srclist-update??? are used, for purposes of
example. See the ???README-dev??? file in the distribution.
??? GNU Gettext (*note Introduction: (gettext)Top.) is used for
internationalization support. Hello's greeting has been translated
into many languages.
??? Internally, Hello uses the GNU ???getopt_long??? function (*note
(libc)Getopt Long Options::) to parse options, thus supporting
GNU-style long options such as ???--help???.
??? The Hello Man page is generated with GNU ???help2man??? (*note
Overview: (help2man)Top.) from the ???--help??? output. This relieves
the maintainers from the burden of updating separate man
documentation, yet provides a reasonable overview for man devotees.
??? Finally, Texinfo (*note Introduction: (texinfo)Top.) is the
documentation format for this manual. It supports output in Info,
HTML, PDF, DVI, plain text, XML, and other formats.
GNU Hello is implemented in C. The GNU Gettext distribution contains
"hello world" examples in many other programming languages; see the
Gettext home page at <https://www.gnu.org/software/gettext/>.
The top-level ???Makefile.am??? in Hello also contains a few special
targets for other projects to adapt as desired:
???diff???
Make a diff from the previous release, assuming the current tarball
is in the current tarball.
???po-check???
Verify that all source files using ???_()??? are included for
translation in ???po/POTFILES.in???, so translators will have all the
messages.
???wwwdoc???
Sample procedure for updating the manual on the GNU web site, in
this case <https://www.gnu.org/software/hello/manual/>.
GNU Hello was written by Mike Haertel, David MacKenzie, Jan
Brittenson, Charles Hannum, Roland McGrath, Noah Friedman, Karl
Eichwalder, Karl Berry, and The King.
File: hello.info, Node: Sample output, Next: Invoking hello, Prev: Overview,
Up: Top
2 Sample output
***************
Here are some examples of running GNU Hello.
This is the output of the command ???hello???:
Hello, world!
This is the output of the command ???hello --traditional???:
hello, world
This is the output of the command ???hello --greeting=hi???:
hi
File: hello.info, Node: Invoking hello, Next: assert, Prev: Sample output,
Up: Top
3 Invoking ???hello???
******************
The format for running the ???hello??? program is:
hello OPTION ...
With no options, ???hello??? prints the greeting ???Hello, world!???.
???hello??? supports the following options:
???--greeting=TEXT???
???-g TEXT???
Output TEXT instead of the default greeting.
???--help???
???-h???
Print an informative help message on standard output and exit
successfully.
For the ???--help??? output of GNU programs, it's strongly encouraged
to include a brief (one or two sentences) description of what the
program does, as well as the synopsis of how to run the program.
Any environment variables which affect execution should also be
mentioned (Hello doesn't have any).
???--traditional???
???-t???
Output the traditional greeting message ???hello, world???.
???--version???
???-v???
Print the version number and licensing information of Hello on
standard output and then exit successfully.
If more than one of the greeting options (???-g???, ???-t???, and their
long-named equivalents) is specified, whichever comes last takes
precedence.
* assert:: The assert function. * assert.h:: The <assert.h> header.
File: hello.info, Node: assert, Next: assert.h, Prev: Invoking hello, Up:
Top
4 The assert function
*********************
This chapter documents the ???assert??? function.
File: hello.info, Node: assert.h, Next: Reporting bugs, Prev: assert, Up:
Top
5 The <assert.h> header
***********************
This chapter documents the ???assert.h??? and ???verify.h??? header files.
File: hello.info, Node: Reporting bugs, Next: Concept index, Prev: assert.h,
Up: Top
6 Reporting bugs
****************
To report bugs, suggest enhancements or otherwise discuss GNU Hello,
please send electronic mail to <bug-he...@gnu.org>.
For bug reports, please include enough information for the
maintainers to reproduce the problem. Generally speaking, that means:
??? The version numbers of Hello (which you can find by running
???hello --version???) and any other program(s) or manual(s) involved.
??? Hardware and operating system names and versions.
??? The contents of any input files necessary to reproduce the bug.
??? The expected behavior and/or output.
??? A description of the problem and samples of any erroneous output.
??? Options you gave to ???configure??? other than specifying installation
directories.
??? Anything else that you think would be helpful.
When in doubt whether something is needed or not, include it. It's
better to include too much than to leave out something important.
Patches are welcome; if possible, please make them with ???diff -c???
(*note Overview: (diff)Top.) and include ???ChangeLog??? entries (*note
(emacs)Change Log::). Please follow the existing coding style.
File: hello.info, Node: Concept index, Prev: Reporting bugs, Up: Top
Concept index
*************
[index ]
* Menu:
* --greeting: Invoking hello. (line 16)
* --help: Overview. (line 38)
* --help <1>: Invoking hello. (line 20)
* --traditional: Invoking hello. (line 31)
* --version: Invoking hello. (line 35)
* -g: Invoking hello. (line 16)
* -h: Invoking hello. (line 20)
* -t: Invoking hello. (line 31)
* -v: Invoking hello. (line 35)
* authors: Overview. (line 71)
* Autoconf: Overview. (line 25)
* Automake: Overview. (line 25)
* Berry, Karl: Overview. (line 71)
* Brittenson, Jan: Overview. (line 71)
* bug reporting: Reporting bugs. (line 6)
* checklist for bug reports: Reporting bugs. (line 9)
* Eichwalder, Karl: Overview. (line 71)
* environment variables, help for: Invoking hello. (line 23)
* examples: Sample output. (line 6)
* Friedman, Noah: Overview. (line 71)
* Gettext: Overview. (line 34)
* GNU coding standards: Overview. (line 17)
* GNU maintainer standards: Overview. (line 17)
* Gnulib: Overview. (line 29)
* greetings: Overview. (line 6)
* Haertel, Mike: Overview. (line 71)
* Hannum, Charles: Overview. (line 71)
* help: Invoking hello. (line 6)
* Help2man: Overview. (line 42)
* invoking: Invoking hello. (line 6)
* joke, not: Overview. (line 12)
* King, The: Overview. (line 71)
* MacKenzie, David: Overview. (line 71)
* Makefile.am targets: Overview. (line 55)
* McGrath, Roland: Overview. (line 71)
* modern: Invoking hello. (line 31)
* options: Invoking hello. (line 6)
* overview: Overview. (line 6)
* patches, contributing: Reporting bugs. (line 25)
* problems: Reporting bugs. (line 6)
* README-dev source file: Overview. (line 29)
* reporting bugs: Reporting bugs. (line 6)
* sample output: Sample output. (line 6)
* srclist-update script: Overview. (line 29)
* standards, GNU coding: Overview. (line 17)
* standards, GNU maintainer: Overview. (line 17)
* Texinfo: Overview. (line 47)
* traditional: Invoking hello. (line 31)
* usage: Invoking hello. (line 6)
* verify.h: assert.h. (line 6)
Tag Table:
Node: Top804
Node: Overview1380
Node: Sample output4627
Node: Invoking hello5027
Node: assert6344
Node: assert.h6525
Node: Reporting bugs6735
Node: Concept index8005
End Tag Table
Local Variables:
coding: utf-8
End:
