[
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
{noformat}
Sink#verbatim(void);
Sink#text(String);
Sink#verbatim_(void);
{noformat}
h4. output
!screenshot-1.png!
h3. boxed
h4. input
{noformat}
Sink#verbatim(SinkEventAttributeSet.BOXED);
Sink#text(String);
Sink#verbatim_(void);
{noformat}
h4. output
!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
{noformat}
Sink#verbatim(void);
Sink#text(String);
Sink#verbatim_(void);
{noformat}
!screenshot-1.png!
h3. boxed
{noformat}
Sink#verbatim(SinkEventAttributeSet.BOXED);
Sink#text(String);
Sink#verbatim_(void);
{noformat}
!screenshot-2.png!
h2. Future situation:
h3. non-boxed
{noformat}
Sink#verbatim(void);
Sink#text(String);
Sink#verbatim_(void);
{noformat}
!screenshot-3.png!
h3. source
{noformat}
Sink#verbatim(SinkEventAttributeSet.SOURCE);
Sink#text(String);
Sink#verbatim_(void);
{noformat}
!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
> {noformat}
> Sink#verbatim(void);
> Sink#text(String);
> Sink#verbatim_(void);
> {noformat}
> h4. output
> !screenshot-1.png!
> h3. boxed
> h4. input
> {noformat}
> Sink#verbatim(SinkEventAttributeSet.BOXED);
> Sink#text(String);
> Sink#verbatim_(void);
> {noformat}
> h4. output
> !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)
