You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doxia-dev@maven.apache.org by Lukas Theussl <lt...@apache.org> on 2008/05/13 14:40:28 UTC
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
Re: link/anchors in apt
Posted by Vincent Siveton <vi...@gmail.com>.
+1
Vincent
2008/5/13, Lukas Theussl <lt...@apache.org>:
> 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
>