slachiewicz opened a new issue, #1121: URL: https://github.com/apache/maven-doxia/issues/1121
Split out of #876, whose documentation part is done (#1076 for the Markdown module, the APT reference on maven.apache.org). The Sink API has two ways to say "this verbatim block is code", and which one a Sink receives depends on the input format, not on the content: | Source | `verbatim` event | nested `inline` event | | --- | --- | --- | | APT `+--`, XDoc `<source>` | `source` decoration | none | | Markdown fenced or indented code | no attributes | `semantics=code`, `class=language-*` or `nohighlight nocode` | | XHTML5 `<pre><code>` | tag attributes only | `Semantics.CODE` | `Xhtml5BaseSink` turns both into `<pre><code>`, so HTML output looks the same. Any other Sink has to handle both forms to treat code blocks consistently, and nothing in the Sink javadoc tells an implementor so. Options: 1. Converge on one form in the parsers (for example, APT and XDoc also emit the nested `inline` with `Semantics.CODE`, or Markdown also sets the `source` decoration), keeping the other accepted by the Sinks for compatibility. 2. Keep both and document in the `Sink#verbatim` javadoc that code can arrive either way. Option 2 is cheap; option 1 changes the event stream third-party Sinks see, so it would need a note in the release notes. -- 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]
