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

["ASF GitHub Bot (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DOXIA-685?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17679529#comment-17679529 ] 

ASF GitHub Bot commented on DOXIA-685:
--------------------------------------

hboutemy commented on code in PR #135:
URL: https://github.com/apache/maven-doxia/pull/135#discussion_r1083418332


##########
doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/AbstractSinkTest.java:
##########
@@ -115,9 +115,9 @@ public final void testTestDocument() throws IOException {
     }
 
     /**
-     * Checks that the sequence <code>[title(), text( title ), title_()]</code>,
+     * Checks that the sequence <code>[title(), text(title), title_()]</code>,

Review Comment:
   these javadoc formatting updates add noise to the change: can we split them in a different PR (no need for any Jira issue...)





> Replace SinkEventAttributes#BOXED with #SOURCE to 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 (see [APT spec|https://maven.apache.org/doxia/references/apt-format.html#verbatim-text] and its use for [xdoc source|https://maven.apache.org/doxia/references/xdoc-format.html#The_.3Csource.3E_tag]): 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}}
> 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)