Bommels05/maven-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@280036 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
ltheussl 2005-09-10 19:44:04 +00:00
parent a30cfc340e
commit 39eff73d60
3 changed files with 69 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
xdoc/src/plugin-resources/site.jsl
View File

@ -453,6 +453,7 @@
<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">
@ -473,11 +474,18 @@
</j:if>
</j:if>
<!-- 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 test="${!empty(_sectionName)}">
<a name="${_anchorName}"/><h2>${_sectionName}</h2>
</j:if>
<j:if test="${!empty(_anchorName)}">
<a name="${_anchorName}"/>
</j:if>
<h2>${_sectionName}</h2>
<jsl:applyTemplates />
</div>
</jsl:template>
@ -485,6 +493,7 @@
<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">
@ -505,11 +514,18 @@
</j:if>
</j:if>
<!-- 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 test="${!empty(_sectionName)}">
<a name="${_anchorName}"/><h3>${_sectionName}</h3>
</j:if>
<j:if test="${!empty(_anchorName)}">
<a name="${_anchorName}"/>
</j:if>
<h3>${_sectionName}</h3>
<jsl:applyTemplates />
</div>
</jsl:template>

1
xdoc/xdocs/changes.xml
View File

@ -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>

41
xdoc/xdocs/index.xml
View File

@ -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>