Represent code macros, verbatim and monospace with distinct syntaxes in CommonMark Markdown 1.2

The code macro, verbatim and monospace are all rendered as Markdown code spans or code blocks, and the Markdown parser reads code spans and code blocks back as code macros. Thus verbatim and monospace content becomes a code macro after a round trip (and the formatting located inside monospace is lost), and a code macro without language gets a language="none" parameter.

The idea is to use a distinct syntax for each of them, so that they can be rendered to Markdown and parsed back without loss.

Code macro and monospace

A code span or a fenced code block without info string keeps being read as a code macro with language="none", since Markdown content isn't highlighted unless a language is specified (see MARKDOWN-65). Mapping <code> to monospace is aligned with XRENDERING-780. Using a code macro for Markdown code is a temporary solution until XRENDERING-266 is implemented.

Verbatim: 3 options

Example XWiki 2.1 content:

a {{{**not bold** <b>x</b> [[link]]}}} b

(% class="box" %)
{{{
**not bold**
<b>x</b> & {{info}}y{{/info}}
}}}

Option A: XWiki macro syntax with a reserved verbatim id, read back by the Markdown parser as verbatim (not as a macro call, so no macro needs to be installed):

a {{verbatim}}**not bold** <b>x</b> [[link]]{{/verbatim}} b

{{verbatim class="box"}}
**not bold**
<b>x</b> & {{info}}y{{/info}}
{{/verbatim}}

No escaping needed in the content (only a content containing an unbalanced {{/verbatim}} would need a fallback). Parameters supported. Reuses the existing macro parsing. Downside: a macro named "verbatim" couldn't be called from Markdown pages.

Option B: XWiki verbatim syntax, with the XWiki parameters syntax:

a {{{**not bold** <b>x</b> [[link]]}}} b

(% class="box" %)
{{{
**not bold**
<b>x</b> & {{info}}y{{/info}}
}}}

Same as XWiki 2.1 and no escaping needed in the content (except for "}}}"). But it adds 2 new syntaxes to markdown/1.2 ((% ... %) doesn't exist in it today), the literal text "{" and "(%" located elsewhere needs to be escaped, and existing Markdown pages containing them would change meaning. Supporting {{(% ... %) for all elements could be a separate proposal (it would also allow to keep paragraph, group and table parameters, see MARKDOWN-129).

Option C: HTML tags:

a <tt>\*\*not bold\*\* &lt;b&gt;x&lt;/b&gt; \[\[link]]</tt> b

<pre class="box">
**not bold**
&lt;b&gt;x&lt;/b&gt; &amp; {{info}}y{{/info}}
</pre>

Rendered nicely by other Markdown tools. But the Markdown located inside <tt> is parsed, so the content needs both Markdown escaping (backslashes) and HTML escaping (entities), and the content of <pre> needs HTML escaping. Only <tt> and <pre> would be recognized, other HTML staying HTML macros.

Other Markdown readers

Backticks, fences and <code> are displayed correctly by other Markdown readers (GitHub, IDEs, etc.). With options A and B, the tags are displayed as plain text and the content is interpreted as Markdown, which is already the case for all the XWiki macros used in markdown/1.2 pages. With option C, the content is displayed correctly.

Impact on existing pages written in Markdown

• The Markdown source of existing pages isn't modified, only the way some constructs are parsed changes.
• Backticks and fenced code blocks: no change.
• Hand-written <code> (without attributes): HTML macro today, monospace after the change (renders almost the same).
• Verbatim: no change with option A (unless a wiki has its own macro named "verbatim"); with option B, literal "{{{" and "(%" text would change meaning; with option C, hand-written <tt> and <pre> would become verbatim (a <pre> containing HTML markup staying an HTML macro).
• Content already turned into code macros by a previous WYSIWYG edit stays as code macros (no migration).

Option A is the preferred one.

Forum proposal: https://forum.xwiki.org/t/distinct-markdown-syntaxes-for-code-macros-verbatim-and-monospace-in-markdown-1-2/19057