Stage 2 proposal: remove xtrf / xtrc (rendered copy for discussion, source is in SVN)

["Robert D Anderson" <robander@us.ibm.com>]

DITA 2.0 proposed feature #46: Remove @xtrf and @xtrc

The @xtrf and @xtrc attributes were added in DITA 1.0 purely for processing purposes, to add a standard way for processors to store mid-conversion debug information while (in theory) retaining validity against an original DTD. This is a legacy concern outside the scope of the standard / outside of the usual interoperability concern; they should be removed as part of the effort to clean up DITA 2.0 and remove obsolete or unnecessary markup.

Date and version information
Date that this feature proposal was completed

January 30, 2018

Champion of the proposal

Robert D Anderson

Links to any previous versions of the proposal

• Stage 1 details stored in tracking issue https://github.com/oasis-tcs/dita/issues/46
• Latest SVN version of the proposal: https://tools.oasis-open.org/version-control/browse/wsvn/dita/trunk/DITA-2.0/stage-2/Issue46-removeXtrfXtrc.dita

Links to e-mail discussion that resulted in new versions of the proposal

N/A

Link to Github issue

https://github.com/oasis-tcs/dita/issues/46

Original requirement or use case

The @xtrc and @xtrf attributes were added to all elements in DITA 1.0. They are entirely intended for processing purposes, with a DITA-OT style processing model in mind. Specifically, the expectations were that:

1. Assumption (often but not always true): Processors would read/write DITA files as they evaluated features like @conref (as DITA-OT has done since early days in the temporary directory).
2. Assumption (often but not always true): Processors needed to a place to track the source each element to enable later debugging (this was done by some processors with @xtrc and @xtrf even in DITA beta days).
3. Assumption (not a valid assumption!): Each DITA document had to remain valid during every read/write operation in the temp directory, including with this debug information. DITA-OT has never followed this and will not in the future; I only know of one tool in beta DITA days that had this requirement.
4. Result: Because processed DITA with debug info had to be valid, every DITA element needed to declare @xtrc and @xtrf as part of the standard. (At the time, there was no way to specialize attributes, so they had to be in the standard to be valid.)

The DITA specification (in the last couple of releases) has moved away from adding functionality or markup based on what is done with processed DITA, in particular what might be done by one single processor but not others. Instead it uses DTD / RNG to place rules on the source, but once processors start working with it, something like storing debug information is completely up to the processor.

The standard cannot and should not try to design this aspect of any DITA implementation, particularly a feature like this that presents no interoperability concern. Based on item #3 above, even the implementations that resulted in these attributes consider them obsolete as part of the standard.

Use cases
The use cases for removing these are:

• Cleaner language; when attributes are unnecessary, there is no reason for them to clutter up the language, the specification, and the attribute list within an authoring tool.
• Cleaner implementation; there is not (and cannot be) a requirement for implementations to use these attributes as designed, but their presence forces implementors to consider them and may guide implementations down an unnecessary path.
• The attribute names themselves are a point of confusion when first encountered, adding to DITA's "perception of complexity" problem.
• There is not a requirement for specialized elements to declare these attributes, so the idea that any implementation can assume they are "global attributes" is already false. At the same time, those designing specializations are often afraid to remove them because it's not clear what they're doing (again adding to the complexity problem).

New terminology

N/A

Proposed solution

Remove the @xtrf and @xtrc declarations from grammar files and from the specification.

Benefits
Who will benefit from this feature?

Authors, information architects working on specializations, DITA implementations, maintainers of the DITA specification.

What is the expected benefit?

Simplified language leads to reduced complexity & less noise in the language.

How many people probably will make use of this feature?

N/A; nearly all audiences will have the very slight benefit of not running into or having to think about the attributes at some point.

How much of a positive impact is expected for the users who will make use of the feature?

Minor impact to wide audience.

Technical requirements
Removing elements or attributes

Removing an attribute
• The @xtrf and @xtrc attributes are currently declared for every element that is formally part of the standard, as part of the %global-atts; entity. This entity would be removed from all MOD files that list it (this includes nearly every MOD file that declares elements).

Processing impact

Should not have any processing impact. Tools like DITA-OT that declare this attribute in intermediate files can continue to do so, but this is not required.

Overall usability

N/A

Backwards compatibility
Was this change previously announced in an earlier version of DITA?

No, though it has been discussed infrequently in various forums. (Some have complained at the absurdity of such a processing feature being part of the core specification.)

Removing or renaming an attribute that was shipped in DITA 1.3?

Yes, removing two attributes from every element.

Removing or replacing a processing feature that was defined in DITA 1.3?

