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

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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


Subject: RE: Ruminations on the prohibition of <include> for DITA content


I am grateful that you’ve opened the door on this slightly to consider the application of referencing DITA content with <include> separately from using a conref. Here at Precision Content we are looking at creating a new reuse mechanism for content based on an <xref> specialization that allows our users to transclude and transmogrify a DITA topic into a type of section with title at the point where it is referenced. If we were able to build it with <include> in mind that would be great.

 

Why do we want to transclude and transmogrify content?

The short description and title for each information type has a specific purpose and style of writing. For example, every concept uses the short description to define the term of the concept. There are many cases that we may want to reference this definition but we aren’t able to do so without performing some tagging gymnastics. Cases where we want to reference another task as a step within a task, we use an <xref> within the <cmd> element. It works – at least mostly.

 

We want a reuse mechanism that pulls in this important content into places where it makes sense to do so.

 

How our transmogrification works

First we create a specialized element from <xref> that allows us to limit the context for where the reused content can be inserted. The specialized element points to the target topic and the topic title and abstract/shortdesc are inserted as specified in the stylesheets, for example as a section with title or a command and step info block in a step.

 

Food for thought, anyway.

 

Cheers,

Rob Hanna

 

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Chris Nitchie
Sent: Thursday, April 12, 2018 12:33 PM
To: dita@lists.oasis-open.org
Subject: [dita] Ruminations on the prohibition of <include> for DITA content

 

As presented in my Stage 2 proposal for <include>, it’s an error to reference XML content outside the context of <foreign>. The goal is to force users who wish to leverage reuse of DITA XML content to use @conref or @conkeyref instead.

 

I was talking to some of my colleagues about this, and they expressed serious concern about this provision. Many of our clients use CMS systems that do not enforce element-level referential integrity on conrefs and conkeyrefs. That is, if I have a @conref from Topic A to an element in Topic B, the CMS will probably prevent me from deleting Topic B, but it will not prevent me from deleting the target _element_ from Topic B. This limitation has led more than one of our clients to disregard @conref entirely, opting instead for XInclude, so that the CMS enforces referential integrity. Unfortunately, the use of XInclude circumvents DITA conref validation and thus it becomes possible to construct a document that is invalid after inclusions are resolved, but by and large the authoring tools discourage this, and it’s a tradeoff these clients gladly make. Of course, XIncludes are also not capabile of reference by key.

 

All of which has me reconsidering, a little, the prohibition on using <include> for DITA content. I’m a firm believer that the TC generally shouldn’t account too much for tooling limitations. At the same time, the near-universality of this limitation, at least in the CMS systems we commonly work with, is troubling. I’m curious about thoughts from others on the TC.

 

Chris

 



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