Re: [dita] "The DITA iceberg" presentation at DITA Europe 2016 -- how RNG focus could help

Here is a bit of Lightweight DITA perspective. I am throwing this on
    the list of possible solutions that Kris Eberlein provided earlier
    in this thread.

    

    In the LWDITA subcommittee we are working on a specialization tool
    that starts with a reasonably simple template file (basically a DITA
    topic) that you create to define your specialization. Then you run
    the template through a tool that generates an RNG schema for your
    specialization. From there we plan to use Trang to generate DTDs and
    XSDs if needed. A first pass on the tool, and other info on
    template-based specialization, is here:

    

https://github.com/oasis-open/dita-lightweight/tree/master/specialization

    

    Mark Giffin

    Mark Giffin Consulting, Inc.

    http://markgiffin.com/

    

    
On 11/17/2016 2:24 PM, Robert D
      Anderson wrote:

    

    
      
Hi all,

        

        I think this point needs a lot of thought / discussion:

        

        >> Maybe we need to move to a model where
          we encourage folks to configure, specialize, and constrain in
          RNG -- keeping to all the rules driven by modularization --
          but them convert the RNG to a monolithic DTD for use in
          production. Yes, this will limit ease of interchange, but ...

        

        This where I've been going in my head. It was prompted by the
        shock I went through finding people were (at great cost)
        maintaining modular XSDs and modular DTDs for the same grammar,
        simply to follow the spec grammar rules.

        

        Here's my thinking, which hopefully flows logically:
      

      
        
Some constraints are relatively easy in DTD (for those who
          can already understand DTD). Others have a clear pattern, but
          are hard. Many get so big as to be impractical (removing
          <ph> or <pre> from every context).
        

        
The entities we have to use in DTD are just plain ugly.
          They're required by DTD rules if we want
          specialization/constraints to work. But they're ugly.
        

        
Basic DTD rules also require that we order many files in a
          specific way. We lay those out as rules in our spec, because
          anybody doing this has to follow them or the DTD breaks. For
          other files, the order is less important, but we put rules on
          those too. Because saying "Put these 10 things in this order"
          is better than saying "Put these 7 things in order, then this
          one somewhere between 0 and 3, and these somewhere between 5
          and 7".

        

        
Constraints in RNG are easy. If you know XML but not RNG,
          the patterns are easy to learn. I mean ridiculously easy,
          compared to DTD.
        

        
In a world where we all write constraints in RNG, no single
          constraint is out of bounds simply because it's impractical.
        

        
If you (like we at OASIS) develop in RNG, everything else
          can / should be generated. Doing otherwise would be like
          developing content in DITA, but maintaining an HTML version in
          parallel.
        

        
Once it's generated ... the organization of the DTD / XSD
          shouldn't matter to the average DITA user. The use of
          entities, the number of files are irrelevant, because you'll
          never look at it. It's almost certainly more efficient to have
          a single file for use in your tools; it's certainly less
          confusing.
        

        
If we push this as a best practice with 2.0 ... constraints
          become almost trivial. Specialization isn't trivial, but it's
          certainly far easier than in DTD or RNG. Even those who cannot
          use RNG win.

      
      

      Point #5 above is the one that most closely relates to the iceberg
      problem. If base DITA with no domains is too much for you, today
      there are practical limits to what you can cut away, and still
      Follow The Rules. With RNG, that practical limit goes away.
      There's now a straightforward, easy to follow pattern for any
      constraint. At least, that is my understanding, and the basis for
      this entire note.

      

      One outcome from this could be for DITA 2.0 to get away from
      modular DTDs and XSDs entirely, but keep our rules / instructions
      for modular RNGs.

      

      There are reasons not to push everybody to RNG as their "source",
      but I'm wondering if the advantages outweigh the objections. 

      

      The following list of objections is probably not be exhaustive,
      but they're sure to come up:
      
        
Those with extensive DTD or XSD based specializations would
          clearly have a harder time upgrading to 2.0. Either we'd have
          to ship a modular copy of DTD / XSD just to allow this, or
          else they'd have to convert their modules to RNG.
        

        
Those trying to stay with modular DTD/XSD would no longer be
          able to easily exchange vocabulary modules. That said - in
          DITA 1.0 days we thought this would happen all the time, but I
          haven't seen it happen much in practice.
        

        
