Re: [dita] Ruminations on the prohibition of <include> for DITA content

The versioned management of hyperdocuments effectively requires the atomic commit of multiple updates as a single action so that the management system can ensure referential integrity without disallowing any particular change as part of a larger update.

That is, the *CMS* should provide a working area into which new versions of documents can be stored without constraint (and often, without allowing access from other users except by explicit permission) but for which link and address resolution services are available so that authors can determine what links are and are not affected by the changes they are making.

Once the author is happy that all links are appropriately updated they can then commit the set of changes as a single commit action to the main content repository.

In this scenario the CMS can be configured to disallow *the entire commit* if it fails some link integrity test.

You can do this with git, for example.

I feel very strongly that any DITA include mechanism should only be allowed within <foreign> for the reasons Chris gives.

XInclude is *functionally identical* to using external parsed entities. DITA explicitly avoids the use of external parsed entities for good reason (they are evil) and XInclude is just as evil as external parsed entities. They are both evil because they provide the *illusion* of allowing reuse while not actually doing all the things a complete reuse solution requires.

That is, there is no provision for reuse when using external parsed entities or XInclude: in both cases two references to the same entity in the same document will result in two *unmodified* copies of the entity content. This breaks reuse in the face of IDs, links to or from the reused element and, in the case of parsed external entities, requires that the referenced content be grammar valid in the using context (because entities are resolved during parse time and thus before grammar validation is performed).

Said more generally: reuse is an application-level concern, not a parse or post-parse preprocessing concern. You cannot do reuse completely except in the context of application-specific processing and full knowledge of all the rules and constraints on the reuse being done, as well as knowledge of how you want the reuse to actually be reflected in any produced result.

All of the complex reuse support features in DITA are there specifically because you cannot do complete and reliable reuse with anything less sophisticated.

Cheers,

Eliot Kimber

http://contrext.com

From: <dita@lists.oasis-open.org> on behalf of Chris Nitchie <chris.nitchie@oberontech.com>
Date: Thursday, April 12, 2018 at 11:32 AM
To: "dita@lists.oasis-open.org" <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

dita message