Stage 3: #361: Split syntax and programming domains
Split syntax diagram from programming domain so that they can be used (and supported) independently.
Robert D Anderson
|Stage 1 proposal accepted||June 30, 2020||https://lists.oasis-open.org/archives/dita/202007/msg00011.html|
|Stage 2 proposal submitted||June 30, 2020||https://lists.oasis-open.org/archives/dita/202007/msg00002.html|
|Stage 2 proposal discussed||7 July 2020||https://lists.oasis-open.org/archives/dita/202007/msg00010.html|
|Stage 2 proposal approved||28 July 2020||https://lists.oasis-open.org/archives/dita/202008/msg00000.html|
|Stage 3 proposal submitted to reviewers||25 August 2020||Frank Wegmann, Deb Bissantz|
|Stage 3 proposal (this document) submitted to TC||31 August 2020|
Approved technical requirements
Split the programming domain into two domains, with
<syntaxdiagram> and child elements in a new syntax diagram
Dependencies or interrelated proposals
Modified grammar files
- No impact to base map and topic (this only affects the technical content package).
- Grammar file updates to technical content include shell updates (every shell including programming domain now adds syntax domain), and the work to split programming into two modules. These changes are recorded here: https://github.com/robander/dita-techcomm/commit/fa2939e317e87711360e54e86b1b8edacb6bd423
- Create a new domain module (RNG and DTD) for syntax.
- Include all elements that are moving from the programming domain.
- Delete those same elements from the programming domain.
- Update class attributes for syntax elements so that they are specializations of the programming domain.
- Update shells to include the new domain.
Modified specification documentation
Only minor changes affecting the inheritance section, as well as the TOC to create a new group for the syntax diagram domain.
Changes are recorded here: https://github.com/robander/dita-techcomm/commit/37bc0d8a5d810853e5ea62f40a3bc3f974f982b9
With one additional change recorded here: https://github.com/robander/dita-techcomm/commit/f754bc596398be2e702252276c8bb82bc18b7d18
- Create a new section of the TOC for the syntax diagram domain, and move relevant languge spec topics from the programming domain into the new section.
- Create a new container for the new domain.
- Update the inheritance section and the index entries for all elements that moved, so that they list the new domain.
- Update the "Element by element recommendations for translators" topic to match the split, with a new table for the new domain.
- Tweak a couple of examples that mention synph just to clean up the language (refer to syntax phrase rather than synph).
- Add the new domain to a list of domains that are part of the technical content specification.
Migration plans for backwards incompatibilities
Tools that process syntax diagram elements should search and replace
matches for all of the moved elements, replacing them with either the new class attribute
pattern, or with both (so that processors can handle both 1.x and 2.x).
Specifically, for each of the migrated elements, the token on the left part of the class
attribute has changed from
- Change all processing that looks for
pr-d/syntaxdiagramso that it looks for both the original
pr-d/syntaxdiagramand the new
syntaxdiagram-d/syntaxdiagram(thus supporting both DITA 1.x and DITA 2.x).
- Or, change all processing that currently looks for
pr-d/syntaxdiagramso that it looks for the new token
syntaxdiagram-d/syntaxdiagram. Even in this case, a separate processing step that normalizes class attributes to the old or new value would allow the processor to work with both DITA 1.x and DITA 2.x.