From 6dec70e802aa008f8f2be0d5a214a494535779af Mon Sep 17 00:00:00 2001
From: Martin Liska <mliska@suse.cz>
Date: Wed, 25 Aug 2021 11:11:39 +0200
Subject: [PATCH] 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     |  4 ++++
 doc/faq.rst                 |  4 ++++
 doc/usage/configuration.rst |  7 +++++++
 sphinx/builders/texinfo.py  |  1 +
 sphinx/writers/texinfo.py   |  9 ++++++---
 tests/test_build_texinfo.py | 14 ++++++++++++++
 6 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt
index 9078199b3e1..3077d1b9332 100644
--- a/doc/_static/conf.py.txt
+++ b/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_cross_references = False
+
 # -- A random example -----------------------------------------------------
 
 import sys, os
diff --git a/doc/faq.rst b/doc/faq.rst
index 4b273023d3a..2e108143957 100644
--- a/doc/faq.rst
+++ b/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_cross_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
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 46c82e56d57..ae3e6bff6e7 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -2486,6 +2486,13 @@ These options influence Texinfo output.
 
    .. versionadded:: 1.1
 
+.. confval:: texinfo_cross_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:
 
diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py
index ee10d58c350..2b28ce40008 100644
--- a/sphinx/builders/texinfo.py
+++ b/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_cross_references', True, None)
 
     return {
         'version': 'builtin',
diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py
index 6df558323f9..70d007f6865 100644
--- a/sphinx/writers/texinfo.py
+++ b/sphinx/writers/texinfo.py
@@ -545,9 +545,12 @@ 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))
-        self.referenced_ids.add(sid)
-        self.referenced_ids.add(self.escape_id(id))
+        if self.config.texinfo_cross_references:
+            self.body.append('@ref{%s,,%s}' % (sid, name))
+            self.referenced_ids.add(sid)
+            self.referenced_ids.add(self.escape_id(id))
+        else:
+            self.body.append(name)
 
     # -- Visiting
 
diff --git a/tests/test_build_texinfo.py b/tests/test_build_texinfo.py
index 546ccaabf4b..f47ec813cad 100644
--- a/tests/test_build_texinfo.py
+++ b/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_cross_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