From 196429c2afb3b4240fea766529b5730023fc4d69 Mon Sep 17 00:00:00 2001
From: Julien Palard <julien@palard.fr>
Date: Mon, 20 Nov 2023 13:20:16 +0100
Subject: [PATCH] Clarify escaping-backslashes at end of inline markup.

---
 README.md                            | 10 ++++++++++
 sphinxlint/checkers.py               |  9 +++++----
 sphinxlint/rst.py                    |  9 ++++++---
 tests/fixtures/xpass/ref-in-samp.rst |  2 ++
 tests/test_rst.py                    | 28 ++++++++++++++++++++++++++++
 5 files changed, 51 insertions(+), 7 deletions(-)
 create mode 100644 tests/fixtures/xpass/ref-in-samp.rst
 create mode 100644 tests/test_rst.py

diff --git a/README.md b/README.md
index afb5200ee..eb655d2d8 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,16 @@ A quick way to test if some syntax is valid from a pure
 reStructuredText point of view, one case use `docutils`'s `pseudoxml`
 writer, like:
 
+```text
+$ docutils --writer=pseudoxml <(echo '``hello``')
+<document source="/dev/fd/63">
+    <paragraph>
+        <literal>
+            hello
+```
+
+Or against a whole file:
+
 ```text
 $ docutils --writer=pseudoxml tests/fixtures/xpass/role-in-code-sample.rst
 <document source="tests/fixtures/xpass/role-in-code-sample.rst">
diff --git a/sphinxlint/checkers.py b/sphinxlint/checkers.py
index 791cac6ca..17249c32e 100644
--- a/sphinxlint/checkers.py
+++ b/sphinxlint/checkers.py
@@ -190,11 +190,12 @@ def check_missing_space_after_role(file, lines, options=None):
     Bad:  :exc:`Exception`s.
     Good: :exc:`Exceptions`\ s
     """
-    for lno, line in enumerate(lines, start=1):
-        line = clean_paragraph(line)
-        role = _SUSPICIOUS_ROLE.search(line)
+    for paragraph_lno, paragraph in paragraphs(lines):
+        paragraph = clean_paragraph(paragraph)
+        role = _SUSPICIOUS_ROLE.search(paragraph)
         if role:
-            yield lno, f"role missing (escaped) space after role: {role.group(0)!r}"
+            error_offset = paragraph[: role.start()].count("\n")
+            yield paragraph_lno + error_offset, f"role missing (escaped) space after role: {role.group(0)!r}"
 
 
 @checker(".rst", ".po")
diff --git a/sphinxlint/rst.py b/sphinxlint/rst.py
index 0e8b7b473..a19a8907c 100644
--- a/sphinxlint/rst.py
+++ b/sphinxlint/rst.py
@@ -161,11 +161,14 @@ def inline_markup_gen(start_string, end_string, extra_allowed_before=""):
     """
     if extra_allowed_before:
         extra_allowed_before = "|" + extra_allowed_before
+    # Both, inline markup start-string and end-string must not be
+    # preceded by an unescaped backslash (except for the end-string of
+    # inline literals).
+    if not (start_string == "``" and end_string == "``"):
+        end_string = f"(?<!\x00){end_string}"
+    start_string = f"(?<!\x00){start_string}"
     return re.compile(
         rf"""
-    (?<!\x00) # Both inline markup start-string and end-string must not be preceded by
-              # an unescaped backslash
-
     (?<=             # Inline markup start-strings must:
         ^|           # start a text block
         \s|          # or be immediately preceded by whitespace,
diff --git a/tests/fixtures/xpass/ref-in-samp.rst b/tests/fixtures/xpass/ref-in-samp.rst
new file mode 100644
index 000000000..85868abc3
--- /dev/null
+++ b/tests/fixtures/xpass/ref-in-samp.rst
@@ -0,0 +1,2 @@
+:samp:`"Please refer to the :ref:\`{security-considerations}\`
+section."`
diff --git a/tests/test_rst.py b/tests/test_rst.py
new file mode 100644
index 000000000..250fee07f
--- /dev/null
+++ b/tests/test_rst.py
@@ -0,0 +1,28 @@
+from sphinxlint.utils import escape2null as e2n
+from sphinxlint.rst import inline_markup_gen
+
+
+def test_inline_literals_can_end_with_escaping_backslash():
+    """See https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+    paragraph: Inline markup recognition rules
+    """
+    inline_markup_re = inline_markup_gen("``", "``")
+    assert inline_markup_re.findall(e2n(r"``\``")) == [e2n(r"``\``")]
+    assert inline_markup_re.findall(e2n(r"``\\``")) == [e2n(r"``\\``")]
+    assert inline_markup_re.findall(e2n(r"``\\\``")) == [e2n(r"``\\\``")]
+    assert inline_markup_re.findall(e2n(r"``\\\\``")) == [e2n(r"``\\\\``")]
+
+
+def test_emphasis_cannot_end_with_escaping_backslash():
+    """See https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+    paragraph: Inline markup recognition rules
+    """
+    emphasis_re = inline_markup_gen(r"\*", r"\*")
+    assert emphasis_re.findall(e2n(r"*\*")) == []
+    assert emphasis_re.findall(e2n(r"*\\*")) == [e2n(r"*\\*")]
+    assert emphasis_re.findall(e2n(r"*\\\*")) == []
+    assert emphasis_re.findall(e2n(r"*\\\\*")) == [e2n(r"*\\\\*")]
+
+    assert emphasis_re.findall(
+        e2n(r"Tous les *\*args* et *\*\*kwargs* fournis à cette fonction sont")
+    ) == [e2n(r"*\*args*"), e2n(r"*\*\*kwargs*")]