Technically yes, removing these attributes is removing a specification-defined method to store debugging information. However, that usage is still allowed by the specification (and could not be prevented in any case).

Migration plan
For documents that may use the attributes:

• A tool could be provided to explicitly scan for and delete any instances of these attributes in source files.
• If any script exists to help migrate documents to DITA 2.0 (as is generally anticipated), this is an easy addition to that tool.

Might any existing processors or implementations need to change their expectations?

Yes, if cases exist where these attributes were not used as intended. Specifically, it's possible that somebody has noticed that these attributes 1) exist on every element, 2) have no meaningful definition with regards to interoperability of source material, and 3) used them as a handy place to drop some other form of annotation or metadata. In such cases, there are a few alternatives:
1. Create an attribute domain that declares @xtrf and @xtrc as specializations of @base, add that to local shells, and continue as-is.
2. Preferably, do the same, but give the attributes names related to their purpose.
3. If "no specialization or extension" is a requirement, use @base directly as the generic "extensible for any purpose" attribute. Alternatively, a recent proposal from Eliot for a global metadata attribute (also specializable) may serve the purpose.

Might any existing specialization or constraint modules need to be migrated?

Yes - most existing element specialization modules will need an update. It's possible that constraints will need an update, but much less likely.

The two attributes are added to all OASIS based modules using a consistent pattern for each grammar (always using the global-atts name). While this is not required, that pattern is followed in all of the specialization modules I've encountered, and I suspect it is true of most modules:

• In DTDs, the attributes are added with the %global-atts; parameter entity:
  <!ATTLIST  steps        %global-atts;  class CDATA "- topic/ol task/steps ">
• In RNG, the attributes are also added with the class attribute:
  <define name="steps.attlist" combine="interleave">
       <ref name="global-atts"/>
       <optional>
         <attribute name="class" a:defaultValue="- topic/ol task/steps "/>
       </optional>
     </define>
• In XSD, the attributes are added with an attribute group:
  <xs:attributeGroup name="steps.attributes">
       <xs:attributeGroup ref="univ-atts"/>
       <xs:attribute name="outputclass" type="xs:string"/>
       <xs:attributeGroup ref="global-atts"/>
    </xs:attributeGroup>
If a utility is created to help scan and update specialized grammar files for DITA 2.0, removing these items is a trivial addition.

If that utility does not exist, removing these references can be done with a search/replace operation that matches the exact sequences above and replaces them with an empty value. I would expect this to work for nearly all specialization modules. If modules exist that independently declare @xtrf or @xtrc, then the same search-and-replace process can be used with a search for those attribute declarations.

Costs
Maintainers of the grammar files

Minor cost, primarily search and replace, to remove the attribute group and its usage.

Editors of the DITA specification:

How many new topics will be required?
None
How many existing topics will need to be edited?
• The global attribute topic will need to be removed: http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/langRef/attributes/debugAttributes.html
• Element definitions that explicitly list and link to these attributes will need to remove the reference (based on DITA 1.3, assumes these elements remain in DITA 2.0): <attributedef>, <dita>, <elementdef>, <enumerationdef>, <no-topic-nesting>, <ux-window>
Will the feature require substantial changes to the information architecture of the DITA specification?
No
f there is new terminology, is it likely to conflict with any usage of those terms in the existing specification?
No

Vendors of tools:

Only cost is to tools that make use of these attributes in ways not intended; see the "migration plan" section above.

DITA community-at-large:

Will this feature add to the perception that DITA is becoming too complex?
No, it should reduce that perception.
Will it be simple for end users to understand?
N/A
If the feature breaks backwards compatibility, how many documents are likely to be affected, and what is the cost of migration?
• Few DITA maps or topics, as this attribute is not intended for use in source documents
• Specialization modules will need to be updated to remove these attributes; this is a straightforward process with easy migration instructions
• Tools that used these attributes in a way not intended may have a higher cost; that cost will depend on how the attributes were used

Producing migration instructions or tools:

How extensive will migration instructions be:
Minimal - full instructions covered above
Will this require an independent white paper or other publication to provide migration details?
No
Do migration tools need to be created before this change can be made? If so, how complex will those tools be to create and to use?
No, though it would be helpful. Migration tools for source should not be very complex. Migration tools for grammars could be more difficult because there are many ways these could be defined. A good search/replace tool is likely the fastest way to migrate specializations.

Examples

N/A.

If the attribute is used as intended, it will not exist in source files before or after migration.

If the attribute is used in some other way (not as defined in the spec), before/after migration examples will depend on that usage.

Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA