Skip to content

Commit

Permalink
feat: asciidoc universal escaping
Browse files Browse the repository at this point in the history
Replace escaping based on passthroughs without universal escaping based on character substitutions: https://docs.asciidoctor.org/asciidoc/latest/subs/replacements/

fix #763
  • Loading branch information
alandefreitas committed Dec 13, 2024
1 parent be64902 commit e2ae861
Show file tree
Hide file tree
Showing 110 changed files with 3,751 additions and 2,655 deletions.
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[source,cpp,subs="verbatim,macros,-callouts"]
[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
{{> @partial-block }}
Expand Down
Original file line number Diff line number Diff line change
@@ -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 }}
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@

{{>location/source dcl=(primary_location symbol)}}


{{> symbol/signatures symbol }}
{{/unless}}
{{! Tranches }}
Expand Down
18 changes: 9 additions & 9 deletions share/mrdocs/addons/generator/html/partials/symbol.html.hbs
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@
{{#each symbol.doc.exceptions}}
<tr>
<td><code>{{exception}}</code></td>
<td>{{description}}</td>
<td>{{{description}}}</td>
</tr>
{{/each}}
</tbody>
Expand All @@ -156,7 +156,7 @@
{{#each allExceptions as |exception|}}
<tr>
<td><code>{{exception}}</code></td>
<td>{{description}}</td>
<td>{{{description}}}</td>
</tr>
{{/each}}
</tbody>
Expand Down Expand Up @@ -188,7 +188,7 @@
{{#each symbol.doc.tparams}}
<tr>
<td><strong>{{name}}</strong></td>
<td>{{description}}</td>
<td>{{{description}}}</td>
</tr>
{{/each}}
</tbody>
Expand All @@ -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>
Expand All @@ -236,7 +236,7 @@
{{#each symbol.doc.params}}
<tr>
<td><strong>{{name}}</strong></td>
<td>{{description}}</td>
<td>{{{description}}}</td>
</tr>
{{/each}}
</tbody>
Expand All @@ -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>
Expand All @@ -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}}
Expand All @@ -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}}
Expand All @@ -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}}
Expand Down
93 changes: 93 additions & 0 deletions src/lib/Gen/adoc/AdocEscape.cpp
Original file line number Diff line number Diff line change
@@ -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
34 changes: 34 additions & 0 deletions src/lib/Gen/adoc/AdocEscape.hpp
Original file line number Diff line number Diff line change
@@ -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
29 changes: 5 additions & 24 deletions src/lib/Gen/adoc/AdocGenerator.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand All @@ -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
Expand All @@ -65,5 +47,4 @@ makeAdocGenerator()
return std::make_unique<adoc::AdocGenerator>();
}

} // mrdocs
} // clang
} // clang::mrdocs
Loading

0 comments on commit e2ae861

Please sign in to comment.