See my comment at http://jira.codehaus.org/browse/DOXIA-208
In short: yes it would be easier and it would have spared us a lot of
pain in the past if apt would handle links like everyone else. But
changing that now we would IMO risk more by confusing users and breaking
things than we gain by a more intuitive behavior.
However, given our history of breaking things (especially wrt
anchors/links) I am not categorically opposed to changing stuff. :) Just
if we decide to go for it then we should either do it now for beta-1, or
postpone it until after 1.0-final.
-Lukas
Benjamin Bentmann wrote:
Hi,
According to the APT Reference [0] and the output delivered by the Maven
Site Plugin 2.0-beta-6, the construct
{{{foo}baa}}
denotes an internal link to the anchor "foo" in the current document. I
believe this kind of linking is inconsistent/unintuitive and hence
error-prone.
For example, {{{dir/doc.pdf}baa}} will render an external link as
expected. Now let's move doc.pdf up one directory. The appealing snippet
{{{doc.pdf}baa}} will not give you the desired external link but out of
a sudden an internal link. To get the desired link, users need to write
{{{./doc.pdf}baa}}.
Wouldn't it be easier, both for users and the parser, if APT would
handle links just like the well-known HTML format? I.e. a link is
internal if and only if it starts with '#'.
What do you think?
Benjamin
[0] http://maven.apache.org/doxia/references/apt-format.html