Apt anchors and links

Using Doxia 1.1 you may see a lot of warnings when processing old Apt source files:

[WARNING] [Apt Parser] Ambiguous link: 'doxia-apt.html'. If this is a local link, prepend "./"!

and

[WARNING] [Apt Parser] Modified invalid link: references/doxia-apt.html

The reason is that in Apt, links to other source documents have to start with either ./ or ../ to distinguish them from internal links. Please read the sections on anchors and links in our Apt guide. Note in particular that internal links in Apt do not start with '#'.

You should pay attention to these warnings since your links will most likely be broken. Unfortunately, the warning message cannot indicate the source file with the broken link (see eg MPDF-11), however, if you run in DEBUG mode, eg invoke maven with the -X switch, you can see which source document is being parsed when the warning is emitted.

TOC macro issues

There was a particular bug in the TOC macro in version 1.0 that has been fixed but leads to a backward incompatibility in some cases. If you have specified the section parameter in your TOC, as for instance:

%{toc|section=1|fromDepth=1|toDepth=1}

then the generated TOC is probably different from the result with Doxia 1.0. In Doxia 1.1, depth=1 is section, depth=2 is sub-section, etc, as documented in the macro guide.

Verbatim blocks not boxed

There was a particular bug in Doxia 1.0 that verbatim blocks were always boxed. If after an upgrade to Doxia 1.1 you find that your blocks are not boxed anymore, check that you actually start your verbatim block with +-- (and not ---).

Figure sink events

Doxia distinguishes between figures, which are block-level elements, and images (or icons), which are in-line elements. For instance, the following sequence of sink events

sink.figure( null );

sink.figureGraphics( "figure.png", null );

sink.figureCaption( null );
sink.text( "Figure caption", null );
sink.figureCaption_();

sink.figure_();

should output the equivalent of this html snippet:

<div class="figure">
  <p><img src="figure.png"/></p>
  <p>Figure caption</p>
</div>

while the figureGraphics( ... ); event alone can be used to generate an in-line image, i.e. just the <img> tag in case of html.

Note that we are using the forms that take a SinkEventAttributeSet above, even though we are just passing in null values. The reason is that the alternative forms (without SinkEventAttributeSet) have a different behavior, which is kept for backward compatibility (but the methods have been deprecated). Using the same sequence of sink events as above, but omitting the null method parameters, will generate

<img src="figure.png" alt="Figure caption"/>

Empty Generated Page

After running mvn site using your Maven reporting plugin, you see that the generated page is empty. Be sure that the the code calls sink.close().