Fix escape chars in references

jaapio · jaapio · commit f2be08df0f22 · 2025-11-07T15:51:05.000+01:00
diff --git a/packages/guides-restructured-text/src/RestructuredText/Parser/References/EmbeddedReferenceParser.php b/packages/guides-restructured-text/src/RestructuredText/Parser/References/EmbeddedReferenceParser.php
@@ -14,14 +14,15 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\References;
 
 use function preg_match;
+use function str_replace;
 use function trim;
 
 trait EmbeddedReferenceParser
 {
     /**
-     * https://regex101.com/r/KadqKx/1
+     * https://regex101.com/r/8O8N3h/2
      */
-    private string $referenceRegex = '/^(.*?)(<([^<]+)>)?$/s';
+    private string $referenceRegex = '/^(.*?)((?<!\\\\)<([^<]+)(?<!\\\\)>)?$/s';
 
     private function extractEmbeddedReference(string $text): ReferenceData
     {
@@ -37,6 +38,9 @@ private function extractEmbeddedReference(string $text): ReferenceData
             $text = null;
         }
 
-        return new ReferenceData($reference, $text);
+        return new ReferenceData(
+            str_replace(['\\<', '\\>'], ['<', '>'], $reference),
+            $text,
+        );
     }
 }
diff --git a/packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php b/packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php
@@ -174,6 +174,10 @@ public static function inlineNodeProvider(): array
                 '`myref`_',
                 new InlineCompoundNode([new HyperLinkNode('myref', 'myref')]),
             ],
+            'Named Reference, escaped phrase' => [
+                '`myref \<foo\>`_',
+                new InlineCompoundNode([new HyperLinkNode('myref <foo>', 'myref <foo>')]),
+            ],
             'Named Reference, Phrased, With URL' => [
                 '`myref <https://test.com>`_',
                 new InlineCompoundNode([new HyperLinkNode('myref', 'https://test.com')]),
diff --git a/tests/Integration/tests/references/reference-with-escape/expected/index.html b/tests/Integration/tests/references/reference-with-escape/expected/index.html
@@ -8,9 +8,7 @@
 <!-- content start -->
     <div class="section" id="the-head">
     <h1>the &lt;head&gt;</h1>
-
-            <a id="anchor"></a>
-        <p>See also <a href="/index.html#anchor">the &lt;head&gt; of this file</a> or <a href="/index.html#the-head">the &lt;head&gt;</a>.</p>
+        <p>See also this is a complex reference <a href="/index.html#the-head">the &lt;head&gt;</a>.</p>
     </div>
 
 <!-- content end -->
diff --git a/tests/Integration/tests/references/reference-with-escape/input/index.rst b/tests/Integration/tests/references/reference-with-escape/input/index.rst
@@ -1,6 +1,4 @@
-.. _anchor:
-
-the \<head\>
+the <head>
 ============
 
-See also :ref:`the \<head\> of this file <anchor>` or `the \<head\>`_.
+See also this is a complex reference `the \<head\>`_.
diff --git a/tests/Integration/tests/references/reference-with-escape/input/skip b/tests/Integration/tests/references/reference-with-escape/input/skip

Original file line number	Diff line number	Diff line change
`@@ -14,14 +14,15 @@`
`14`	`14`	`namespace phpDocumentor\Guides\RestructuredText\Parser\References;`
`15`	`15`
`16`	`16`	`use function preg_match;`
	`17`	`+use function str_replace;`
`17`	`18`	`use function trim;`
`18`	`19`
`19`	`20`	`trait EmbeddedReferenceParser`
`20`	`21`	`{`
`21`	`22`	`/**`
`22`		`- * https://regex101.com/r/KadqKx/1`
	`23`	`+ * https://regex101.com/r/8O8N3h/2`
`23`	`24`	`*/`
`24`		`- private string $referenceRegex = '/^(.*?)(<([^<]+)>)?$/s';`
	`25`	`+ private string $referenceRegex = '/^(.*?)((?<!\\\\)<([^<]+)(?<!\\\\)>)?$/s';`
`25`	`26`
`26`	`27`	`private function extractEmbeddedReference(string $text): ReferenceData`
`27`	`28`	`{`
`@@ -37,6 +38,9 @@ private function extractEmbeddedReference(string $text): ReferenceData`
`37`	`38`	`$text = null;`
`38`	`39`	`}`
`39`	`40`
`40`		`- return new ReferenceData($reference, $text);`
	`41`	`+ return new ReferenceData(`
	`42`	`+ str_replace(['\\<', '\\>'], ['<', '>'], $reference),`
	`43`	`+ $text,`
	`44`	`+ );`
`41`	`45`	`}`
`42`	`46`	`}`