Re: [dita-lightweight-dita] Mapping of definition list entries from xdita to/from hdita

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

Personally - I think your approach is fine as long as we're careful about what words we use when we talk about equivalence. Which can be tricky.

It's accurate to say today that they are functionally equivalent. Anything you need to do in one, you can do in the other:

• If you want to reuse the term/defn, XML does it in one step, HTML does it in 2.
• If you need to link to this point in the doc, XML lets you link to dlentry or dt, HTML lets you link to dt
• If you want to style both the definition and the term, XML has an extra way to do it on dlentry, but you can do still do it in HTML
  

So basically ... you have all the same options. The only thing you *don't* have is exact / automatic markup equivalence that enables round tripping. As I understood it in our meeting some weeks ago, that was the reason for encoding rules like these -- so that in theory, you could round trip.

All that said ... and again, my opinion ... for the committee note I'm completely on board with your approach -- <dlentry> cannot be mapped to HTML, but attributes can be preserved if needed with custom data attributes. Assuming we want those standardized, the LwDITA spec itself -- which again, isn't this document, and comes later -- can lay out specifically what those custom attributes are.

Make sense? 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

Carlos Evia ---09/18/2017 08:10:45 PM---Oh my... I am going to owe you more than one edible arrangement for this. This is quite the complica

From:        Carlos Evia <cevia@vt.edu>
To:        Robert D Anderson <robander@us.ibm.com>
Cc:        dita-lightweight-dita@lists.oasis-open.org
Date:        09/18/2017 08:10 PM
Subject:        Re: [dita-lightweight-dita] Mapping of definition list entries from xdita to/from hdita
Sent by:        <dita-lightweight-dita@lists.oasis-open.org>

---

Oh my... I am going to owe you more than one edible arrangement for this. 
This is quite the complicate attribute soup. 
I am tempted, for the purpose of this introductory committee note, to say that the XDITA <dlentry> cannot be mapped directly in HDITA, but with a footnote (enter your own joke about fnref here) saying that this could be accomplished with custom data attributes if truly needed. 
Acceptable?

Carlos 

-- 
Carlos Evia, Ph.D.
Director of Professional and Technical Writing
Associate Professor of Technical Communication
Department of English
Center for Human-Computer Interaction
Virginia Tech
Blacksburg, VA 24061-0112
(540)200-8201


On Mon, Sep 18, 2017 at 3:19 PM, Robert D Anderson <robander@us.ibm.com> wrote:

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