Author: ltheussl
Date: Wed May 20 09:49:13 2009
New Revision: 776639
URL: http://svn.apache.org/viewvc?rev=776639&view=rev
Log:
Add more info on issues with Doxia 1.1
Modified:
maven/doxia/site/src/site/apt/downloads.apt
maven/doxia/site/src/site/apt/issues/index.apt
maven/doxia/site/src/site/apt/references/doxia-apt.apt
Modified: maven/doxia/site/src/site/apt/downloads.apt
URL:
http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/downloads.apt?rev=776639&r1=776638&r2=776639&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/downloads.apt (original)
+++ maven/doxia/site/src/site/apt/downloads.apt Wed May 20 09:49:13 2009
@@ -31,8 +31,9 @@
Releases of Maven Doxia are made available in both binary and source
distributions.
Individual JARs are also made available through Apache Maven repositories.
- * {{{http://repo2.maven.org/maven2/org/apache/maven/doxia/}Doxia 1.1}}
+ Releases of all Doxia sub-projects (currently Doxia, Doxia Sitetools and
Doxia Tools)
+ may be downloaded from Maven's central repository:
- * {{{http://repo2.maven.org/maven2/org/apache/maven/doxia/}Doxia 1.0}}
+ * {{http://repo2.maven.org/maven2/org/apache/maven/doxia/}}
[]
\ No newline at end of file
Modified: maven/doxia/site/src/site/apt/issues/index.apt
URL:
http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/issues/index.apt?rev=776639&r1=776638&r2=776639&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/issues/index.apt (original)
+++ maven/doxia/site/src/site/apt/issues/index.apt Wed May 20 09:49:13 2009
@@ -29,15 +29,65 @@
Doxia Issues & Gotchas
This document collects some infos about specific issues and 'gotchas' when
working with Doxia.
+ Please check also the {{{../faq.apt}Frequently Asked Questions}}.
%{toc|section=1|fromDepth=1|toDepth=1}
+* {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 {{{../references/doxia-apt.html#Anchors}anchors}}
+ and {{{../references/doxia-apt.html#Links}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 {{{http://jira.codehaus.org/browse/MPDF-11}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 {{{http://jira.codehaus.org/browse/DOXIA-316}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 {{{../macros/index.html#TOC_Macro}macro guide}}.
+
+* {Verbatim blocks not boxed}
+
+ There was a particular {{{http://jira.codehaus.org/browse/DOXIA-297}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 );
@@ -47,16 +97,16 @@
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.
@@ -66,9 +116,9 @@
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}
Modified: maven/doxia/site/src/site/apt/references/doxia-apt.apt
URL:
http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/references/doxia-apt.apt?rev=776639&r1=776638&r2=776639&view=diff
==============================================================================
--- maven/doxia/site/src/site/apt/references/doxia-apt.apt (original)
+++ maven/doxia/site/src/site/apt/references/doxia-apt.apt Wed May 20 09:49:13
2009
@@ -155,7 +155,8 @@
{{{standalone.html}Standalone}}
---
- will be interpreted as an internal link. Since you most likely meant to
+ will be interpreted as an internal link (dots are valid characters in
anchor names).
+ Since you most likely meant to
link to another source document, you should again prepend a "./".
* An <<external>> link is a link that is neither local nor internal.
