Maven 1.x XDoc Plugin

Do not generate name tags from section names

Details

  • Type: Improvement Improvement
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: 1.9.1
  • Fix Version/s: 1.10
  • Labels:
    None
  • Environment:
    ?
  • Number of attachments :
    2

Description

In the current version of the xdoc plugin, a <a name="sectionName"> element is generated for every sub/section from its corresponding
name tag. This may lead to an invalid HTML document if some sub/sections have the same name, because according to the HTML 4.01 specs ( http://www.w3.org/TR/html4/struct/links.html#h-12.2.1 ), anchor names must be unique within one document. For the xdoc plugin this is not a big problem
because browsers usually ignore identical ids, but we are having troubles for the pdf plugin (see MPPDF-40) where identical ids lead to a
build failure.

I suggest to generate an id from an optional id tag as in the following example:

<section name="Section 1">
<subsection name="SubSection" id="SubSection1">
</subsection>
</section>
<section name="Section2">
<subsection name="SubSection" id="SubSection2">
</subsection>
</section>

so the section title is constructed from the name tag while the id tag (which has to be unique) may be used to reference the section.
I attach a patch to achieve this, if this gets accepted I can easily adjust the pdf plugin accordingly.

The only worry is backwards compatibility: xdocs that use the old feature of referencing sections by names, will produce invalid links.
However, I haven't seen this feature documented anywhere, I don't think it is widely used and therefore, it should not be a big problem.

  1. Text File
    MPXDOC-158.patch
    22/Aug/05 12:24 AM
    3 kB
    Lukas Theussl
  2. Text File
    site.jsl.patch
    15/Aug/05 12:14 PM
    2 kB
    Lukas Theussl

Issue Links

is related to

New Feature - A new feature of the product, which has yet to be developed. MPXDOC-159 Allow users to provide 'href' attribute to be used a section or subsection anchor

  • 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
Trygve Laugstøl added a comment -

As this will totally break backwards compablity I would say that the xdoc plugin should just warn and ignore any repeated headings.

Show
Trygve Laugstøl added a comment - As this will totally break backwards compablity I would say that the xdoc plugin should just warn and ignore any repeated headings.
Hide
Permalink
Lukas Theussl added a comment -

'Totally break' is a bit exaggerated in my opinion. There is nothing broken in any build process. And if you have a href="index.html#section1" reference,
then any browser I know will still bring you to index.html, even if section1 does not exist.

On the upside, we would have strictly valid HTML documents and an unambiguous prescription for referencing sections.
I also forgot to point out that the name attribute is formally deprecated in XHTML 1.0 (http://www.w3.org/TR/xhtml1/#h-4.10),
it will be removed in a future specification.

Show
Lukas Theussl added a comment - 'Totally break' is a bit exaggerated in my opinion. There is nothing broken in any build process. And if you have a href="index.html#section1" reference, then any browser I know will still bring you to index.html, even if section1 does not exist. On the upside, we would have strictly valid HTML documents and an unambiguous prescription for referencing sections. I also forgot to point out that the name attribute is formally deprecated in XHTML 1.0 ( http://www.w3.org/TR/xhtml1/#h-4.10 ), it will be removed in a future specification.
Hide
Permalink
Trygve Laugstøl added a comment -

If you upgrade your plugin and suddenly links doesn't work that's something that I would call broken. Now if you instead just give a warning about the second link beeing dropped (as it wouldn't ever have worked in the first place) that shouldn't change anything. I would also think that most browsers would jump to the first tag.

Also, requiring all sections to supply an id if they want to be referencable is not something I like, it should be an optional way to override the generated name.

The generated documentation should be valid XHTML, so if the spec has deprecated the element we should use whatever they has as a replacement.

Show
Trygve Laugstøl added a comment - If you upgrade your plugin and suddenly links doesn't work that's something that I would call broken. Now if you instead just give a warning about the second link beeing dropped (as it wouldn't ever have worked in the first place) that shouldn't change anything. I would also think that most browsers would jump to the first tag. Also, requiring all sections to supply an id if they want to be referencable is not something I like, it should be an optional way to override the generated name. The generated documentation should be valid XHTML, so if the spec has deprecated the element we should use whatever they has as a replacement.
Hide
Permalink
Arnaud Heritier added a comment -

we are inside the same problem : how generate (sub)sections ids and how to use them ?

Show
Arnaud Heritier added a comment - we are inside the same problem : how generate (sub)sections ids and how to use them ?
Hide
Permalink
Lukas Theussl added a comment -

A slight change to maintain backwards compatibility: the id tag will only be used if it is present, if omitted, we fall back to the name tag as before. This patch also makes the link handling of the pdf and xdoc plugins identical.

Show
Lukas Theussl added a comment - A slight change to maintain backwards compatibility: the id tag will only be used if it is present, if omitted, we fall back to the name tag as before. This patch also makes the link handling of the pdf and xdoc plugins identical.

People

  • Assignee:
    Lukas Theussl
    Reporter:
    Lukas Theussl
Vote (0)
Watch (0)

Dates

  • Created:
    Updated:
    Resolved:

Time Tracking

Estimated:
5m
Original Estimate - 5 minutes
Remaining:
5m
Remaining Estimate - 5 minutes
Logged:
Not Specified
Time Spent - Not Specified