maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lukas Theussl <ltheu...@apache.org>
Subject Re: Review Link Handling in APT
Date Sat, 12 Apr 2008 11:33:56 GMT
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
> 

Mime
View raw message