RE: [dita] DITA 2.0 and the <schemeref> element: Removing the concept of

Iâd second that proposal, Kris.

I used to come up with similar designs of distributing global and local configuration data for processing our in-house XML variant. It turned out that this kind of extension mechanisum, although it indeed looks âslick and usefulâ, as you put it, it doesnât pay off: Users are not necessarily aware of what has been specified in the global data, which, here, is the subject scheme map foo.ditamap. In the end, it may lead to inconsistencies further down the road, when the referenced subject scheme map (governed by other users) undergoes changes.

My recommendation to users would be to either reference a given subject scheme as is, or define it completely on their own. In the case of the division specifying the ePub output, they really should define the complete map themselves instead of extending a given one, as in the subject scheme under 3. The message then is, if you reference a subject scheme map, you basically get everything there as defined in and you can only define other subjects.

Still, you have to clarify how to then handle the department-specific subject scheme map, if it references a given subject scheme map, but with definitions of the same subject:

What is the processor expected to do? As effective subject scheme map you could either take the subject definitions of foo.ditamap, since you cannot extend the existing subject defs any more, yielding:

Or you redefine the subject defs of values-deliveryTarget, with the contents of your own subject scheme map, arriving at:

âand any other subject definitions from the referenced foo.ditamap would be part of the effective subject scheme map without change.

In my view, the second approach makes more sense. The thing is, is it to the spec to mandate this or is it up to the implementation to decide on the way, the effective subject scheme map is constructed? Or, is this already answered by standard key processing?

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Kristen James Eberlein
Sent: Thursday, January 13, 2022 18:22
To: DITA TC <dita@lists.oasis-open.org>
Subject: [dita] DITA 2.0 and the <schemeref> element: Removing the concept of extending a subjectScheme

The <schemeref> element is part of the subjectScheme structural specialization (introduced in DITA 1.2). It can only be used within subject scheme maps. Its purpose is to reference a subject scheme map.

The processing expectations for the <schemeref> element were ill-defined for DITA 1.2 and 1.3.

[Main point] I want to propose that we change that for DITA 2.0. And rather than suggesting that we spell out the processing expectations for the current design, I want to suggest that we simply remove the idea of "extending a subject scheme"/using @keyref in a subjectScheme map to redefine subjects. If we do that, we end up with NO special processing for the <schemeref> element.

If you want more information, read on. Othwise, stop right here.

Here's how we suggested that "extending a subjectScheme" worked in the DITA 1.2 and 1.3 spec. I write "suggested",because this was only outlined in (non-normative) examples.

A company has a standard map (foo.ditamap) that creates an enumeration for @deliveryTarget.
Example:

<subjectScheme>
    <subjectdef keys="values-deliveryTarget">
      <subjectdef keys="html"/>
      <subjectdef keys="pdf"/>
      <subjectdef keys="serviceDatabase"/>
    </subjectdef>
    <enumerationdef>
    <attributedef name="deliveryTarget"/>
    <subjectdef keyref="values-deliveryTarget"/>
</enumerationdef>
</subjectScheme>
A division builds their department-specific map (foo-revised.ditamap). They want to add "ePub" as a value for @deliveryTarget, so they construct the following subjectScheme map, which uses the <schemeref> element to reference the company's standard subjectScheme map.

<subjectScheme>
<schemeref href=""> <subjectdef keyref="values-deliveryTarget">
<subjectdef keys="ePub"/>
</subjectdef>
</subjectScheme>
Processors were supposed to then build an effective subjectScheme map that looked like the following:

<subjectScheme>
    <subjectdef keys="values-deliveryTarget">
      <subjectdef keys="html"/>
      <subjectdef keys="pdf"/>
      <subjectdef keys="serviceDatabase"/>
      <subjectdef keys="ePub"/>
    </subjectdef>
    <enumerationdef>
    <attributedef name="deliveryTarget"/>
    <subjectdef keyref="values-deliveryTarget"/>
</enumerationdef>
</subjectScheme>

Note that this is the contents of foo.ditamap, with a single <subjectref> added (highlighted in bold).

Seems slick and useful, right? Yeah, but implementing this would require redesigning how a processor handled key resolution. To the best of my knowledge no processor has implemented any support for this behavior.

Here's what we'd do for DITA 2.0
We keep the <schemeref> element, but our processing expectations are simply standard key processing. For example, using the scenario outlined above, the division could use their department-specific subjectScheme to create an enumeration for @outputclass:

--
Best,
Kris

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

dita message