Notes on LwDITA

On the whole, I think this is good. It does a nice job of presenting a simplified grammar for authoring and processing, and while I might quibble with some of the omissions and design decisions here and there, on the whole I think it’s a good design.

I have two major concerns, and then some less serious notes and suggestions.

I think the lack of a multimedia domain in DITA 1.3 was a pretty major oversight. That said, I’m deeply uncomfortable with the introduction of a new multimedia domain as part of LwDITA. If there’s no equivalent domain in base DITA, interoperability between LwDITA and full DITA will be problematic. The only solution I see would be if the DITA TC released, as a stand-alone work product, a full DITA 1.3-compatible multimedia domain, which would be adapted for use in Lightweight DITA. I’d be happy to work on such a thing. Without it, I’m going to require some convincing as to why it shouldn’t be removed from LwDITA, despite its obvious utility.

Validation of HDITA and MIDTA is never mentioned, and so it’s unclear how processors are expected to respond to unexpected markup or content structures. Since existing rich text editors that are likely to be used for HDITA generally allow arbitrary HTML, I think the onus is on the LwDITA standard to define, clearly and unambiguously, what happens in exceptional cases (which aren’t going to be that exceptional). For example, what happens when there are multiple levels of <div> nesting, or no <h1> or Markdown title at the start of the file, or a stray <br> or other unrecognized tag, just to name a few examples I’ve wrestled with converting HTML comments into <draft-comment>? Without something addressing validation, we’re going to get a wide variety of behavior from different vendors, limiting interoperability. It’s also not something that can be fixed in future versions; it’ll be difficult to add validation constraints after-the-fact without breaking existing implementations.

Other notes and suggestions:

- Page 13: "The @keyref attribute is available only on the phrase or span element." This isn’t true. It’s also available on xref, alt, and data. It is also available on <ph> specializations. Suggest significant rewording of this sentence.

- Every Markdown variant I know of supports preformatted text by indenting four spaces; some support the ``` encoding, some don't. The spec doesn't mention using indentation for preformatted text in MDITA. It should.

- I'm not fond of '-hd-' in HDITA data attributes. I'd prefer if we either used '-dita-' or did without the intermediate qualifier entirely - data-conref, data-keyref, etc.

- Is there a reason to use @data-hd-class instead of just @class in HDITA?

- The presence of <object> specializations without <object> is irksome. I’d be much more comfortable if <object> was included.

- The lack of text directly in table cells and list items bothers me. I understand the rationale, but it also complicates the authoring of simple cases for those elements, which feels counter to the purpose of LwDITA.

- Should <xref> have @type? Otherwise, how would processors distinguish between footnote references and other types of links?

I also second all of Robert’s notes on the DTDs.

Chris

dita message