Mailing-List: contact doxia-dev-help@maven.apache.org; run by ezmlm
Precedence: bulk
Reply-To: doxia-dev@maven.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
Message-ID: <48298C3C.8060603@apache.org>
Date: Tue, 13 May 2008 14:40:28 +0200
From: Lukas Theussl <ltheussl@apache.org>
Organization: Apache Software Foundation
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US;
 rv:1.7.12) Gecko/20050922 Fedora/1.7.12-1.3.1
MIME-Version: 1.0
To: doxia-dev@maven.apache.org
Subject: link/anchors in apt
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

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