[
https://issues.apache.org/jira/browse/DOXIA-685?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Herve Boutemy updated DOXIA-685:
--------------------------------
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, 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!
was:
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}
----
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>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}
+----+
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><pre>verbatim text...</pre></div>
{noformat}
* 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!
> 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)
