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

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Hi, Jang.

Here is how to submit a stage one proposal:

1. Send an e-mail to the list (DONE)
2. 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