Re: [dita] Stage 1 proposal: allow properties in section within refbody

Hi, Jang.

    
Here is how to submit a stage one proposal:

    
      
Send an e-mail to the list (DONE)

      
Attend a DITA TC meeting or arrange to have someone present
        your idea.

    
    
For a proposal to move to stage two, it needs to be championed by
      a voting member of the DITA TC.

    

    
Best,

      Kris

      

      Kristen James Eberlein

      Chair, OASIS DITA Technical Committee

      Principal consultant, Eberlein Consulting

      www.eberleinconsulting.com

      +1 919 622-1501; kriseberlein (skype)

      

    

    
On 3/26/2018 1:01 PM, Jang wrote:

    

    
      
      
Not sure about the formal aspects of a stage 1
        proposal, but here is the basic writeup:

      

      

      
While creating API documentation for complex objects
        I was looking for ways to split the information into sections
        within the single reference topic. To my surprise, only
        <simpletable> can be used inside a <section> of a
        <refbody>. I wanted to use <properties> but that is
        only allowed in <refbody> or in <refbodydiv>. I
        could create <refbodydiv> with a <p> figuring as
        title, but that is ugly and should not be required.

      

      

      
I can think of many similar use cases in machinery
        industry, where a single reference topic often has a number of
        clear sections, within which I would want to have the benefit of
        using the structure given by <properties> rather than the
        free-form <simpletable>.

      

      

      
My proposal is to allow <properties> in a
        <section> of <refbody>.

      

      

      
Implementation:

      

      

      
Option 1. Define a <refsection> (much like the
        <refbodydiv>, which includes both <simpletable> and
        <properties> in its content model.

      
Option 2. Redefine the content model for
        <section> in referenceMod.rng to also include
        <properties>. (not sure if this is possible)

      
Option 3. Move <properties> to a domain
        specialisation, making it available wherever <simpletable>
        is allowed. (but which domain ?)

      

      

      
My preference would be option 1.

      
      

        
Jang F.M. Graat
          Smart Information Design
          Amsterdam, Netherlands
          Cell: +31 646 854 996