OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Notes on LwDITA -- xref/@type

I agree with Robert: The @type attribute is really only useful as a statement of intent for designers of specialized xrefs—for authored generic xrefs it adds no value and simply creates a potential “Simon Says” environment. In today’s processing world it should always be possible to resolve a reference (or determine that it is not resolvable).


For specialized xrefs it can be be useful to be able set a (notionally fixed) default for @type that indicates what the specialized xref *should* refer to, e.g.:


<element name=”fnref”>

  <attribute name=”type” a:defaultValue=”fn”>









Eliot Kimber





From: <dita@lists.oasis-open.org> on behalf of Robert D Anderson <robander@us.ibm.com>
Date: Monday, June 12, 2017 at 11:43 AM
To: Chris Nitchie <chris.nitchie@oberontech.com>
Cc: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: Re: [dita] Notes on LwDITA -- xref/@type


Responding here only about this item:
> Should <xref> have @type? Otherwise, how would processors distinguish between footnote references and other types of links?

I think processors should be free to evaluate the link, figure out on their own that it's to a footnote, and proceed accordingly. This would make footnotes links work exactly the same as any other in-topic links. That is -- a figure link that results in link text of "Figure X", or a table link that results in "Table X: Table Title", are really no different than an untyped footnote link that results in a superscript "X".

The language around values for xref/@type is ... not my favorite part of the specification, and in large part comes from expected usage + tool limitations going all the way back to DITA 1.0.

The specification does say this about the @type value on links: "If there is no explicit value for the @type attribute on any ancestor, a default value of "topic" is used." It also says that "it is an error if the actual type of a DITA topic and the explicit, inherited, or default value for the @type attribute are not the same as or a specialization of the @type attribute value." Again, that goes all the way back to DITA 1.0. At the time the language was informed by tools that could not (or did not) query linked elements to determine the type.

Even with that in mind:
1. The spec is also clear that applications MAY (not MUST or even SHOULD) give warnings when they think the target type isn't right.
2. I've never seen a DITA application that warned about missing type="table" on <xref href="" even though the spec might suggest this. We shouldn't have different expectations for <xref href="">
3. I think in the Olden Days of DITA, the very first versions of DITA-OT failed with cross references to footnotes. Using type="fn" made it work. This was a toolkit bug. It works now. (Not sure when it was fixed - I think long ago, but I've verified again in the latest). The spec (LwDITA or full DITA) shouldn't make people add type="fn" to get around obsolete tool limitations.

FWIW, Chris isn't the first one to ask about this -- the LwDITA group was operating under the assumption that type="fn" was mandatory until somewhat recently. I think that early experience with DITA, where type="fn" was a widespread tool requirement, really stuck in the minds of those who ran into it, so much so that it eventually became Just How Things Are Done.


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

nactive hide details for Chris Nitchie ---06/09/2017 04:16:22 PM---On theChris Nitchie ---06/09/2017 04:16:22 PM---On the whole, I think this is good. It does a nice job of presenting a simplified grammar for author

From: Chris Nitchie <chris.nitchie@oberontech.com>
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Date: 06/09/2017 04:16 PM
Subject: [dita] Notes on LwDITA
Sent by: <dita@lists.oasis-open.org>

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.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]