APT - local named anchors in apt text are not created properly.

Related to http://jira.codehaus.org/browse/DOXIA-29

This patch was the simplest I could come up with to fix the named anchor problem. The bug has to do with placing a # sign in the named anchor, rather than using it in the link, so there were problems with both parts of the anchor/link pair.

The main issue with the fix is tracking the difference between a normal link and a link to a named anchor.

<a href="commons.html">commons.html</a> <!-- from commons.html -->

vs

<a href="commons">commons</a> <!-- from commons -->

for instance, where the named anchor would be:

<a name="#commons">commons</a> <!-- from

-->

So some alternatives would be:
a. to store a list of named anchors to search against when creating a link
b. to check the link text to see if you could decide based on network protocols (ie http://) or extensions (ie .htm) whether this should be a URL to a named anchor or not.
c. to change the APT format slightly to give a hint as to what to do

I opted for c, since it involved the least code change, and should work in all instances. That's what this patch does. I think it makes adequate sense to differentiate the syntax which refers to a named anchor from other types of links. Now, the syntax would be as follows, in APT:

An . Link to #anchor. Link to http://www.pixware.fr.
Link to {{

anchor showing alternate text}}.
Link to {{

Pixware home page}}.

The only difference is the # sign, which is stripped for display if we're in the middle of a link.

Got bit by the formatting. I'll try again:

 
An {anchor}. Link to {{#anchor}}. Link to {{http://www.pixware.fr}}.
Link to {{{#anchor} anchor showing alternate text}}.
Link to {{{http://www.pixware.fr}Pixware home page}}.

Not sure where this should go, but I wanted to comment on actually getting m2.0.2 to use my fixes, which I haven't been able to do.

I can do mvn install -DupdateReleaseInfo=true

in my doxia directory, and everything is installed to
~/.m2/repository/org/apache/maven/doxia

However, mvn doesn't use the fixes. We also have

~/.m2/repository/ doxia/doxia-core
~/.m2/repository/ doxia/doxia-sink-api
~/.m2/repository/org/codehaus/doxia/doxia-sink-api

/usr/local/maven/lib/doxia-sink-api-1.0-alpha-8-SNAPSHOT.jar

Issuing mvn site will download all of these jars if they are not there, every time. Not only that, but it will download multiple versions of each!

So it would appear there is some pom clean up necessary, and in the short term, even replacing all of them with my "fixed" version, only got "half" of the changes in. I have no idea how this is possible, since all of my changes are in doxia-core. What I mean by "half" is that the links work, but the ampersand is not stripped from the display. I will assume it's some problem with versioning, but if anyone has some suggestions...

Also, it would be good to have a test for this. I found that adding doxia-site-renderer/src/test/site/apt/syntax.apt was good for analysis. Syntax.apt is just copy/paste of the relevant portion from src/site/apt/format.apt. Of course this is not a test at all, but I couldn't see any other tests around for apt either, to which I could add the link/anchor test.

Maybe this should be another bug report?

I'm not happy that the solution "modifies the APT format". Need to more closely assess the problem and why the solution was chosen, which I don't have time for now....

Indeed. Shouldn't Maven's implementation match this implementations output as far as possible: http://www.xmlmind.com/aptconvert.html ?

In that case I think b) would have been the right answer. Links should be assumed to be to local anchors (and should error out if the named anchor does not exist) unless they start with something that indicates they are an external anchor: Text beginning with http:/, https:/, ftp:/, file:/, , ../, ./ (..\ and .\ on Windows) according to the documentation.

Fixed in SVN. There are two questions open however:

• HtmlTools.encodeId makes all anchor names lower case, I think this is a bug so I will open a separate issue
• we need to document that links to other source documents have to start with ./ or ../