Fwd: [dita-comment] Proposal for simplifying linking classes in the topic schema

Forward from dita-comment. This originally came in as a GitHub
      comment, which I closed with a recommendation that Chris Trenkamp
      post to dita-comment if he wanted the TC to consider this
      proposal.

    

    
Best,

      Kris

      

      Kristen James Eberlein

      Chair, OASIS DITA Technical Committee

      OASIS Distinguished Contributor

      Principal consultant, Eberlein Consulting LLC

      www.eberleinconsulting.com

      +1 919 622-1501; kriseberlein (skype)

      

      

    

    

      

      -------- Forwarded Message --------
      
        
          

            Subject:
            
            [dita-comment] Proposal for simplifying linking classes
              in the topic schema
          

          

            Date: 
            Wed, 2 Dec 2020 20:45:26 +0000
          

          

            From: 
            Trenkamp, Chris <>
          

          

            To: 
            
              <>
          

        
      
      

      

      
      
      
      

        
Proposal

        
DITA's topic schema can be simplified so
          there are only two kinds of classes for linking and text
          lookup.  This will preserve the meaning to author's with
          DITA's class extension functionality, while making it easier
          to implement.

        

        
* Any tag that can create a link should
          extend the - topic/xref class.

        
* The - topic/object class should be
          completely removed, but if it must be retained, then it should
          be changed (details below).

        
* Anything that can reuse text via
          @keyref/@keyscope should extend a common class.

        
 

        
Background

        
DITA's map schema allows you to create a
          TOC hierarchy and key references to DITA and non-DITA content
          using only only the - map/topicref class.  This is simple for
          implementors because all the different TOC/key tags all extend
          from the - map/topicref class, so there's only one class they
          have to check.

        

        
DITA's topic schema allows you to create
          links and reuse text, but there are at least four different
          classes for creating links (xref, image, link, and object),
          and an unknown number of other elements that allow you to
          reuse text if it contains @keyref.  This is difficult for
          implementors because it involves checking multiple kinds of
          different classes for creating links, plus a fuzzy @keyref
          lookup for reusing text on any kind of element.

        

        
The object tag:  this tag, in my opinion,
          is a violation of DITA's goal to abstract the target output
          from the content the author is trying to produce and is
          processed completely different from the other three linking
          tags.  First, you have to resolve @codebase/@codebasekeyref. 
          Then you have to resolve @classid/@classidkeyref and
          @data/@datakeyref, and may have to re-resolve it against
          @codebase.  Then you have to resolve multiple URI's against
          @archive and multiple keyref’s against @archivekeyref, and if
          any one of @archivekeyref successfully resolves, all the URI’s
          in @archive are overridden.  All of this special processing
          provides no extra value and could be accomplished using
          regular xref's. In addition, neither the object nor param tags
          have keyscope functionality and HTML5 deprecated @codebase,
          @classid, and @archive.

        
 

        
All the work that goes into implementing
          the different kind of links in the topic schema is
          unnecessary, and it can be drastically simplified.  I propose
          that any tag that can create a link should extend the -
          topic/xref class.  This way, implementors only need to look
          for one kind of class when creating links and pulling in
          non-DITA content.  I would also propose that the -
          topic/object class be removed, but if it must be retained,
          then it should be changed to a form that looks like this:

        
 

        
<object>

        
  <classid
          href=''
          scope='external'/> <!—scope=’external’ could be implied
          in the schema -->

        
  <data keyref='datakey'/>

        
  <archive keyref='archivekey1'/>

        
  <archive keyref='archivekey2'/>

        
  <param keyref='paramkey1'/>

        
  <param keyref='paramkey2'/>

        
</object>

        
 

        
Since the data, classid, archive, and param
          tags extend the - topic/xref class, they retain the same
          linking functionality, the keyscope functionality from xref
          will be inherited, it follows the exact same kind of
          processing as regular xref's, and the processor can still
          transform it to the proper output.  There is no need for
          @codebase since it not only provides no value, it can cause
          confusion when relative URI's are rewritten.

        

        
Finally, I would like to propose that
          anything that can reuse text via @keyref/@keyscope should
          extend a common class, though I don't know what.  This
          functionality is inherently different from regular linking
          because the text is defined on the topicref's metadata, rather
          than pulling in a title on a target topic.  This will help
          implementor's since, again, they only have to check one kind
          of class.

        

        
Conclusion

        
DITA's topic schema can be simplified so
          implementor's only need to worry about two different kind of
          classes for linking and text lookup.  This will preserve the
          meaning to author's with DITA's class extension functionality,
          while making it easier for implementor's since they don't have
          to worry about all the different kinds of possible tags that
          can link or reuse text.