Maven 1.x XDoc Plugin
  1. Maven 1.x XDoc Plugin
  2. MPXDOC-158

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. MPXDOC-158.patch
        3 kB
        Lukas Theussl
      2. site.jsl.patch
        2 kB
        Lukas Theussl

        Issue Links

          Activity

          Hide
          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
          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
          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
          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
          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
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Time Tracking

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