|
| Description: |
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 Markdown syntax (raw HTML being allowed in CommonMark) for each of them, so that they can be rendered to Markdown and parsed back without loss : .
h3. Code macro and monospace
||XWiki||markdown/1.2||Parsed back as||
|Inline code macro with {{language="none"}}|code span (backticks)|inline code macro with {{language="none"}} (unchanged)|
|Standalone code macro with a language|fenced code block, the info string being the language (no info string for {{none}})|standalone code macro (unchanged)|
|Code macro without language, or with parameters that a code span or code block can't express|XWiki macro syntax : ( { noformat} { { {{ code ... }} }} ... {{ {{ /code }} }} {noformat} ) |code macro|
|Monospace {noformat}##x##{noformat} |{ noformat} { <code> x }} ... {{ </code> {noformat } } (the Markdown located inside is parsed, so formatting is kept)|monospace format|
|Standalone verbatim|
A code span or a fenced code block without info string keeps being read as a code macro with { noformat {language="none" } }, since Markdown content isn't highlighted unless a language is specified (see MARKDOWN-65). Mapping {{ < pre code > }} to monospace is aligned with XRENDERING-780 . Using a code macro for Markdown code is a temporary solution until XRENDERING-266 is implemented .
h3 . Verbatim: 3 options
Example XWiki 2.1 content:
{noformat}
a {{{**not bold** < b>x< / pre b > {noformat [[link]] } }} b
( with % class="box" %)
{{ {
**not bold**
< b>x</b> & {{info }} and y {{ & /info }} written
}}}
{noformat}
*Option A*: XWiki macro syntax with a reserved {{verbatim}} id, read back by the Markdown parser as HTML entities)|standalone verbatim | (not as a macro call, so no macro needs to be installed):
|Inline verbatim| {noformat}
a {{verbatim}}**not bold** < tt b > ... x </ tt b > [[link]] { {/verbatim}} b
{{verbatim class="box"}}
**not bold**
<b>x</b> & {{info}}y{{/info}}
{{/verbatim}}
{ noformat} (with
No escaping needed in the Markdown and HTML special characters escaped content (only a content containing an unbalanced {{{{/verbatim}}}} would need a fallback ) |inline . Parameters supported. Reuses the existing macro parsing. Downside: a macro named " verbatim | " couldn't be called from Markdown pages.
Notes *Option B* : XWiki verbatim syntax, with the XWiki parameters syntax:
* A code span or {noformat}
a fenced code block without info string keeps being read as a code macro with {{ language {**not bold** <b>x</b> [[link]]}}} b
(% class =" none box " %)
{{{
**not bold**
<b>x</b> & {{info }} , since Markdown y{{/info}}
}}}
{noformat}
Same as XWiki 2.1 and no escaping needed in the content isn (except for "}}}"). But it adds 2 new syntaxes to markdown/1.2 ({{(% ... %)}} doesn 't highlighted unless 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 language is specified separate proposal ( it would also allow to keep paragraph, group and table parameters, see MARKDOWN- 65 129 ).
* Only Option C*: HTML tags:
{ noformat}
a <tt>\*\*not bold\*\* <b>x</b> \[\[link]]</tt> b
<pre class="box">
**not bold**
<b>x</b> & { {info}}y{{/info}}
< code /pre >
{noformat }
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>}} without attributes would be recognized, the other HTML keeps being read as staying HTML macros.
h3. 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.
h3. 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>}} located in existing Markdown pages would be read as monospace and become verbatim instead of HTML macros ( which renders almost the same).
* Mapping a {{< code pre >}} to monospace is aligned with XRENDERING-780 containing HTML markup staying an HTML macro) . Using
* Content already turned into code macros by a previous WYSIWYG edit stays as code macro for Markdown code macros (no migration).
Option A is a temporary solution until XRENDERING-266 is implemented the preferred one .
Forum proposal: (link to be added) https://forum.xwiki.org/t/distinct-markdown-syntaxes-for-code-macros-verbatim-and-monospace-in-markdown-1-2/19057 |
|
