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 [EMAIL PROTECTED] 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
