Revision of 12013 design from Tue, 2008-06-17 20:00
Part of Plans for DITA Open Toolkit 1.5
Design for item
What user need will be met by this feature?
Users can use @conref combined with @conrefend to refer to a range of sibling elements and pull them into the specified location.
What is the technical design for the change
In conrefImpl.xsl, when the target of @conref is processed, the code first copy or proceed all @* attributes of target elements and then use apply-templates on its sub-nodes. After that we need to add the code to check whether @conrefend is valid and proceed the elements in the conref range. Since the template to proceed conref target doesn't know whether there is @conrefend at conref source, the value of @conrefend should be passed as parameter.
Another piece of code we need to change is "<xsl:copy>". In current code, <xsl:copy> is used in <xsl:template match="*[@conref][@conref!='']" priority="10">. The code proceed the conref source element and keep necessary @* attributes before go to conref target. But if we want to proceed range conref, the generated sibling elements will be sibling to the conref source element and logic of <xsl:copy> should be moved to the code which proceed conref target. Thus <xsl:copy> in <xsl:template match="*[@conref][@conref!='']" priority="10"> need to be removed and the info of conref source element needs to be transmitted as a parameter to the template which proceeds conref target elements.
Here is the current template to proceed conref-target in conrefImpl.xsl with update comments in bold
<xsl:template match="*" mode="conref-target">
************************************************
We need to add a parameter here to accept the value of @conrefend. The default value is #none# which means that there is no @conrefend
************************************************
************************************************
We need to add a parameter to accept the info of conref source element and generate the element in this template.
************************************************
<xsl:param name="WORKDIR"/>
<xsl:param name="conref-source-topicid"/>
<xsl:param name="conref-ids"/>
<xsl:param name="source-element"/>
<xsl:param name="current-relative-path"/> <!-- File system path from original file to here -->
<xsl:param name="conref-filename"/>
.......calculate topic id and element id..........
<!-- If for some bizarre reason you conref to another element that uses @conref, forget the original and continue here. -->
<xsl:choose>
<xsl:when test="@conref">
.......proceed @conref of the conref target.........
</xsl:when>
<xsl:otherwise>
***********************************************
Generate the conref source element and its attributes
***********************************************
<xsl:for-each select="@*">
.......proceed every @* attribute.........
</xsl:for-each>
<!-- Continue processing this element as any other -->
<xsl:apply-templates select="*|comment()|processing-instruction()|text()">
......apply templates on sub-nodes.......
</xsl:apply-templates>
***********************************************
End of generating the conref source element
***********************************************
</xsl:otherwise>
</xsl:choose>
***************************************************************
Here we need to add the logic to proceed @conrefend if the value of @conrefend is sent to this template as variable.
***************************************************************
</xsl:template>
How to address the elements in the conref range?
If @conrefend is valid, there must be a following sibling to the conref target which has the same id as @conrefend specified. If @conrefend is not valid, we would ignore @conrefend and report a warning message saying that @conrefend is not valid. If valid, we should use following XPath expression to address all of the elements between conref start and conref end.
following-sibling::*[following-sibling::*[@id=$conrefend-elem-id]]
This XPath expression is used to address all of the following siblings to current conref target with condition that @conrefend element is also their following sibling.
We created a sample demo to prove that this XPath can be accepted by XSLT processor. Here is the demo.
***********1.xml************
<?xml version="1.0" encoding="UTF-8"?>
<stub>
<li id="a"></li>
<li id="b"></li>
<li id="c"></li>
<li id="d"></li>
<li id="e"></li>
<li id="f"></li>
<li id="g"></li>
<li id="h"></li>
<li id="i"></li>
<li id="k"></li>
</stub>
********2.xsl***********
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:template match="/">
<xsl:for-each select="/stub/*[preceding-sibling::*[@id='a']][following-sibling::*[@id='g']]">
<xsl:copy>
<xsl:copy-of select="@*|*|text()|comment()|processing-instruction()"/>
</xsl:copy>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>
In this demo, 2.xsl get all elements between a and g and copy them to the output.
What sections of the toolkit will be impacted by the change?
The change will impact conref resolution xslt script.
See also
none