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

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 2.0.0-M4
• Fix Version/s: 2.0.0-M5, 2.0.0
• Component/s: Core
• Assignee: Michael Osipov
• Reporter: Michael Osipov
• Created: 09/Jan/23 11:29
• Updated: 24/Nov/24 10:05
• Resolved: 22/Jan/23 18:21

Description

Currently, verbatim text is inconsistently handled in the Sink API and formats apt, xhtml5, xdoc, fml and markdown.

BOXED implies that some both should be rendered in the output (see APT spec and its use for xdoc source): since introduction of source code highlighting in skins, apt boxed more importantly indicates that this is source code to be likely highlighted.

In other words, from the API does not know this mix between boxed and source and about the look and feel at the end the output format and styling should decide rather than the sink.

For those reasons the following change is proposed:

• BOXED as original name will be deprecated and then removed w/o replacement (SOURCE is not really a replacement for the boxing)
• Sink#verbatim() and Sink#verbatim(null) will print verbatim text w/o any implications
• The Xhtml5Sink will make add to every verbatim block <div class="verbatim"> instead of no class
• instead of BOXED, SinkEventAttributes#SOURCE to explicitly denotimate verbatim source code, Xhtml5Sink will add <div class="verbatim source">, the Apt format will turn -...- to verbatim source as well.
• The EchoMacro and SnippetMacro won't use BOXED anymore
• The SnippetMacro will have a source=true attribute which denotes source code, but only IF verbatim=true

Current situation for non-boxed vs boxed verbatim:

non-boxed

input

• APT:

  ----
  non-boxed verbatim text...
  ----
  

• Doxia Sink API:

  Sink#verbatim(void);
  Sink#text(String);
  Sink#verbatim_(void);
  

• Markdown: TBD
• xdoc: TBD

output

• HTML

  <div><pre>non-boxed verbatim text...</pre></div>
  

• HTML + CSS visual
  a CSS border: 1px ... is displayed in Fluido Skin (version?), that should not happen in a non-boxed case...
  rendered example on https://github.com/apache/maven-site/blob/master/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
  

boxed

input

• APT:

  +----+
  boxed verbatim text...
  +----+
  

• Doxia Sink API:

  Sink#verbatim(SinkEventAttributeSet.BOXED);
  Sink#text(String);
  Sink#verbatim_(void);
  

• Markdown: TBD
• xdoc: TBD

output

• HTML

  <div class="source"><pre>boxed verbatim text...</pre></div>
  

  TBD: what is precisely done at Doxia level when rendering HTML, what is done at skin level server-side, what is done by JS/CSS at skin level browser time

• HTML + CSS visual

  <div class="source"><pre class="prettyprint linenums">verbatim text...</pre></div>
  

  HTML result is not focused on boxing or not boxing, but on source hightlighting and linenums (reason: this has been done over years, when introducing source code highlighting in Fluido, and discovering that what we needed in apt was more about activating/disabling highlighting, not so much about boxing. But this was never really specified anywhere, just explaining history 10 years after the fact)
  rendered example on https://github.com/apache/maven-site/blob/master/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
  

Future situation:

non-boxed

input

Sink#verbatim(void);
Sink#text(String);
Sink#verbatim_(void);

output

source

input

Sink#verbatim(SinkEventAttributeSet.SOURCE);
Sink#text(String);
Sink#verbatim_(void);

output

Issue Links

• causes: MSKINS-245 Maven Site 4 will break code highlight of site generated by Markdown
• causes: MSHARED-1182 Drop incorrect usage of SinkEventAttributeSet#BOXED
• is related to: MPIR-412 Dependency report generates non-well-formed output if the POM of a depdendency cannot be parsed
• is related to: DOXIA-762 Clarify code highlighting for verbatim text in Markdown and APT
• is related to: DOXIA-731 Simplify HTML emitted from Sink.verbatim(...)
• requires: MSKINS-221 Update template to reflect verbatim block changes in Doxia 2.0.0-M6
• links to: GitHub Pull Request #135