[
https://issues.apache.org/jira/browse/DOXIA-685?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17657850#comment-17657850
]
Herve Boutemy commented on DOXIA-685:
-------------------------------------
??I don't expect that it will be so complicated??
yes, precisely defining a user-visible change in Doxia requires to describe
more layers that what we would expect:
- Doxia Sink API and markup formats
- HTML output (done by Doxia rendering)
- CSS capabilities added by skins
we never described anything precisely until now, because we never managed to
have multiple people interacting at the same time: this is what we are doing now
we'll need to make the logic clear for the future
> 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}
> ----
> 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
> 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)
