dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Stage 2 proposal: make @audience, @platform, @product, and @otherprops into specializations
- From: "Robert D Anderson" <robander@us.ibm.com>
- To: "DITA Technical Committee" <dita@lists.oasis-open.org>
- Date: Wed, 28 Feb 2018 13:39:14 -0600
DITA 2.0 proposed feature #18: Make audience, platform, product, otherprops into specializations
DITA 2.0 should refactor the existing profiling attributes – @audience, @platform, @product, and @othermeta – so that they’re defined in domains and specialized from @props, as we did for @deliveryTarget in 1.3.
Date and version information
Date that this feature proposal was completed
Champion of the proposal
Links to any previous versions of the proposal
Links to minutes where this proposal was discussed at stage 1 and moved to stage 2
Links to e-mail discussion that resulted in new versions of the proposal
Link to the GitHub issue
Original requirement or use caseAs discussed at the TC May 2, 2017, the goal is to clean up our architecture by making the original four filter attributes into specializations of @props. They already function exactly the same way as @props (including the fact that they allow the grouping syntax that is exactly equivalent to the generalized attribute syntax). However, they were defined as part of the core before we had specialized attributes, so for backwards compatibility they have remained in the core even though logically they must be treated exactly the same as any specialization of @props.
Use cases
1. To clean up the language and simplify processors.
With DITA 1.0, the four attributes (@audience, @platform, @product, and @otherprops) were intended to be the only attributes available for filter / flag metadata processing. When attribute specialization was developed, a new base attribute called @props was added, also for filtering / flagging. To fully support the specification around filtering and flagging, processors must now support:
- The @props attribute
- Any unrecognized attributes that are properly specialized from @props
- Generalized syntax within any of those attributes
- A general processor must do all of that, but then add in exceptions for the 4 original attributes that function exactly the same but are not actually declared as specialized attributes.
With these four turned into specializations, any processor that supports @props + specializations of @props is complete.
2. To allow proper specializations of @audience, @platform, @product, and @otherprops. Authors have at times requested the ability to specialize these attributes - that need is explicitly what led to the grouping syntax added in DITA 1.3. However, because of the original DITA 1.0 design, these attributes could not be handled / specialized in the same way. Converting them to specializations of @props will allow architects to create new attributes off of these four, such as defining @appserver and @database as specialized variants of @product.
New terminologyN/A; any terminology needed for these already exists for specialized attributes.
Proposed solution
1. Create four new domain modules, one for each of @audience, @platform, @product, and @otherprops. Having these as four individual domains (rather than as one group) allows any architect to more easily remove any that do not apply – for example, keeping @audience while removing the other three.
2. Remove the existing definitions of these attributes. In OASIS grammars, these are defined as base attributes in the %filter-atts; group along with @props and a placeholder for extensions of @props. This is the only place the attributes are named in OASIS grammars (DTD: commonElements.mod; RNG: commonElementsMod.rng).
3. Add the domain attributes into the shells of all OASIS-provided grammar files, and add them to the props-extension group. This will restore the attributes to any element that previously defined them.
Benefits
Who will benefit from this feature?
- Processors can be simplified with one set of rules for all filtering / flagging
- Information architects gain the ability to remove any or all of these 4 without needing a constraint
- Information architects gain the ability to specialize directly from the existing attributes
- Maintainers of DITA specification can simplify language around these attributes and (more importantly) attribute grouping, which becomes an exact match for generalization syntax
How many people probably will make use of this feature?
Realistically, few authors will see a change, as many architects will likely restore all four attributes into existing shells, but this is just a guess.
How much of a positive impact is expected for the users who will make use of the feature?
Minor impact but goes along with the overall goal of simplifying the language.
Technical requirements
Adding new elements or attributes
Adding a domain
All existing shells will get these four new attribute extension domains, with zero overall change to content / attribute models. The domains will exactly match the pattern of the current @deliveryTarget attribute, both in how the module is defined and in how it is integrated into shells.
Adding an attribute
The four domains will add a total of four attributes, but with no overall change to the language as a whole.
Removing elements or attributes
Removing an attribute
The attribute definitions will be moved, which will technically remove the attributes from any shells that do not restore them. All DITA document types will be affected, and will need to update their shells as part of any migration to DITA 2.0.
Processing impact
Overall usability
No change to authors. Architects that maintain shells will need to go through the one-time process of adding these domains.
Backwards compatibility
Was this change previously announced in an earlier version of DITA?
It has been discussed in an unofficial capacity many times, but I'm not sure if it was officially announced.
Removing or renaming an attribute that was shipped in DITA 1.3?
The four attributes in question, from all elements.
Are element or attribute groups being renamed or shuffled?
This is closest in concept to the suggested change; the attributes are not going away, but moving them from the %filter-atts; group into their own domains will require updates to shells, but will have no impact on DITA documents.
Migration plan- No documents will need to be migrated.
- Processors may optionally remove exceptions in any filter/flagging code that explicitly look for these attributes, but as long as the processors correctly support @props and specializations, they will continue to work as designed.
- Document types that wish to retain all four attributes will need to add the four new domains into shells.
- Constraints that remove any of these attributes today will need to be updated; it may be possible to discard the constraint module and simply not include the relevant domain(s).
- Constraints that explicitly declare or restrict values on these attributes will need to be updated.
Costs
Outline the impact (time and effort) of the feature on the following groups:
- Maintainers of the grammar files: very small cost of removing the attribute definitions, small cost of creating and integrating the domain modules based on the existing @deliveryTarget pattern.
- Editors of the DITA specification:
- No new topics required.
- Definitions of these attributes will likely remain where they are, together in one topic with @deliveryTarget, but need additional language to clarify that they are domain specializations.
- The topics about filtering and grouping syntax will need editing, and can be simplified to treat all of these attributes in the same way as @props.
- Implementations: likely a low cost to remove extra support for these attributes, and allow them to use general support based on @props
- DITA community-at-large: those only concerned with authoring should see no change. There will be a small cost associated with updating shells, but we can provide straightforward patterns that allow cut-and-paste updates. Costs for updating constraints are harder to determine, because we do not know how many exist or what they are doing, but should not be large.
- Producing migration instructions or tools:
- Small cost for instructions on updating shells - basically, documenting the updates we make to our own shells.
- Small additional cost with (speculative) updates about impacts on constraint modules, with examples of how to update those we consider most likely to exist.
- No special white paper or publication is needed solely for this feature.
- Because grammar files can follow different patterns, cut-and-paste updates from the migration document are likely to be more reliable than a tool that updates DTD/XSD/RNG files.
ExamplesN/A; content is exactly the same.
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]