People already comfortable with DITA DTDs (there are a few
          of us) or XSDs would have to learn a new way of working. But
          ... that seems reasonable after 15 years, especially when RNG
          is so much easier.
        

        
People who spent weeks making a constraint to remove
          <ph> in XSD might be annoyed once they learn how easy it
          is in RNG. Of course that's probably an argument for the
          switch rather than a reason to oppose it...

        

      
      

      I'm curious to hear what others would think about this. If the
      logic doesn't make sense, I'll blame jetlag, having returned last
      night from Munich. As mentioned, I've been thinking about this for
      a while, so it's also possible I jumped over some logical step
      that I had wrestled with some weeks ago.

      

      
        
          

            Regards,
              
Robert
                    D. Anderson 

                  DITA-OT lead and Co-editor DITA
                      1.3 specification,

                    Digital Services Group 

            
            
          

          

            
              
          

          

            E-mail: 

              Digital Services Group 
            
              

            
          

          

            11501 BURNET
                  RD,, TX, 78758-3400, AUSTIN, USA 
          

          

            
              

            
          

        
      
      

      

      Kristen James Eberlein ---11/17/2016 02:46:17
        AM---Maybe we can separate the pain points raised in Leigh's
        presentation and possible solutions: Pain p

      

      From: Kristen
        James Eberlein <>

      To: Tom
        Magliery <>, DITA TC
        <>

      Date: 11/17/2016
        02:46 AM

      Subject: Re:
        [dita] "The DITA iceberg" presentation at DITA Europe 2016

      Sent by: <>

      

      

      

      Maybe we can separate the pain points raised in
        Leigh's presentation and possible solutions:
      
Pain points

      
        1. Our starter set of DTDs has more in it than
          many people want.

        2. Many people don't understand that they can
          configure their own document-type shells; they think the start
          set of shells ARE DITA. If they know that they can configure
          shells, it still might be too troublesome to implement them.
          For example, a small company with a handful of writers using
          version control on the file system will have to install
          doctype plug-ins whenever they upgrade their authoring tool or
          DITA-OT instance.

        3. Constraints are ridiculously time consuming
          to implement in DTDs. It's relatively simple to subset a
          domain -- but to remove base elements (for example,
          <pre>) requires constraining every element that can
          contain the base element. It's much easier in RNG. And it just
          doesn't really work in XSD.
      
      

      Possible solutions
      
        1. DITA 2.0 gives us the opportunity to modify
          what we include in the starter set of shells. We also could
          distribute other sets of shells ... I suspect that if we
          wanted to entertain that, we should NOT have them be part of
          the standard. We could "release" them as a package associated
          with a ZIP file.

        2. We need to do more education about
          configuration.

        3. Maybe we need to move to a model where we
          encourage folks to configure, specialize, and constrain in RNG
          -- keeping to all the rules driven by modularization -- but
          them convert the RNG to a monolithic DTD for use in
          production. Yes, this will limit ease of interchange, but ...

        4. Drop support for XSD.
      
      Best,

        Kris

        

        Kristen James Eberlein

        Chair, OASIS DITA Technical Committee

        Principal consultant, Eberlein Consulting

        www.eberleinconsulting.com

        +1 919 682-2290; kriseberlein (skype)

      

      On 11/16/2016 10:45 PM, Tom Magliery wrote:
      
        
          I love the idea of a smaller "standard
              DITA", and I look forward to months/years of entertaining
              discussion while "what's in" gets hammered out.

              

              mag

              

              

              -----Original Message-----

              From:  [mailto:] On Behalf Of Kristen James Eberlein

              Sent: Tuesday, November 15, 2016 11:19 PM

              To: DITA TC

              Subject: [dita] "The DITA iceberg" presentation at DITA
              Europe 2016

              

              Attached is a PDF from a session done by Leigh White,
              IXIASOFT, at this 

              year's DITA Europe conference. (I'll follow up later with
              some 

              additional PDFs from other sessions.)

              

              I'd like to ask TC members to read and consider it; I'm
              looking forward 

              to discussion on the list.

              

            
        
      
      

      ---------------------------------------------------------------------
        To unsubscribe from this mail list, you must leave the OASIS TC
        that generates this mail. Follow this link to all your TCs in
        OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php