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

You are correct--we are looking for an implementation option (and have one to suggest in the white paper) that will allow tools to support aggregated authoring with no additional "aggregated authoring" configuration requirement. When it comes to the process integration of aggregated and standalone authoring, there will have to be some configuration components, but we are focused on providing those in a manner that is hopefully simple to adopt with any authoring tool. 

This is a slightly complex subject, not because the configuration tasks themselves are complicated--as you say, they are trivial. The complexity is related to an audience that is often new to DITA, the enterprise orientation of what the BusDocs subcommittee is trying to deliver, parallel or potential activities of other business document oriented subcommittees, and the number of different approaches that people have already tried or adopted in the field.

We hope to get the white paper posted tomorrow, so the discussion is a little ahead of itself.



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

By "no alteration to the base DITA configuration" I assume you mean "using
commercial tools as provided out of the box with no local configuration",

That is, the issue must primarily be one of authoring environment
configuration since most tools (and certainly the Open Toolkit) are
otherwise trivial to configure for local shells.

I appreciate the practical challenge there.

I had not until just now thought about the use of an all-inclusive topic
type as an alternative to <dita> for the specific purpose of aggregated
authoring but it seems very obvious now. It's too bad we didn't think of
this earlier in the 1.2 cycle--it would have been easy to add such a topic
type to the set of TC-provided shells.


If you had such a topic type, what would you call it?



On 9/28/10 1:57 PM, "Michael Boses" <mboses@QUARK.com> wrote:

> 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,
> Michael
> -----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.).
> Cheers,
> Eliot
> 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
> www.reallysi.com
> www.rsuitecms.com
> ---------------------------------------------------------------------
> 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:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

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

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