Commons Functor
  1. Commons Functor
  2. FUNCTOR-23

aggregator.xml generates broken JavaDoc links

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Trivial Trivial
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Labels:

      Description

      aggregator.xml has a few JavaDoc links to methods, as such the anchor url contains a hash (#) as well as a method name followed by brackets (). This triggers Doxia/Velocity into "thinking" that this is a macro call, and as such the links resulted (during mvn site) do not contain these brackets.
      To fix them, as per https://jira.codehaus.org/browse/MSITE-646, we need to URL-escape the # hash sign (%23).
      This bug is created to propose a patch to aggregator.xml for this.

      1. FUNCTOR-23.2.patch.bz2
        3 kB
        Liviu Tudor
      2. FUNCTOR-23.patch.bz2
        2 kB
        Liviu Tudor

        Activity

        Liviu Tudor created issue -
        Hide
        Liviu Tudor added a comment -

        Patch to generated correct JavaDoc links in aggregator.xml.

        Show
        Liviu Tudor added a comment - Patch to generated correct JavaDoc links in aggregator.xml .
        Liviu Tudor made changes -
        Field Original Value New Value
        Attachment FUNCTOR-23.patch.bz2 [ 12538071 ]
        Hide
        Simone Tripodi added a comment -

        Patch applied, see r1366301, thanks a lot Liviu for taking care!!

        Show
        Simone Tripodi added a comment - Patch applied, see r1366301, thanks a lot Liviu for taking care!!
        Simone Tripodi made changes -
        Status Open [ 1 ] Resolved [ 5 ]
        Assignee Simone Tripodi [ simone.tripodi ]
        Resolution Fixed [ 1 ]
        Hide
        Liviu Tudor added a comment -

        Actually having looked at the output generated now closely it seems that the browser shows the link (in the status bar) correctly, but the generated link contains still the %23 escaped code, which results in wrong URLs.
        Reopening this to provide a new patch.

        Show
        Liviu Tudor added a comment - Actually having looked at the output generated now closely it seems that the browser shows the link (in the status bar) correctly, but the generated link contains still the %23 escaped code, which results in wrong URLs. Reopening this to provide a new patch.
        Liviu Tudor made changes -
        Resolution Fixed [ 1 ]
        Status Resolved [ 5 ] Reopened [ 4 ]
        Hide
        Liviu Tudor added a comment -

        Looking in the bugs for DOXIA, it turns out that they are planning a fix for this but in the next major release, meanwhile, the only workaround for this is to actually provide full URL's (rather than relative URL's – which is what causes the problem).
        I've changed the URLs to absolute (prefixed with http://commons.apache.org/functor/) only for those cases where the links contained an anchor and about to submit the new patch.

        Show
        Liviu Tudor added a comment - Looking in the bugs for DOXIA, it turns out that they are planning a fix for this but in the next major release, meanwhile, the only workaround for this is to actually provide full URL's (rather than relative URL's – which is what causes the problem). I've changed the URLs to absolute (prefixed with http://commons.apache.org/functor/ ) only for those cases where the links contained an anchor and about to submit the new patch.
        Hide
        Liviu Tudor added a comment -

        Updated patch, with absolute URL's, which fixes the issue for now.

        Show
        Liviu Tudor added a comment - Updated patch, with absolute URL's, which fixes the issue for now.
        Liviu Tudor made changes -
        Attachment FUNCTOR-23.2.patch.bz2 [ 12538204 ]
        Hide
        Liviu Tudor added a comment -

        Also the attached patch adds the link to aggregator.html (generated from aggregator.xml) in the top level menu, to make it easier to access and more visible to the users.

        Show
        Liviu Tudor added a comment - Also the attached patch adds the link to aggregator.html (generated from aggregator.xml ) in the top level menu, to make it easier to access and more visible to the users.
        Hide
        Bruno P. Kinoshita added a comment -

        Hi Liviu,

        The problem with absolute links is that if you are working offline, you won't be able to generate the site and browse the links (as you would be directed to http://commons.apache.org/functor, rather than file://...).

        I took a look at the Doxia issues and seems like it hasn't been solved yet. I tried using Markdown, but the same happens. No lucky trying escape the () too.

        I think we should use the initial approach (i.e.: apidocs/org/apache/.../Class.html#method()) even if the () gets cut due to a bug in Doxia. Other components like Apache Commons Math [1] and Apache Commons VFS [2] use this too.

        [1] http://commons.apache.org/math/userguide/genetics.html
        [2] http://commons.apache.org/vfs/api.html

        Show
        Bruno P. Kinoshita added a comment - Hi Liviu, The problem with absolute links is that if you are working offline, you won't be able to generate the site and browse the links (as you would be directed to http://commons.apache.org/functor , rather than file:// ...). I took a look at the Doxia issues and seems like it hasn't been solved yet. I tried using Markdown, but the same happens. No lucky trying escape the () too. I think we should use the initial approach (i.e.: apidocs/org/apache/.../Class.html#method()) even if the () gets cut due to a bug in Doxia. Other components like Apache Commons Math [1] and Apache Commons VFS [2] use this too. [1] http://commons.apache.org/math/userguide/genetics.html [2] http://commons.apache.org/vfs/api.html
        Hide
        Sebb added a comment -

        I think we should use the initial approach

        Agreed. Although it would be better if the link took one directly to the method, using absolute links is a worse problem.

        Note: there is a fix for some Doxia relativisation errors in the commons-site VM file.
        The VM file just removes 'http://dummy.invalid/' from the start of any link text.
        However it does not currently process the main text body though it should not be too difficult to extend the code to do so. If that were done, then one could prefix any Javadoc method links with 'http://dummy.invalid/' to skip the Doxia mangling.

        Show
        Sebb added a comment - I think we should use the initial approach Agreed. Although it would be better if the link took one directly to the method, using absolute links is a worse problem. Note: there is a fix for some Doxia relativisation errors in the commons-site VM file. The VM file just removes 'http://dummy.invalid/' from the start of any link text. However it does not currently process the main text body though it should not be too difficult to extend the code to do so. If that were done, then one could prefix any Javadoc method links with 'http://dummy.invalid/' to skip the Doxia mangling.
        Hide
        Bruno P. Kinoshita added a comment -

        URL: http://svn.apache.org/viewvc?rev=1424224&view=rev
        Log:
        FUNCTOR-23 reverting changes from PATCH-23 as the %23 was breaking URL's in chrome and not really fixing the javadoc links

        Modified:
        commons/proper/functor/trunk/src/site/xdoc/aggregator.xml

        Show
        Bruno P. Kinoshita added a comment - URL: http://svn.apache.org/viewvc?rev=1424224&view=rev Log: FUNCTOR-23 reverting changes from PATCH-23 as the %23 was breaking URL's in chrome and not really fixing the javadoc links Modified: commons/proper/functor/trunk/src/site/xdoc/aggregator.xml
        Hide
        Bruno P. Kinoshita added a comment -

        Hi Liviu,

        I reverted the changes from FUNCTOR-23.patch. The %23 was breaking the URL's in Chrome 23.0.1271.97/Linux-amd64 and not really fixing the javadoc links.

        The patch FUNCTOR-23.2.patch is not necessary anymore, as this issue happens in other components due to a known bug in Doxia, and using the project website in the links wouldn't allow to generate the site offline.

        But the FUNCTOR-23.2 patch also added a link to aggregators in the top menu. As the top menu has no links to functors, functions, predicates, procedures or other basic concepts in [functor] at the moment, it wouldn't be right to include a link to aggregators in there IMHO.

        I added a link to aggregators in the examples page though (r1424226), as there were links to functions, predicates, procedures and generators already.

        Thanks for the hard work on [functor]! Looking forward to more patches

        Show
        Bruno P. Kinoshita added a comment - Hi Liviu, I reverted the changes from FUNCTOR-23 .patch. The %23 was breaking the URL's in Chrome 23.0.1271.97/Linux-amd64 and not really fixing the javadoc links. The patch FUNCTOR-23 .2.patch is not necessary anymore, as this issue happens in other components due to a known bug in Doxia, and using the project website in the links wouldn't allow to generate the site offline. But the FUNCTOR-23 .2 patch also added a link to aggregators in the top menu. As the top menu has no links to functors, functions, predicates, procedures or other basic concepts in [functor] at the moment, it wouldn't be right to include a link to aggregators in there IMHO. I added a link to aggregators in the examples page though (r1424226), as there were links to functions, predicates, procedures and generators already. Thanks for the hard work on [functor] ! Looking forward to more patches
        Hide
        Bruno P. Kinoshita added a comment -

        Resolving issue as it was reopened due to a bug in Doxia. Changes reverted to adhere with the pattern of other commons components.

        Show
        Bruno P. Kinoshita added a comment - Resolving issue as it was reopened due to a bug in Doxia. Changes reverted to adhere with the pattern of other commons components.
        Bruno P. Kinoshita made changes -
        Status Reopened [ 4 ] Resolved [ 5 ]
        Resolution Fixed [ 1 ]

          People

          • Assignee:
            Simone Tripodi
            Reporter:
            Liviu Tudor
          • Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development