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

["Herve Boutemy (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/DOXIA-685?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Herve Boutemy updated DOXIA-685:
--------------------------------
    Summary: Replace SinkEventAttributes#BOXED with #SOURCE to clearly separate between regular verbatim and verbatim source (code)  (was: Replace SinkEventAttributes#BOXED and clearly separate between regular verbatim and verbatim source (code))

> 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, 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)