[
https://issues.apache.org/jira/browse/DOXIA-685?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17676702#comment-17676702
]
ASF GitHub Bot commented on DOXIA-685:
--------------------------------------
michael-o commented on PR #135:
URL: https://github.com/apache/maven-doxia/pull/135#issuecomment-1382142481
@hboutemy Please review on the weekend. This is the last change I want to
merge for M5 and perform a release.
> Replace SinkEventAttributes#BOXED and clearly separate between regular
> verbatim and verbatim source (code)
> ----------------------------------------------------------------------------------------------------------
>
> Key: DOXIA-685
> URL: https://issues.apache.org/jira/browse/DOXIA-685
> Project: Maven Doxia
> Issue Type: Improvement
> Components: Core
> Affects Versions: 2.0.0-M4
> Reporter: Michael Osipov
> Assignee: Michael Osipov
> Priority: Major
> Fix For: 2.0.0-M5
>
> Attachments: screenshot-1.png, screenshot-2.png, screenshot-3.png,
> screenshot-4.png
>
>
> 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, but it actually indicates that this is
> source code to be likely highlighted. It other works, from the API one does
> not know this 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
> * {{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
> * {{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}} attribut which denotes
> source code, but IF {{verbatim=true}}
> h2. Current situation for non-boxed vs boxed verbatim:
> h3. non-boxed
> h4. input
> * APT:
> {noformat}
> ----
> non-boxed verbatim text...
> ----
> {noformat}
> * Doxia Sink API:
> {noformat}
> Sink#verbatim(void);
> Sink#text(String);
> Sink#verbatim_(void);
> {noformat}
> * Markdown: TBD
> * xdoc: TBD
> h4. output
> * HTML
> {noformat}
> <div><pre>non-boxed verbatim text...</pre></div>
> {noformat}
> * 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
> !screenshot-1.png!
> h3. boxed
> h4. input
> * APT:
> {noformat}
> +----+
> boxed verbatim text...
> +----+
> {noformat}
> * Doxia Sink API:
> {noformat}
> Sink#verbatim(SinkEventAttributeSet.BOXED);
> Sink#text(String);
> Sink#verbatim_(void);
> {noformat}
> * Markdown: TBD
> * xdoc: TBD
> h4. output
> * HTML
> {noformat}
> <div class="source"><pre>boxed verbatim text...</pre></div>
> {noformat}
> 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
> {noformat}
> <div class="source"><pre class="prettyprint linenums">verbatim
> text...</pre></div>
> {noformat}
> 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
> !screenshot-2.png!
> h2. Future situation:
> h3. non-boxed
> h4. input
> {noformat}
> Sink#verbatim(void);
> Sink#text(String);
> Sink#verbatim_(void);
> {noformat}
> h4. output
> !screenshot-3.png!
> h3. source
> h4. input
> {noformat}
> Sink#verbatim(SinkEventAttributeSet.SOURCE);
> Sink#text(String);
> Sink#verbatim_(void);
> {noformat}
> h4. output
> !screenshot-4.png!
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
