Add an optional id tag to sub/sections, so they can be referenced

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@280036 13f79535-47bb-0310-9956-ffa450edef68

xdoc/xdocs/changes.xml

@@ -27,6 +27,7 @@
   </properties>
   <body>
     <release version="1.10" date="in SVN">
+      <action dev="ltheussl" type="add" issue="MPXDOC-158">Add an optional id tag to sub/sections, so they can be referenced.</action>
       <action dev="ltheussl" type="add" issue="MPXDOC-144">Add a property to override <code>navigation.xml</code>.</action>
       <action dev="ltheussl" type="add" issue="MPXDOC-127" due-to="Shinobu Kawai Yoshida">Show organization in header even if logo not set.</action>
       <action dev="ltheussl" type="fix" issue="MPXDOC-47">Ampersands in navigation.xml being escaped twice.</action>

xdoc/xdocs/index.xml

@@ -74,6 +74,47 @@
       <subsection name="External Link Icon">
         <p>XDoc automatically adds the "External Link" icon and tooltip to links referring to external sites (actually, any absolute url).</p>
       </subsection>
+      <subsection name="Referencing sections and subsections">
+        <p>
+          From version <code>1.10</code> on, the <code>xdoc</code> plugin
+          allows for an optional <code>id</code> tag in the <code>section</code>
+          and <code>subsection</code> elements:
+        </p>
+        <source><![CDATA[<section name="Section" id="Section1">
+    <subsection name="SubSection" id="SubSection1">
+    </subsection>
+</section>]]></source>
+        <p>
+          An anchor is constructed from each <code>id</code> tag,
+          so you can reference sections and subsections from other source
+          documents. Note that each <code>id</code> tag has to be unique
+          within one source document.
+        </p>
+        <p>
+          In previous versions of the plugin, an <code>id</code> tag
+          was constructed from section/subsection names, replacing special
+          characters by underscores. For backwards compatibility reasons,
+          we keep this behaviour, <emph>i.e.</emph>, if no <code>id</code> tag
+          is present, an anchor is constructed from the <code>name</code> tag.
+          Note that this presents two shortcomings:
+        </p>
+        <ul>
+          <li>
+            If two sections or subsections have identical names
+            (within one source document), you will get an ambiguity when
+            referencing them. Also the resulting html document will not be
+            valid XHTML.
+          </li>
+          <li>
+            For long section titles, this leads to rather
+            cumbersome anchor names.
+          </li>
+        </ul>
+        <p>
+          We recommend that you provide an <code>id</code> tag if you
+          want to reference a section or subsection.
+        </p>
+      </subsection>
     </section>
   </body>
 </document>