[DOXIA-762] Clarify code highlighting for verbatim text in Markdown and APT

[jira-importer]

Konrad Windszus opened DOXIA-762 and commented

Currently it is undocumented how to emit Sink.verbatim(SinkEventAttributes) blocks with/without the SinkEventAttributeSet.SOURCE argument.

• For APT it is verbatim with source if using delimiter +--, verbatim without if using delimiter ---. However in https://maven.apache.org/doxia/references/apt-format.html#verbatim-text only boxed and unboxed verbatim is described.
• For MD it is verbatim with source if fenced code with info string, e.g. ````java` and verbatim without source if fenced code without info string (`````). That is currently not mentioned at all in https://maven.apache.org/doxia/modules/index.html#Markdown nor in https://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-markdown/index.html.

---

Issue Links:

• DOXIA-685 Replace SinkEventAttributes#BOXED with #SOURCE to clearly separate between regular verbatim and verbatim source (code)

• DOXIA-763 MarkdownSink: Distinguish between verbatim with source attribute and without

[kwin]

The situation right now differs a lot between the different markup parsers:

1. AptParser

• +--: Sink.verbatim(SinkEventAttributeSet(DECORATION, "source"))
• ---: Sink.verbatim(null)

2. MarkdownParser:

• ```: <pre><code class="nohighlight nocode"> -> Sink.verbatim(); Sink.inline(new SinkEventAttributeSet("semantics", "code", "class", "nohighlight nocode"))
• ```java: <pre><code class="language-java"> -> Sink.verbatim(); Sink.inline(new SinkEventAttributeSet("semantics", "code", "class", "language-java"))

3. XDocParser:

• <source>: Sink.verbatim(new SinkEventAttributeSet(DECORATION, "source"))

4. XHTML5Parser

• <pre>: Sink.verbatim(null)
• <pre><code>: Sink.verbatim(null); Sink.inline(SinkEventAttributeSet.Semantics.CODE)

Particularly the class nohighlight seems to be very specific to https://highlightjs.readthedocs.io/en/latest/readme.html?highlight=nohighlight#ignoring-a-code-block while nocode is specific to https://github.com/googlearchive/code-prettify?tab=readme-ov-file#how-do-i-prevent-a-portion-of-markup-from-being-marked-as-code