Stage 3 proposal: make @outputclass universal

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

Stage 3 proposal: Feature #17 make @outputclass universal

Make @outputclass a universal attribute on all elements defined as part of the DITA specification.

Champion

Robert D Anderson

Tracking information

Event	Date	Links
Stage 1 proposal accepted	Jan 24 2017	https://lists.oasis-open.org/archives/dita/201701/msg00097.html
Stage 2 proposal submitted	June 12 2018	DITA version: https://tools.oasis-open.org/version-control/svn/dita/trunk/DITA-2.0/stage-2/Issue17-universalOutputclass.dita HTML version: https://www.oasis-open.org/apps/org/workgroup/dita/download.php/60973/Issue17-universalOutputclass.html
Stage 2 proposal discussed	July 11 2018	https://www.oasis-open.org/committees/download.php/61199/minutes20170711.txt
Stage 2 proposal approved	July 18 2018	https://www.oasis-open.org/committees/document.php?document_id=61257&wg_abbrev=dita
Stage 3 proposal submitted to reviewers	February 28 2018	Sent to Dawn Stevens, Scott Hudson
Stage 3 proposal (this document) submitted	February 28 2018	https://tools.oasis-open.org/version-control/browse/wsvn/dita/trunk/DITA-2.0/stage-3/Issue17-stage3-universalOutputclass.dita

Approved technical requirements

Apart from the <dita> container element, add @outputclass to every element in the specification that does not already allow that attribute.

Dependencies or interrelated proposals

Any proposal for a new element in DITA 2.0 needs to ensure that @outputclass is allowed.

The original LwDITA proposal anticipated that @outputclass would be available everywhere but had to be adjusted when that was determined to be incorrect. A new version of LwDITA may want to make use of this attribute on those elements if it has not already done so.

Modified Grammar files
The @outputclass attribute should be declared for any element that does not already have it, as follows:
<optional><attribute name="outputclass"></optional>
The most reliable way to do this is to add it to the universal attribute group – assuming the other groups are not modified, this will make:
<define name="univ-atts">
     <ref name="id-atts"/>
     <ref name="select-atts"/>
     <ref name="localization-atts"/>
     <optional>
       <attribute name="outputclass">
     </optional>
   </define>
All modules that independently declare @outputclass will need to be updated, EXCEPT for those that also need to override univ-atts (for example, <topic> and its specializations must override univ-atts in order to make @id required). The attribute is currently declared in a large number of files, and can likely be removed with a good search/replace _expression_. The @outputclass attribute is currently declared in 46 independent RNG files from DITA 1.3, so this proposal effectively updates every module that declares elements to remove one or more instances of the line above. Those in the base package that will need updates include:

• commonElementsMod.rng
• delayResolutionDomain.rng (likely to be dropped from DITA 2.0)
• ditavalrefDomain.rng
• hazardstatementDomain.rng
• highlightDomain.rng
• mapGroupDomain.rng
• tblDeclMod.rng
• topicMod.rng
• utilitiesDomain.rng
• classifyDomain.rng
• subjectSchemeMod.rng

DTD updates are comparable. The following attribute declaration will be needed in the univ-atts declaration:
outputclass     CDATA      #IMPLIED

The same declaration will need to be removed from every element that currently uses it; as with RNG, this will effectively mean removing that same declaration from every module that declares elements.

Modified terminology

No new or updated terminology.

Modified specification documentation

• The @outputclass definition will move from the "Other common attributes" topic to the "Universal attribute group" topic.
• Every element reference topic that independently links to the @outputclass definition will need to remove that link. As in the technical requirements section, there is an exception for any element that overrides the universal attribute group, which will keep the link to @outputclass in its new location. 73 topics in specification/langRef/base/ link to @outputclass and need to be updated. The attribute reuse topic also contains a few reusable definitions that link to @outputclass.
  Note: For most DITA 2.0 proposals I'd expect this section to have a list of all modified topics. For this reason I don't think it is necessary, because:
  1. The change involves removing a single trivial item in many places, rather than adding any new language that must be reviewed.
  2. The change exactly the same in all 73 topics, so describing or explaining it 73 times will not aid in evaluating the proposal.
  3. Listing all 73 would also not be helpful for the spec editors; any editor implementing this change is going to do so with a quick search across the topics. That is, I would not expect any editor to make updates based on a list of 73 topics here (which I came up with using a search), because that process would be more time consuming and less reliable than doing that same search on the source.

Migration plans for backwards incompatibilities

Most structural or domain specialization modules that declare elements will need to be updated to remove declarations of @outputclass.

There is not currently a plan for an automated way to accomplish this for DTDs, due to the wide variety of coding practices for DTD modules. XSD and RNG could likely be automated with a search/replace algorithm that handles complex regular expressions, but this may result in removing the attribute from elements that do not use the universal attribute group.

Current suggestion for migration instructions is as follows (to be clarified with addition details based on our own experience updating the OASIS shells):

1. Use search/replace to remove all declarations of @outputclass from any working DITA 1.3 specialization modules. This can be done by hand with a search / manual removal or (depending on grammar format and coding practice) with a search/replace query that automatically removes the declaration.
2. Once the updated modules are added to DITA 2.0 level shells, use trang or a similar tool to convert the grammar files (DTD, XSD, or RNG) into a single RNG file.
3. Run a (to-be-written) script over that RNG to check for any elements that do not declare @outputclass. For any elements that do not declare the attribute, restore the declaration in your specialization module (in the DTD, RNG, or XSD – not in the single generated RNG).
4. The single generated RNG can be discarded once this process is completed.

Note: As Dawn pointed out during her review of my first stage 3 draft, the definition of XML itself technically allows you to declare an attribute twice, but it's considered a warning. This could reduce the urgency of migration by some small amount because this change alone will not break anything. That said, the warnings you're likely to receive from your editors and build systems will likely push you to migrate quite quickly, and long term a migration is definitely worth the relatively small effort of removing declarations.

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