slachiewicz commented on issue #876: URL: https://github.com/apache/maven-doxia/issues/876#issuecomment-5227117706
Picked this up. Two PRs cover the documentation the issue asks for; the behavioural question underneath it I have left alone deliberately. - apache/maven-doxia-site#70 — the APT reference. It still describes `+--` as drawing a box, which is the pre Doxia 2 `BOXED` wording. Replaced with what the two forms actually emit and which to reach for. - #1076 — the Markdown module page, which said nothing about code blocks, plus a correction to the `MarkdownHtmlParser` javadoc. ### Current state, verified against master Confirming @kwin's table, which still holds, with the sink output added: | Source | verbatim event | nested inline event | rendered | | --- | --- | --- | --- | | APT `+--` | `source` decoration | — | `<pre><code>` | | APT `---` | no attributes | — | `<pre>` | | XDoc `<source>` | `source` decoration | — | `<pre><code>` | | XHTML5 `<pre>` | tag attributes only | — | `<pre>` | | XHTML5 `<pre><code>` | tag attributes only | `Semantics.CODE` | `<pre><code>` | | Markdown ` ```java ` | no attributes | `semantics=code`, `class=language-java` | `<pre><code class="language-java">` | | Markdown ` ``` ` | no attributes | `semantics=code`, `class=nohighlight nocode` | `<pre><code class="nohighlight nocode">` | | Markdown indented | no attributes | `semantics=code`, `class=nohighlight nocode` | `<pre><code class="nohighlight nocode">` | `Xhtml5BaseSink.verbatim(SinkEventAttributes)` opens the `CODE` element only when the decoration is `source`, so both representations land on `<pre><code>` in XHTML5 output; they differ in what a Sink other than XHTML5 sees. One thing worth flagging, found while writing this up: the `MarkdownHtmlParser` javadoc claims PRE elements are marked as `source` so the sink wraps them in `<div class="source">` for the skins. Neither half of that is true any more — there is no `div` wrapper in `Xhtml5BaseSink` and Markdown sets no decoration. That is fixed in #1076. ### What the docs cannot settle There are two representations of "this is code" in the Sink API, `source` on the `verbatim` event and `Semantics.CODE` on a nested `inline` event, and which one you get depends on the input format rather than on anything meaningful. A Sink that is not the XHTML5 one has to handle both to treat code blocks consistently, and a Sink implementor has nothing telling them that. Documenting it, as these PRs do, is worth doing either way. But if the intent is that the two should converge, the docs will need rewriting when they do, so it may be worth deciding that first. Happy to open a separate issue for the convergence question if that is useful. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
