feat: asciidoc universal escaping

Replace escaping based on passthroughs without universal escaping based on character substitutions: https://docs.asciidoctor.org/asciidoc/latest/subs/replacements/

fix cppalliance#763

Author: alandefreitas

share/mrdocs/addons/generator/adoc/partials/markup/code-block.adoc.hbs

@@ -1,4 +1,4 @@
-[source,cpp,subs="verbatim,macros,-callouts"]
+[source,cpp,subs="verbatim,replacements,macros,-callouts"]
 ----
 {{> @partial-block }}
 

share/mrdocs/addons/generator/adoc/partials/markup/h.adoc.hbs

@@ -1,3 +1,3 @@
 {{#if id}}[#{{{id}}}]
 {{/if}}
-={{select level (repeat "=" level) (select @root.config.multipage "==" "=")}} {{> @partial-block }}
+={{{select level (repeat "=" level) (select @root.config.multipage "==" "=")}}} {{> @partial-block }}

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -28,6 +28,7 @@
 
 {{>location/source dcl=(primary_location symbol)}}
 
+
 {{> symbol/signatures symbol }}
 {{/unless}}
 {{! Tranches }}

share/mrdocs/addons/generator/html/partials/symbol.html.hbs

@@ -133,7 +133,7 @@
 {{#each symbol.doc.exceptions}}
 <tr>
 <td><code>{{exception}}</code></td>
-<td>{{description}}</td>
+<td>{{{description}}}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -156,7 +156,7 @@
 {{#each allExceptions as |exception|}}
 <tr>
 <td><code>{{exception}}</code></td>
-<td>{{description}}</td>
+<td>{{{description}}}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -188,7 +188,7 @@
 {{#each symbol.doc.tparams}}
 <tr>
 <td><strong>{{name}}</strong></td>
-<td>{{description}}</td>
+<td>{{{description}}}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -211,7 +211,7 @@
 {{#each allTParams as |param|}}
 <tr>
 <td><strong>{{param.name}}</strong></td>
-<td>{{param.description}}</td>
+<td>{{{param.description}}}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -236,7 +236,7 @@
 {{#each symbol.doc.params}}
 <tr>
 <td><strong>{{name}}</strong></td>
-<td>{{description}}</td>
+<td>{{{description}}}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -259,7 +259,7 @@
 {{#each allParams as |param|}}
 <tr>
 <td><strong>{{param.name}}</strong></td>
-<td>{{param.description}}</td>
+<td>{{{param.description}}}</td>
 </tr>
 {{/each}}
 </tbody>
@@ -273,7 +273,7 @@
 <div>
 {{#> markup/dynamic-level-h level=2 }}Preconditions{{/markup/dynamic-level-h}}
 {{#each symbol.doc.preconditions}}
-<p>{{.}}</p>
+<p>{{{.}}}</p>
 {{/each}}
 </div>
 {{/if}}
@@ -282,7 +282,7 @@
 <div>
 {{#> markup/dynamic-level-h level=2 }}Postconditions{{/markup/dynamic-level-h}}
 {{#each symbol.doc.postconditions}}
-<p>{{.}}</p>
+<p>{{{.}}}</p>
 {{/each}}
 </div>
 {{/if}}
@@ -291,7 +291,7 @@
 <div>
 {{#> markup/dynamic-level-h level=2 }}See Also{{/markup/dynamic-level-h}}
 {{#each symbol.doc.see}}
-<p>{{.}}</p>
+<p>{{{.}}}</p>
 {{/each}}
 </div>
 {{/if}}

src/lib/Gen/adoc/AdocEscape.cpp

@@ -0,0 +1,93 @@
+//
+// This is a derivative work. originally part of the LLVM Project.
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#include "AdocEscape.hpp"
+#include <mrdocs/Support/Handlebars.hpp>
+
+namespace clang::mrdocs::adoc {
+
+namespace {
+
+constexpr
+std::optional<std::string_view>
+HTMLNamedEntity(char const c)
+{
+    // If c has a named entity, we use it
+    // Otherwise, we return std::nullopt
+    switch (c)
+    {
+        case '~': return "&tilde;";
+        case '^': return "&circ;";
+        case '_': return "&lowbar;";
+        case '*': return "&ast;";
+        case '`': return "&grave;";
+        case '#': return "&num;";
+        case '[': return "&lsqb;";
+        case ']': return "&rsqb;";
+        case '{': return "&lcub;";
+        case '}': return "&rcub;";
+        case '<': return "&lt;";
+        case '>': return "&gt;";
+        case '\\': return "&bsol;";
+        case '|': return "&verbar;";
+        case '-': return "&hyphen;";
+        case '=': return "&equals;";
+        case '&': return "&amp;";
+        case ';': return "&semi;";
+        case '+': return "&plus;";
+        case ':': return "&colon;";
+        case '.': return "&period;";
+        case '"': return "&quot;";
+        case '\'': return "&apos;";
+        case '/': return "&sol;";
+        default:
+            break;
+        }
+    return {};
+}
+
+} // (anon)
+
+void
+AdocEscape(OutputRef& os, std::string_view str)
+{
+    static constexpr char reserved[] = R"(~^_*`#[]{}<>\|-=&;+:."\'/)";
+    for (char c: str)
+    {
+        if (std::ranges::find(reserved, c) != std::end(reserved))
+        {
+            // https://docs.asciidoctor.org/asciidoc/latest/subs/replacements/
+            if (auto e = HTMLNamedEntity(c))
+            {
+                os << *e;
+            }
+            else
+            {
+                os << "&#" << static_cast<int>(c) << ';';
+            }
+        }
+        else
+        {
+            os << c;
+        }
+    }
+}
+
+std::string
+AdocEscape(std::string_view str) {
+    std::string res;
+    OutputRef os(res);
+    AdocEscape(os, str);
+    return res;
+}
+
+
+} // clang::mrdocs::adoc

src/lib/Gen/adoc/AdocEscape.hpp

@@ -0,0 +1,34 @@
+//
+// This is a derivative work. originally part of the LLVM Project.
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2023 Vinnie Falco ([email protected])
+// Copyright (c) 2024 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_LIB_GEN_ADOC_ADOCESCAPE_HPP
+#define MRDOCS_LIB_GEN_ADOC_ADOCESCAPE_HPP
+
+#include <mrdocs/Support/Handlebars.hpp>
+#include <string>
+#include <string_view>
+
+namespace clang::mrdocs::adoc {
+
+/** Escape a string for use in AsciiDoc
+  */
+MRDOCS_DECL
+void
+AdocEscape(OutputRef& os, std::string_view str);
+
+MRDOCS_DECL
+std::string
+AdocEscape(std::string_view str);
+
+} // clang::mrdocs::adoc
+
+#endif

src/lib/Gen/adoc/AdocGenerator.cpp

@@ -10,11 +10,11 @@
 //
 
 #include "AdocGenerator.hpp"
+#include "AdocEscape.hpp"
 #include "DocVisitor.hpp"
 #include <mrdocs/Support/Handlebars.hpp>
 
-namespace clang {
-namespace mrdocs {
+namespace clang::mrdocs {
 namespace adoc {
 
 AdocGenerator::
@@ -34,27 +34,9 @@ toString(hbs::HandlebarsCorpus const& c, doc::Node const& I) const
 
 void
 AdocGenerator::
-escape(OutputRef& os, std::string_view str) const
+escape(OutputRef& os, std::string_view const str) const
 {
-    static constexpr std::string_view formattingChars = "\\`*_{}[]()#+-.!|";
-    bool const needsEscape = str.find_first_of(formattingChars) != std::string_view::npos;
-    if (needsEscape)
-    {
-        os << "pass:[";
-        // Using passthroughs to pass content (without substitutions) can couple
-        // your content to a specific output format, such as HTML.
-        // In these cases, you should use conditional preprocessor directives
-        // to route passthrough content for different output formats based on
-        // the current backend.
-        // If we would like to couple passthrough content to an HTML format,
-        // then we'd use `HTMLEscape(os, str)` instead of `os << str`.
-        os << str;
-        os << "]";
-    }
-    else
-    {
-        os << str;
-    }
+    AdocEscape(os, str);
 }
 
 } // adoc
@@ -65,5 +47,4 @@ makeAdocGenerator()
     return std::make_unique<adoc::AdocGenerator>();
 }
 
-} // mrdocs
-} // clang
+} // clang::mrdocs