Author: ltheussl
Date: Sat Sep 10 12:44:04 2005
New Revision: 280036
URL: http://svn.apache.org/viewcvs?rev=280036&view=rev
Log:
Add an optional id tag to sub/sections, so they can be referenced
Modified:
maven/maven-1/plugins/trunk/xdoc/src/plugin-resources/site.jsl
maven/maven-1/plugins/trunk/xdoc/xdocs/changes.xml
maven/maven-1/plugins/trunk/xdoc/xdocs/index.xml
Modified: maven/maven-1/plugins/trunk/xdoc/src/plugin-resources/site.jsl
URL:
http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/xdoc/src/plugin-resources/site.jsl?rev=280036&r1=280035&r2=280036&view=diff
==============================================================================
--- maven/maven-1/plugins/trunk/xdoc/src/plugin-resources/site.jsl (original)
+++ maven/maven-1/plugins/trunk/xdoc/src/plugin-resources/site.jsl Sat Sep 10
12:44:04 2005
@@ -453,7 +453,8 @@
<jsl:template match="section" trim="true">
<div class="section">
<x:set var="_sectionName" select="string(@name)"/>
-
+ <j:set var="_sectionId"><x:expr select="@id"/></j:set>
+
<!-- Key is more important than message... -->
<j:set var="_key">
<x:expr select="@key" />
@@ -473,11 +474,18 @@
</j:if>
</j:if>
- <!-- named anchors can't contain whitespaces -->
- <j:set var="_anchorName"><doc:escapeNameToken
value="${_sectionName}"/></j:set>
- <j:if test="${!empty(_sectionName)}">
- <a name="${_anchorName}"/><h2>${_sectionName}</h2>
+ <!-- construct anchor from 'id' tag if it exists, from 'name' tag
otherwise -->
+ <j:if test="${!empty(_sectionId)}">
+ <j:set var="_anchorName"><x:expr select="@id"/></j:set>
+ </j:if>
+ <j:if test="${empty(_sectionId)}">
+ <!-- named anchors can't contain whitespaces -->
+ <j:set var="_anchorName"><doc:escapeNameToken
value="${_sectionName}"/></j:set>
+ </j:if>
+ <j:if test="${!empty(_anchorName)}">
+ <a name="${_anchorName}"/>
</j:if>
+ <h2>${_sectionName}</h2>
<jsl:applyTemplates />
</div>
</jsl:template>
@@ -485,7 +493,8 @@
<jsl:template match="subsection" trim="true">
<div class="subsection">
<x:set var="_sectionName" select="string(@name)"/>
-
+ <j:set var="_sectionId"><x:expr select="@id"/></j:set>
+
<!-- Key is more important than message... -->
<j:set var="_key">
<x:expr select="@key" />
@@ -504,12 +513,19 @@
</fmt:bundle>
</j:if>
</j:if>
-
- <!-- named anchors can't contain whitespaces -->
- <j:set var="_anchorName"><doc:escapeNameToken
value="${_sectionName}"/></j:set>
- <j:if test="${!empty(_sectionName)}">
- <a name="${_anchorName}"/><h3>${_sectionName}</h3>
+
+ <!-- construct anchor from 'id' tag if it exists, from 'name' tag
otherwise -->
+ <j:if test="${!empty(_sectionId)}">
+ <j:set var="_anchorName"><x:expr select="@id"/></j:set>
+ </j:if>
+ <j:if test="${empty(_sectionId)}">
+ <!-- named anchors can't contain whitespaces -->
+ <j:set var="_anchorName"><doc:escapeNameToken
value="${_sectionName}"/></j:set>
+ </j:if>
+ <j:if test="${!empty(_anchorName)}">
+ <a name="${_anchorName}"/>
</j:if>
+ <h3>${_sectionName}</h3>
<jsl:applyTemplates />
</div>
</jsl:template>
Modified: maven/maven-1/plugins/trunk/xdoc/xdocs/changes.xml
URL:
http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/xdoc/xdocs/changes.xml?rev=280036&r1=280035&r2=280036&view=diff
==============================================================================
--- maven/maven-1/plugins/trunk/xdoc/xdocs/changes.xml (original)
+++ maven/maven-1/plugins/trunk/xdoc/xdocs/changes.xml Sat Sep 10 12:44:04 2005
@@ -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>
Modified: maven/maven-1/plugins/trunk/xdoc/xdocs/index.xml
URL:
http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/xdoc/xdocs/index.xml?rev=280036&r1=280035&r2=280036&view=diff
==============================================================================
--- maven/maven-1/plugins/trunk/xdoc/xdocs/index.xml (original)
+++ maven/maven-1/plugins/trunk/xdoc/xdocs/index.xml Sat Sep 10 12:44:04 2005
@@ -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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
