OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-busdocs message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

Hi Eliot,

I appreciate your offer to help with the topic definition. We will be posting a white paper that discusses the entire subject of aggregated authoring, with a focus on subsequent reconciliation of aggregated authoring sessions with standalone authoring of the individual topics and map(s). 

Based to a large degree on your writings regarding the use of topic as the root of aggregated documents, and your suggestions about making local copies of the shell dtds, we address the pros and cons of dita vs. topic in the white paper and felt that topic might be the better approach for quite a while. The primary driver for using dita at the end of the discussion comes out of our desire to provide aggregated authoring with no alteration to the base dita configuration. Granted that people may probably wind up specializing or modifying the shell dtds for other reasons, but we did not want to add another layer of modification simply to achieve aggregated authoring. For the same reason, I do not think we will be requesting a change to ditabase in 1.3, as it currently meets the requirements outlined in the white paper.

The major goal of posting the white paper is to get feedback from TC members before we continue thinking about this issue. We appreciate your continued input!

Thank you,


-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Tuesday, September 28, 2010 2:33 PM
To: tgrantham@timgrantham.com; dita-busdocs@lists.oasis-open.org
Subject: Re: [dita-busdocs] Disaggregating stylesheet for ditabase <dita> documents

The <dita> element is at best a convenience for storage of topics that are
conveniently stored as a single XML document but are otherwise unrelated.

It would be inappropriate and unnecessary to try to make <dita> more like a
map (e.g., by adding @id or allowing a title) because the whole point of the
<dita> element is that it's not a map.

If you want to represent a complete publication as a single topic, use a
topic as the root. I haven't done it in DITA for Publishers, but it would be
easy to define a topic type that is intended to act as a publication root
and if it would help the busdocs process to have such a topic type I would
be happy to define and document it.

That is, the only difference between <dita> and <topic> where the topic has
been configured to allow all desired topic types is that topic requires @id
allows <title> and <dita> does not.

If there requirement is that there be a topic type that allows nesting of
all TC-defined topic types, I can implement that in about 2 minutes and
would be happy to do so. The only real question is what the topic type name
should be.

If the issue is one of conversion (that is, converting from non-DITA content
to DITA content typically results in a <dita> document rather than a map),
that's a software problem that I have to a large degree solved with the
Word-to-DITA transformation framework that is part of the DITA for
Publishers project--it is fully capable of generating systems of maps and
topics from a single Word document using a declarative mapping from
paragraph styles to DITA structures.

For example, a single Word paragraph might result in a new map, a new topic,
and a topicref to that topic in the generated map.

The current software is Word specific but it's been engineered so that it
could be adapted to any similar word processing format (e.g., InDesign
articles, WordPerfect, Open Document, etc.).



On 9/28/10 1:17 PM, "Tim Grantham" <tgrantham@timgrantham.com> wrote:

> 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>.
> 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.)
> 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>

Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368

To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]