Hi Lennart,
Thanks for picking this up!
Personally I don't like either of the two solutions you propose... :p
The APT format was above all designed to be simple, which necessarily
implies some functional limitations. Eg it is on purpose that APT does
not support styles [1], if any fancy layout features are required, like
the one we are talking about here, I would always recommend to use
something else than APT (xdoc,...).
Also, changing/enhancing a well-established format spec like APT is
likely to cause disturbance, we did it once with the Doxia 1.1 release
[2], and frankly, I wouldn't do it again.
See further comments in-line below.
Cheers,
-Lukas
[1]
http://maven.apache.org/doxia/faq.html#How_to_handle_style_in_the_APT_markup_language
[2] http://maven.apache.org/doxia/references/doxia-apt.html
Lennart Jörelid wrote:
Hello Lukas,
A question here...
It seems simple enough to add the required constants conveying the choice
to provide syntax coloring or line number visibility to Doxia's
SinkEventAttributes.
It also seems simple enough to make a smallish change to the core
SinkAdapter, to recognize more properties than the "boxed" attribute, and
to propagate this change to all relevant doxia modules.
These changes caters for the need to convey the semantics of some extra
properties to all modules. Fair enough.
However, each module interested in interpreting these new attributes in a
meaningful way must have some means to configure them in its native markup.
According to the SunkUtils class, code of all kinds is rendered within
"div" or "pre" tags - implying Verbatim SinkEventAttributes.
Confused here what you are referring to,.. the SinkUtils class doesn't
mention anything like that AFAICS and div and pre are html specific, so
shouldn't occur anywhere in the generic Sink API.
While the documentation for SinkEventAttributes.DECORATION claims that
'Generally accepted values are "underline", "overline", "line-through",
"boxed"', the SinkAdapter.verbatim() method in its current form only
recognizes the value "boxed".
To provide the ability to set optional properties (boxed, syntaxColored,
lineNumbersVisible), one could simply create more SinkEventAttributes
values. No biggie.
Note that the SinkAdapter class is just an empty base implementation, it
gets overridden by practically all low-level Sinks, see eg the
XhtmlBaseSink.
But ... taking the APT module (which seems a decently frequently used one)
as an example, we have 2 choices for markup alterations:
a) Permutations of the currently available one, or
b) Mutator elements within the verbatim block
If we choose (a), we end up with several markup permutations (with/without
syntax coloring; with/without line numbers displayed).
Currently, the only two choices in the AptMarkup interface are
BOXED_VERBATIM_START_MARKUP ("+------+") and HEADER_START_MARKUP (" -----").
What seems the dim way to solve the problem would then be simply creating
several new markup starts along the lines of:
/** Syntax for the boxed verbatim start, indicating syntax coloring
should be used: "+c-----+" */
String BOXED_VERBATIM_WITH_SYNTAX_COLORING_START_MARKUP =
String.valueOf( PLUS )
+ StringUtils.repeat( String.valueOf( MINUS ), 6 ) +
String.valueOf( PLUS );
/** Syntax for the boxed verbatim start, indicating line numbers should
be used: "+cl----+" */
String BOXED_VERBATIM_WITH_LINE_NUMBERS_START_MARKUP = String.valueOf(
PLUS )
+ StringUtils.repeat( String.valueOf( MINUS ), 6 ) +
String.valueOf( PLUS );
If we choose (b), we would be required to introduce mutators within the
verbatim markup elements - something along the lines of:
+------+ [option: [displayLineNumbers] [useSyntaxColoring]]
... code goes here ...
+------+
I prefer the latter solution, and I hope to be able to grab the last part
of the start line within the APT module given a small tweak to
the AptSink in order for it not to use the verbatim(boolean) method. Do you
have comments or suggestions for me so far?
2011/11/26 Lukas Theussl<ltheu...@apache.org>
There is a feature request for that:
https://jira.codehaus.org/browse/DOXIA-439
It's not implemented yet...
HTH,
-Lukas
On Sat, Nov 26, 2011 at 2:16 AM, Lennart Jörelid
<lennart.jore...@gmail.com>wrote:
Hello Simone,
Looking good.
So ... given that this is a skin to maven, could you include the CSS and
JS
of the syntax highlighter (i.e.
http://alexgorbatchev.com/SyntaxHighlighter/
)?
However, I guess my question is on a more fundamental level.
What do we need to do in an APT file (or one of the other site
documentation format files) to achieve pretty-printed/syntax colored
source
snippets in Java or XML?
There seems to be no mention of exactly how to craft code snippet
examples
- as far as I can see - on the
http://maven.apache.org/doxia/references/doxia-apt.html (and friends)
pages.
2011/11/26 Simone Tripodi<simonetrip...@apache.org>
Hi Lennart,
we are going to release the maven-fluido-skin[1] that does also code
prettyprint ans syntax highlight.
HTH!
Simo
[1] http://maven.apache.org/skins/maven-fluido-skin/
http://people.apache.org/~simonetripodi/
http://simonetripodi.livejournal.com/
http://twitter.com/simonetripodi
http://www.99soft.org/
On Sat, Nov 26, 2011 at 1:15 AM, Lennart Jörelid
<lennart.jore...@gmail.com> wrote:
Hello folks,
I need to include some pretty-printed and syntax coloured code
snippets
into the maven site of a set of projects.
After a tad of searching, I haven't found any plugin or extension to
Doxia that seems to do this. There seems to be
several "box text and don't ruin its formatting"-type tags and
operations - but I would like to pretty print and syntax
colour both Java and XML files.
... and I suppose this is fixed by some nice doxia-based utility
already.
Could you point me in the correct direction?
// Bästa hälsningar,
// [sw. "Best regards"
//
// Lennart Jörelid
// lennart.jore...@gmail.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org
For additional commands, e-mail: dev-h...@maven.apache.org
--
--
Lennart Jörelid
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org
For additional commands, e-mail: dev-h...@maven.apache.org