Stage 3: #361: Split syntax and programming domains

Split syntax diagram from programming domain so that they can be used (and supported) independently.

Champion

Robert D Anderson

Tracking information

Event Date Links
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 domain.

Dependencies or interrelated proposals

N/A.

Modified grammar files

List the files that must be modified and provide the exact code modifications (preferably RNG, as DTD / XSD should be generated).
  • 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
  • Specifically:
    • 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 terminology

N/A

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

Specifically:
  • 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 @class 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 pr-d/ to syntaxdiagram-d/.

So, for example, a processor that currently includes support for pr-d/syntaxdiagram will alternatively:
  • Change all processing that looks for pr-d/syntaxdiagram so that it looks for both the original pr-d/syntaxdiagram and 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/syntaxdiagram so 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.