Maven Doxia
  1. Maven Doxia
  2. DOXIA-47

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

    Details

    • Type: Bug Bug
    • Status: Closed Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 1.0-alpha-6
    • Fix Version/s: 1.0-alpha-9
    • Component/s: Module - Xhtml
    • Labels:
      None
    • Environment:
      osx 10.4.4, java 1.4.2_09
    • Number of attachments :
      1

      Description

      Named anchors don't work in APT text. It seems that the anchor part is OK, but the link is not.

        Issue Links

          Activity

          Hide
          Julian Wood added a comment -
          Show
          Julian Wood added a comment - Related to http://jira.codehaus.org/browse/DOXIA-29
          Hide
          Julian Wood added a comment -

          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

          {commons}

          -->

          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}

          anchor showing alternate text}}.
          Link to {{

          {http://www.pixware.fr}

          Pixware home page}}.

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

          Show
          Julian Wood added a comment - 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 {commons} --> 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} anchor showing alternate text}}. Link to {{ {http://www.pixware.fr} Pixware home page}}. The only difference is the # sign, which is stripped for display if we're in the middle of a link.
          Hide
          Julian Wood added a comment -

          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}}.
          
          Show
          Julian Wood added a comment - 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}}.
          Hide
          Julian Wood added a comment -

          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...

          Show
          Julian Wood added a comment - 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...
          Hide
          Julian Wood added a comment -

          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?

          Show
          Julian Wood added a comment - 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?
          Hide
          Brett Porter added a comment -

          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....

          Show
          Brett Porter added a comment - 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....
          Hide
          Stephen Duncan Jr added a comment -

          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.

          Show
          Stephen Duncan Jr added a comment - 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.
          Hide
          Lukas Theussl added a comment -

          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 ../
          Show
          Lukas Theussl added a comment - 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 ../

            People

            • Assignee:
              Lukas Theussl
              Reporter:
              Julian Wood
            • Votes:
              1 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: