Mapping of definition list entries from xdita to/from hdita

["Robert D Anderson" <robander@us.ibm.com>]

The basic problem we need to address is that we've claimed equivalence between XDITA and HDITA, but the wrapper element <dlentry> in XDITA currently offers something that cannot be mapped to HDITA. This is because the element itself does not exist in HDITA, so we need to be explicit about how get the same functionality from HDITA.

First a note on my possibly tortured language. In 12 years of working with / editing the DITA spec, I've learned to be very careful about words that imply a specific type of conversion. In this case, I'm going to be careful about the assumption that we are converting or mapping from HDITA to XDITA (or the reverse). Conversion language often implies a specific type of tool, which is where we get interpretations like "You have to convert from HDITA to real XML and then do xyz..."

Basically if we're claiming equivalence, then our job here is to lay out that equivalence, without assuming that you ever need to map from one format to the other. As an author, I just need to know how to mark up my chosen format; as an implementor, I can get from one format to the other (or not) any way I prefer, as long as items that mean the same thing are treated the same way. For what it's worth, I think the table in our appendix does a good job of this today.

So, with that pedantic note out of the way, my suggestion is:

• Filter attributes: in XDITA, @props is available on the <dlentry> but not on the <dt> or <dd>. In HDITA, the @data-props should be available on <dt> and <dd>. Setting the value on <dlentry> in XDITA is equivalent to setting the same value on both <dt> and <dd> in HDITA.
  NOTE: this means you can set different values for @data-props in HDITA for the term and definition. This cannot have a clear equivalence to a single value in XDITA. That said - if there were a way to disallow different values in HDITA, I would want to do that. With one required term and one required definition, using different conditions can result in an invalid model where you've got one but not the other.
• Localization atts: setting these on <dlentry> in XDITA is equivalent to setting the same values on both <dt> and <dd> in HDITA. Going the other direction is not an issue here; if the values are the same in HDITA, it's equivalent to setting them on <dlentry> in XDITA; if they differ, it's equivalent to setting them directly on <dt> and <dd> in XDITA.
• @conref: same as with localization going both directions. Reusing <dlentry> is equivalent to reusing both <dt> and <dd> in HDITA; reusing adjacent <dt> and <dd> in HDITA is equivalent to using XDITA's <dlentry>, while reusing non-adjacent <dt> and <dd> is equivalent to using @conref on <dt> and <dd> in XDITA.
• @id: this is the tricky one. If you do have a reason to transition between formats, you may need a place to hang dlentry/@id in the HDITA. I'm conflicted here.
  • In most cases, if I'm converting from one to the other, I don't want to care where things go, I just want my application to handle it. As an application developer, I'd want to handle it in a way that makes sense for the process I'm creating. In that case ... I'm not sure the spec should care. This is one reason I'm careful about mandating a specific conversion -- it may not make sense for every literal conversion.
  • That said ... the spec is trying to lay out equivalence. If I can set an ID on XDITA's <dlentry> group to refer to the group, and also on <dt> and <dd> in the same group ... I need to be able to do the same in HDITA.
  • So my suggestion is to have an ID on <dt> in HDITA that collectively refers to both the term and definition. I don't care what the ID is called. So I'll suggest @data-dlentryid on <dt> ... but could also see something like @data-groupid or (if we want to be generic) @data-parentid.
• @outputclass: same concerns and same resolution as with @id. I'd suggest having @data-dlentryclass, @data-groupclass, or @data-parentclass on <dt> as a way to collectively set an outputclass for both the term and definition.
  

And with all that said, I now remember why I put off writing this ;-)

Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA