From af7f127323249da183ac02616babea5246f290d7 Mon Sep 17 00:00:00 2001
From: mgoonde <miha.gunde@gmail.com>
Date: Sat, 23 Nov 2024 14:31:04 +0000
Subject: [PATCH] add backslash as escape for alias:

such that \|foo| is not replaced, while |foo| is.
---
 docs/user_guide/writing_documentation.rst |  7 ++++++-
 ford/_markdown.py                         | 15 ++++++++++++---
 test/test_markdown.py                     | 18 +++++++++++++++++-
 3 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/docs/user_guide/writing_documentation.rst b/docs/user_guide/writing_documentation.rst
index f9656664..94f6f600 100644
--- a/docs/user_guide/writing_documentation.rst
+++ b/docs/user_guide/writing_documentation.rst
@@ -243,7 +243,7 @@ There are three predefined macros:
 - ``|media|``: the (absolute) path to the `media directory <option-media_dir>`
 - ``|page|``: the `static page directory <option-page_dir>`
 
-You can defined additional custom aliases with the `alias
+You can define additional custom aliases with the `alias
 <option-alias>` option.
 
 .. note::
@@ -262,6 +262,11 @@ You can defined additional custom aliases with the `alias
    This avoids clashes between the syntax for the two features.
 
 
+.. note::
+   An alias can be escaped with a prepended baskslash, such that `|foo|` will
+   be replaced with its alias, while `\|foo|` will be rendered as `|foo|`.
+
+
 .. _writing-links:
 
 Links
diff --git a/ford/_markdown.py b/ford/_markdown.py
index bc57d7cb..531f573c 100644
--- a/ford/_markdown.py
+++ b/ford/_markdown.py
@@ -131,9 +131,14 @@ def convert(
 
 class AliasPreprocessor(Preprocessor):
     """Substitute text aliases of the form ``|foo|`` from a dictionary
-    of aliases and their replacements"""
+    of aliases and their replacements.
+    The backslash ``\`` acts as an escape character, aliases of the
+    form ``\|foo|`` will not be replaced, but instead copied verbatim
+    without the preceding backslash.
+    """
 
-    ALIAS_RE = re.compile(r"\|([^ ].*?[^ ]?)\|")
+    # pattern to match alias only if not preceded by `\`
+    ALIAS_RE = re.compile(r"(?<!\\)\|([^ ].*?[^ ]?)\|")
 
     def __init__(self, md: Markdown, aliases: Dict[str, str]):
         self.aliases = aliases
@@ -149,7 +154,11 @@ def _lookup(self, m: re.Match):
 
     def run(self, lines: List[str]) -> List[str]:
         for line_num, line in enumerate(lines):
-            lines[line_num] = self.ALIAS_RE.sub(self._lookup, line)
+            # replace the real aliases
+            line = self.ALIAS_RE.sub(self._lookup, line)
+            # replace the escaped aliases verbatim, without the preceding `\`
+            line = re.sub(r"\\(\|([^ ].*?[^ ]?)\|)", r"\g<1>",line)
+            lines[line_num]=line
         return lines
 
 
diff --git a/test/test_markdown.py b/test/test_markdown.py
index 597edef3..7dacafb9 100644
--- a/test/test_markdown.py
+++ b/test/test_markdown.py
@@ -5,9 +5,25 @@
 
 def test_sub_alias():
     result = MetaMarkdown(aliases={"a": "b"}).convert("|a|")
-
     assert result == "<p>b</p>"
 
+    result = MetaMarkdown(aliases={"a": "b"}).convert("|undefined|")
+    assert result == "<p>|undefined|</p>"
+
+
+def test_sub_alias_escape():
+    def_alias={"a":"b"}
+
+    result = MetaMarkdown(aliases=def_alias).convert("\|a|")
+    assert result == "<p>|a|</p>"
+
+    result = MetaMarkdown(aliases=def_alias).convert("*|a|")
+    assert result == "<p>*b</p>"
+
+    result = MetaMarkdown(aliases=def_alias).convert("\|undefined|")
+    assert result == "<p>|undefined|</p>"
+
+
 
 def test_sub_alias_with_equals():
     result = MetaMarkdown(aliases={"a": "b=c"}).convert("|a|")