Maven Doxia

standardize link/anchor handling: remove usage of StructureSinkUtils

Details

  • Number of attachments :
    0

Description

To be inline with wikis and other formats the APT link "MyLink" should be a relative link whereas "#MyLink" would link to an anchor.
This is a deviation from the apt format, but would remove confusion for new users and those working on supporting multiple formats.

Edit: this is an issue with the XHTML sink, not the apt parser - anything link "MyLink" will be spat out as "#MyLink"

Issue Links

is related to

Bug - A problem which impairs or prevents the functions of the product. DOXIA-257 APT local anchor / link doesn't work when there is a whitespace in the anchor name

  • Major - Major loss of function.
  • Closed - The issue is considered finished, the resolution is correct. Issues which are not closed can be reopened.
supercedes

Task - A task that needs to be done. DOXIA-56 clean up doxia api and code

  • Major - Major loss of function.
  • Closed - The issue is considered finished, the resolution is correct. Issues which are not closed can be reopened.

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Lukas Theussl added a comment -

viz changing apt: this was already proposed (and rejected) at DOXIA-47. Even though we are now discussing changes to the original apt format (http://docs.codehaus.org/display/DOXIA/Proposed+Changes+to+the+APT+Format) I'm not in favor of this particular change, because it's not motivated by a necessary bug fix or missing feature. IMO we risk more by confusing users and breaking things than we gain by a more intuitive behavior.

viz. xhtml sink: there is an issue to discuss I think, eg I don't see why one should be forced to use href="./other.html" instead of just href="other.html" in an xdoc document (in apt you have to because there is no other way to distinguish internal from external links).

I think we can easily define how parsers should emit link events link( String name ) : if name starts with # it's an internal link and the receiving sink can decide what to do with it. The StructureSink.isExternalLink method is apt specific, it should not be used by other sinks.

Show
Lukas Theussl added a comment - viz changing apt: this was already proposed (and rejected) at DOXIA-47 . Even though we are now discussing changes to the original apt format ( http://docs.codehaus.org/display/DOXIA/Proposed+Changes+to+the+APT+Format ) I'm not in favor of this particular change, because it's not motivated by a necessary bug fix or missing feature. IMO we risk more by confusing users and breaking things than we gain by a more intuitive behavior. viz. xhtml sink: there is an issue to discuss I think, eg I don't see why one should be forced to use href="./other.html" instead of just href="other.html" in an xdoc document (in apt you have to because there is no other way to distinguish internal from external links). I think we can easily define how parsers should emit link events link( String name ) : if name starts with # it's an internal link and the receiving sink can decide what to do with it. The StructureSink.isExternalLink method is apt specific, it should not be used by other sinks.
Hide
Permalink
Lukas Theussl added a comment -

The two methods in StructureSink are apt-specific but they are used in HtmlTools, XhtmlBaseSink, DocbookSink and XdocSink. Eg the isExternalLink() method returns true for links that start with "./" but this is only necessary for apt, see my comment above.

Show
Lukas Theussl added a comment - The two methods in StructureSink are apt-specific but they are used in HtmlTools, XhtmlBaseSink, DocbookSink and XdocSink. Eg the isExternalLink() method returns true for links that start with "./" but this is only necessary for apt, see my comment above.
Hide
Permalink
Benjamin Bentmann added a comment -

I'm not in favor of this particular change, because it's not motivated by a necessary bug fix or missing feature.

Depends on your definition of "feature": I call ease of usage a feature and the current link handling is not really that easy...

Show
Benjamin Bentmann added a comment - I'm not in favor of this particular change, because it's not motivated by a necessary bug fix or missing feature. Depends on your definition of "feature": I call ease of usage a feature and the current link handling is not really that easy...
Hide
Permalink
Lukas Theussl added a comment -

The problem is that both ways are actually supported in practice, see eg the links in [1], which are not strictly legal even in the original apt format. If we want to standardize things, we have to define the 'correct' way and doxia should at least issue a warning for invalid links. See also [2] for reference.

[1] https://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/pom.apt?revision=645089&view=markup
[2] http://www.nabble.com/link-anchors-in-apt-td17207340.html

Show
Lukas Theussl added a comment - The problem is that both ways are actually supported in practice, see eg the links in [1] , which are not strictly legal even in the original apt format. If we want to standardize things, we have to define the 'correct' way and doxia should at least issue a warning for invalid links. See also [2] for reference. [1] https://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/pom.apt?revision=645089&view=markup [2] http://www.nabble.com/link-anchors-in-apt-td17207340.html
Hide
Permalink
Lukas Theussl added a comment -

Done in revs 652905 and 656154.

Show
Lukas Theussl added a comment - Done in revs 652905 and 656154.

People

  • Assignee:
    Lukas Theussl
    Reporter:
    Andrew Williams
Vote (1)
Watch (0)

Dates

  • Created:
    Updated:
    Resolved: