Hi,
I would like to forward this message from doxia-dev. It outlines upcoming
changes to the way links and anchors in APT will be handled.
Keeping these rules in mind when writing/updating your plugin docs may
prevent some bad surprise later on.
Benjamin
[0] http://www.nabble.com/link-anchors-in-apt-to17207340.html
----- Original Message -----
From: "Lukas Theussl" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Tuesday, May 13, 2008 2:40 PM
Subject: link/anchors in apt
Hi,
I'd like to fix http://jira.codehaus.org/browse/DOXIA-208 in beta-1 still
to avoid possible breaking changes later on. I am a bit confused about APT
though as we seem to have a lot of different standards floating around in
our own docs. Just to make sure I am on the right track, this is how I
understand that things should work, which we should enforce in beta-1:
1) external links are links that start with http:/ , https:/ , ftp:/ ,
file:/ , mailto: , ../ , or ./ (Windows-style ..\ and .\ are NOT
allowed contrary to the original apt docs).
This means in particular that links to other source documents have to
start with ./ or ../, ie something like {{getting-started/index.html}} is
NOT valid, you nee to pre-pend ./ (just to be clear: this is APT specific,
the above link would be valid in an xdoc).
2) internal links are links to anchors within the same source document, eg
"Link to {{anchor}}". Anchors have to be valid id's as defined in the Sink
javadocs for anchor() [1].
This means in particular that links to anchors must not start with "#", eg
all the links in the beginning of [2] are NOT valid.
Does that sound reasonable? The alternative would be to handle links a la
HTML, ie to mark internal links with "#" as suggested at DOXIA-208, this
would render the examples at [2] valid.
Any comments/objections?
-Lukas
[1]
https://svn.apache.org/repos/asf/maven/doxia/doxia/trunk/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
[2] https://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/pom.apt
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
