RE: [dita-busdocs] Disaggregating stylesheet for ditabase <dita>documents

[Michael Boses <mboses@QUARK.com>]

Hi Tim,

This is great! With the focus on getting the white paper finished I had not looked at the transform itself yet.

A potential next step for us would be to think through the logic required to update the map after a subsequent aggregated authoring session deleted, added, or moved topics or topic headings.
   
A couple of comments (surrounded by ***) are provided below.

Thank you!

Michael

-----Original Message-----
From: Tim Grantham [mailto:tgrantham@timgrantham.com] 
Sent: Tuesday, September 28, 2010 2:17 PM
To: dita-busdocs@lists.oasis-open.org
Subject: [dita-busdocs] Disaggregating stylesheet for ditabase <dita> documents

Yesterday, inspired my Michael's presentation, I wrote an XSL stylesheet that takes a valid <dita> document as its source and generates a DITA map of the topics contained within the <dita> document and one file for each topic.
The map and topic files are stored by default in the same directory as the stylesheet. After running the stylesheet, you can use the resulting map as you normally would: to author, to publish, etc.

The stylesheet uses XSL 2.0 elements and functions, so to run it, you need to use an XSL 2.0 processor, such as the freely-distributable Saxon HE.

Some notes about the stylesheet:
*	The schema for the <dita> element does not provide a @title
attribute or a <title> element. Nor does it support an @id attribute. Yet these are very commonly used for DITA <map> elements (though they are not required). Perhaps we should discuss adding some attributes or elements to <dita> in 1.3, precisely to support these transformations between <dita> and <map>.

    *** The white paper addresses this issue in discussing pros and cons of dita vs. topic as the root of the aggregated document. Using topic as the root would allow for a title. On the other hand, with dita as the root, it can be assumed (as you say below) that the first topic contains the title of the document. It is the same hierarchy that would exist if topic were at the root, simply wrapped in the dita tag.***

In the interim, I've used the same strategy the DITA OT follows for the map
title: I set the value of @title to the contents of the first topic/title element.

For the map @id, I'm currently simply generating a random value for it with generate-id().

*	For the generated file names, I'm concatenating the value of the @id
attribute on the topic with ".xml". The map file name is the generated @id value, concatenated with ".ditamap".

*	This version of the stylesheet currently does not support:
o	Values for any <topicref> attribute other than @href. Future
versions could generate some of the attribute values based on identical values on the individual topic elements.
o	Specializations of <map> or the DITA 1.1 topic types. It currently
only supports <map>, <topic>, <reference>, <task>, <concept>, <glossentry>, and <glossgroup>.
o	Mapping title-only topics to <topichead>. (Easy enough to add, but
I'm wondering about the value of doing this.)

     ***I think mapping them to topichead allows the intent of the author to be reflected in the map, and allows the map to more clearly represent the aggregated structure of the document. A good subject for further discussion.***

o	Over-writing map and topic files of the same name. (This might be
just a feature of the Saxon HE processor.) This means that, for now at least, before you re-run the stylesheet on a <dita> document, you have to delete any previously-generated files.
o	Any map element other than <topicref>.

I've tested this with a couple of <dita> documents, including one that had
74 deeply-nested topics, and it worked well. But I would like to see it tested with some other <dita> documents, including ones that contain <glossentry> and <glossgroup> topics.

Let me know if you have any questions or comments.

Regards,
Tim.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
    xmlns:xs="http://www.w3.org/2001/XMLSchema";
xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl";
    exclude-result-prefixes="xs xd" version="2.0">
    <xd:doc scope="stylesheet">
        <xd:desc>
            <xd:p><xd:b>Created on:</xd:b> Sep 27, 2010</xd:p>
            <xd:p><xd:b>Author:</xd:b> Tim Grantham</xd:p>
            <xd:p/>
        </xd:desc>
    </xd:doc>

    <xsl:output method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Map//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd"/>
    
    <xsl:output name="reference" method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Reference//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/reference.dtd"/>

    <xsl:output name="concept" method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Concept//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/concept.dtd"/>

    <xsl:output name="task" method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Task//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/task.dtd"/>

    <xsl:output name="topic" method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Topic//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/topic.dtd"/>

    <xsl:output name="glossentry" method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Glossary//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/glossary.dtd"/>

    <xsl:output name="glossgroup" method="xml" indent="yes" encoding="UTF-8"
        doctype-public="-//OASIS//DTD DITA Glossary Group//EN"
 
doctype-system="http://docs.oasis-open.org/dita/v1.1/OS/dtd/glossgroup.dtd"/
>

    <xsl:template match="dita">
        <xsl:result-document href="{concat(*[contains(@class, 'topic/topic')][1]/@id,'.ditamap')}">
        <map id="{generate-id(.)}" title="{*[contains(@class, 'topic/topic')][1]/title}">
            <xsl:apply-templates mode="topicref"/>
        </map>
        </xsl:result-document>
        <xsl:apply-templates mode="topic"/>
    </xsl:template>

    <xsl:template match="*[contains(@class, 'topic/topic')]" mode="topic">
        <xsl:result-document href="{concat(@id,'.xml')}" format="{name()}">
            <xsl:copy>
                <xsl:copy-of select="@*"/>
                <xsl:for-each
select="*[not(contains(@class,'topic/topic'))]">
                    <xsl:copy-of select="."/>
                </xsl:for-each>
            </xsl:copy>
        </xsl:result-document>
        <xsl:apply-templates mode="topic"/>
    </xsl:template>

    <xsl:template match="*[contains(@class, 'topic/topic')]"
mode="topicref">
        <topicref href="{concat(@id,'.xml')}">
            <xsl:apply-templates mode="topicref" select="*[contains(@class, 'topic/topic')]"/>
        </topicref>
    </xsl:template>
    
</xsl:stylesheet>