texinfo: simplify reference emission.

The commit adds a new config value 'texinfo_emit_document_references'
that blocks the emission of inline references and make it better readable
with legacy stand-alone reader ``info``.

Before the change we emit:
Default option value for @ref{e,,-Wshift-overflow3}.

while with texinfo_emit_document_references == True:
Default option value for -Wshift-overflow3.

It addresses limitations mentioned in Sphinx' FAQ:
https://www.sphinx-doc.org/en/master/faq.html#texinfo-info

doc/_static/conf.py.txt

@@ -319,6 +319,10 @@ texinfo_documents = [
 #
 # texinfo_no_detailmenu = False
 
+# If false, do not generate in manual @ref nodes.
+#
+# texinfo_emit_document_references = False
+
 # -- A random example -----------------------------------------------------
 
 import sys, os

doc/faq.rst

@@ -299,6 +299,10 @@ appear in the source.  Emacs, on the other-hand, will by default replace
 
     :ref:`texinfo-links`
 
+One can disable generation of the inline references in a document
+with confval:`texinfo_emit_document_references`.  That makes
+an info file more readable with stand-alone reader (``info``).
+
 The exact behavior of how Emacs displays references is dependent on the variable
 ``Info-hide-note-references``.  If set to the value of ``hide``, Emacs will hide
 both the ``*note:`` part and the ``target-id``.  This is generally the best way

doc/usage/configuration.rst

@@ -2486,6 +2486,13 @@ These options influence Texinfo output.
 
    .. versionadded:: 1.1
 
+.. confval:: texinfo_emit_document_references
+
+  If false, do not generate inline references in a document.  That makes
+  an info file more readable with stand-alone reader (``info``).
+  Default is ``True``
+
+  .. versionadded:: 4.3.0
 
 .. _qthelp-options:
 

sphinx/builders/texinfo.py

@@ -211,6 +211,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('texinfo_domain_indices', True, None, [list])
     app.add_config_value('texinfo_show_urls', 'footnote', None)
     app.add_config_value('texinfo_no_detailmenu', False, None)
+    app.add_config_value('texinfo_emit_document_references', True, None)
 
     return {
         'version': 'builtin',

sphinx/writers/texinfo.py

@@ -545,7 +545,10 @@ def add_anchor(self, id: str, node: Node) -> None:
     def add_xref(self, id: str, name: str, node: Node) -> None:
         name = self.escape_menu(name)
         sid = self.get_short_id(id)
-        self.body.append('@ref{%s,,%s}' % (sid, name))
+        if self.config.texinfo_emit_document_references:
+            self.body.append('@ref{%s,,%s}' % (sid, name))
+        else:
+            self.body.append(name)
         self.referenced_ids.add(sid)
         self.referenced_ids.add(self.escape_id(id))
 

tests/test_build_texinfo.py

@@ -112,3 +112,17 @@ def test_texinfo_escape_id(app, status, warning):
     assert translator.escape_id('Hello(world)') == 'Hello world'
     assert translator.escape_id('Hello world.') == 'Hello world'
     assert translator.escape_id('.') == '.'
+
+
+@pytest.mark.sphinx('texinfo')
+def test_texinfo_xrefs(app, status, warning):
+    app.builder.build_all()
+    output = (app.outdir / 'sphinxtests.texi').read_text()
+    assert re.search(r'@ref{\w+,,--plugin\.option}', output)
+
+    # Now rebuild it without xrefs
+    app.config.texinfo_emit_document_references = False
+    app.builder.build_all()
+    output = (app.outdir / 'sphinxtests.texi').read_text()
+    assert not re.search(r'@ref{\w+,,--plugin\.option}', output)
+    assert 'Link to perl +p, --ObjC++, --plugin.option, create-auth-token, arg and -j' in output