Stage 3 proposal: split syntax diagrams from programming domain

Iâm attaching the Stage 3 proposal for issue 361 to split syntax diagrams (and now syntax phrases) from the programming domain.

 

Thanks to Deb and Frank for reviews. Frank noted one thing, which is that the domain token (syntaxdiagram-d) is more verbose than many of the original ones (such as âpr-dâ that it used to have). I tend to link the more verbose ones better in this case, and it follows the pattern of more recent domain tokens, such as âditavalref-dâ. We should discuss whether others prefer a more abbreviated token in this case.

 

Thanks,

Robert

 

Title: Stage 3: #361: Split syntax and programming domains

  
    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.

          

    

  

Attachment:
Issue361-SplitSyntaxDomain.pdf

Description: Adobe PDF document