2.2 Technical Content edition
3.1.2 Stage three: #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=dit a
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.