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 13:36:22 GMT

Benjamin Bentmann wrote:
>> See my comment at http://jira.codehaus.org/browse/DOXIA-208
> 
> 
> Your proposal at
> http://docs.codehaus.org/display/DOXIA/Proposed+Changes+to+the+APT+Format
> already suggests to break compat with the original APT format. I beg you to
> go this route down to its end and make APT a user-friendly format. If it 
> helps, call it N(ew)APT, B(etter)APT, D(oxia)APT or whatever ;-)

We have already implemented a number of enhancements/changes to the 
original apt format: 
http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/references/doxia-apt.apt

> 
>> 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.
> 
> 
> I'm really in favor to get the link handling straight as soon as possible
> and believe beta-1 is a good chance to do it. The more you wait, the more
> users/docs will rely on the currently weird link handling such that the
> penalty of breaking will increase.

As I said in my other mail, I don't quite see the necessity. It's a big 
change with a big risk of breaking things for a little bit of more 
intuitive behavior.

> 
> It's always pity if backward-compat prevents one from fixing 
> questionable decisions in the past. Maybe the best way to come to 
> conclusion for this controversial topic is to call a simple vote on the 
> mailing lists (I guess user@maven will reach the most) and get a feel of 
> the world's thoughts on this.

I don't think adopting the apt format was a questionable decision. The 
mistake that was made is that the AptParser was taken over from 
aptconvert without modification and the XhtmlSink was adapted to its 
behavior (since at the time, people were only interested in apt->html). 
But this is something that can be corrected without user penalty.

I'm not sure about the vote, I could imagine that all people that are on 
the user list now have gotten used to the current format already and so 
wouldn't want to change it.

-Lukas

> 
> 
> Benjamin
> 
> 

Mime
View raw message