Index targets in Info files

[peniblec]

Howdy; Sphinx & Info enjoyer, puzzled by .. index :: translation from ReST to Texinfo to Info.

The Sphinx user's guide recommends putting index entries "before the thing they refer to". For example:

Section foo
-----------

Discussion about foo.

.. index:: synonym for bar, bar-adjacent, bar-shaped, barbell, barista

Section bar
-----------

Discussion of all things bar.

However, when generating .info files, the generated index entries seem to point to the node prior to the one that .. index :: should refer to, which is confusing because Info readers typically only display one node at a time (NB: "node" as in, Info node). So in the above example, searching for & following index entries for bar-related keywords leads to section foo.

In more details, Sphinx's TexinfoTranslator generates this .texi output (simplified):

@node Section foo,Section bar,Top,Top
@anchor{foo doc}@anchor{1}@anchor{foo repro-documentation}@anchor{2}@anchor{foo section-foo}@anchor{3}
@chapter Section foo


Discussion about foo.

@geindex synonym for bar
@geindex bar-adjacent
@geindex bar-shaped
@geindex barbell
@geindex barista

@node Section bar,Index,Section foo,Top
@anchor{foo section-bar}@anchor{4}
@chapter Section bar


Discussion of all things bar.

Then Sphinx calls makeinfo, which generates this .info output (again, simplified; quoted the ^X control characters):

File: repro.info,  Node: Section foo,  Next: Section bar,  Prev: Top,  Up: Top

1 Section foo
*************

Discussion about foo.

^_
File: repro.info,  Node: Section bar,  Next: Index,  Prev: Section foo,  Up: Top

2 Section bar
*************

Discussion of all things bar.

^_
File: repro.info,  Node: Index,  Prev: Section bar,  Up: Top

Index
*****

^@^H[index^@^H]
* Menu:

* bar-adjacent:                          Section foo.           (line 7)
* bar-shaped:                            Section foo.           (line 7)
* barbell:                               Section foo.           (line 7)
* barista:                               Section foo.           (line 7)
* synonym for bar:                       Section foo.           (line 7)

(See attached script to reproduce)

So wondering what to do about this.

On the makeinfo side: the Texinfo manual does say "Index entries should precede the visible material that is being indexed", which sounds like the logic matches Sphinx's, but

• the example given is an index targeting a simple paragraph, not a section heading;
• the sources for this very section of the manual clearly show index commands (@cindex) added after the section heading.

AFAICT from a couple of such hand-authored .texi sources, putting indices after headings is common practice, so my tentative conclusion is that the Texinfo manual's "should precede" advice implicitly applies to section bodies (e.g. because Texinfo best practices emphasize peppering such indices all throughout the prose?), not necessarily to headings.

But I'm not sure what that should say about Sphinx's TexinfoTranslator. Should visit_index behave differently when the next node (NB: "node" as in, docutils node) is a heading?

(I'm guessing the HTML writer does something along those lines anyway? Since the HTML output looks like this:

  <section id="section-foo">
<h1>Section foo<a class="headerlink" href="#section-foo" title="Link to this heading">¶</a></h1>
<p>Discussion about foo.</p>
</section>
<section id="section-bar">
<span id="index-0"></span><h1>Section bar<a class="headerlink" href="#section-bar" title="Link to this heading">¶</a></h1>
<p>Discussion of all things bar.</p>
</section>

id="index-0", refered in genindex.html, is produced within <section id="section-bar">, rather than at the very end of "section-foo")

---

I haven't yet found "definite proof" in the Texinfo documentation or sources that spells out "@*index entries always point to the section they are defined in". I'm relatively sure that it would be desirable for TexinfoTranslator to move @geindex commands after section headings, but I wonder if I missed something; hence opening a discussion.