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] Clarification on text insertion via keyref


Here is the message from Robert that Dave Helfinstine found on text insertion via keyref. We will use this as guidance in our design.

http://lists.oasis-open.org/archives/dita/201102/msg00059.html

Embarrassingly, I was involved in this thread at the time, and completely forgot.

Chris

-----Original Message-----
From: Nitchie, Chris 
Sent: Wednesday, September 28, 2011 5:32 PM
To: DITA TC
Subject: [dita] Clarification on text insertion via keyref

Folks,

We're working on filling out our keyref support with text insertion and support for @keyref on non-linking elements. As such we've been spending some time trying to parse the "Processing key references" topic in the 1.2 spec [1] and, frankly, we're a little stumped. I apologize in advanced if this was all covered in the DITA 1.2 process, but I missed the vast majority of that.

I see three pieces of guidance with regard to finding the effective contents for an empty key referencing element.

---
1. For elements on which no @href attribute is available [...], matching content is taken from the <keyword> or <term> elements within <keywords> within <topicmeta>. If more than one <keyword> or <term> is present, the matching content is taken from the first of them.

2. For elements that in addition to @keyref or @conkeyref do specify an @href attribute [...], matching content includes all elements from within the key definition element that are in valid context within the key reference. Elements that are invalid within the key reference element directly or after generalization are not included or are filtered out.

(3) When a key definition has a <topicmeta> subelement, elements that refer to that key and that are empty may get their effective content from the first matching subelement of the <topicmeta> subelement of the key-defining topicref. If no matching element is found, the contents of the <linktext> tag, if present, should be used. Elements within <linktext> that do not match the content model of the key reference directly or after generalization should be skipped. For <link> tags with a keyref attribute, the contents of the <shortdesc> tag in the key-defining element should provide the <desc> contents.
---

I put (3) in parentheses because it's not explicitly listed in the "Matching element content" rules - it's the second paragraph in the topic.

Now, my questions:

A. Does rule (3) apply to elements without @href, that is, can non-linking elements get effective text from <linktext> within <topicmeta>? The first sentence restates the rule for @href-bearing references, but the paragraph doesn't otherwise make the distinction explicitly, so it's not clear.

B. For rule 2, when "valid context" elements are found, what is propagated to the effective output, their contents, or are the elements themselves propagated as well? I'll illustrate with an example.

---
<keydef keys="someText">
  <topicmeta>
    <keywords>
      <keyword>Text</keyword>
    </keywords>
  </topicmeta>
</keydef>

<ph keyref="someText"/>
<lq keyref="someText"/>
---

If I'm reading the spec correctly, the effective "resolved" markup for the <ph> will not include the <keyref> element, because <ph> does not allow @href; but <lq> does allow @href, so the <keyword> element will be included, to wit:

---
<ph>Text</ph>
<lq><keyword>Text</keyword></lq>
---

Is that right?

C. If an element is a specialization of an @href-bearing element, like <data>, but does not itself allow @href, is it treated as an @href-bearing element or not? I think not, based on the letter of the spec, but that would introduce potential inconsistencies if fallback processing occurs.

D. There are cases when the rules for @href-bearing element would require processing that I'm not sure makes sense. A lot of stuff can appear within the contents of a key-defining topicref, and the rule as written requires processors to propagate everything that would be "in valid context" to the reference. So take this definition and references:

---
<topicref keys="api.SomeClass" href="api/SomeClass.dita">
  <topicmeta>
    <linktext><apiname>SomeClass</apiname> API Documentation</linktext>
    <searchtitle><apiname>SomeClass</apiname></searchtitle>
    <keywords>
      <keyword>SomeClass</keyword>
    </keywords>
  </topicmeta>
</topicref>

<ph keyref="api.SomeClass"/>
<xref keyref="api.SomeClass"/>
---

The processing of <ph>, a non-@href bearing element, is pretty straightforward. It becomes a linking element, and its effective text is taken from the keyword - in this case, "SomeClass."

However, according to the letter of the spec, processors must take all matching elements within the key definition and propagate them to the @href-bearing references. Does that mean that the resolved xref looks like this:

---
<xref href="api/SomeClass.dita">
  <apiname>SomeClass</apiname>
  <apiname>SomeClass</apiname>
  <keyword>SomeClass</keyword>
</xref>
---

Admittedly, this is a somewhat trumped-up example, but it illustrates a basic problem, either with my reading of the spec or the way it's worded (or both).

E. When an empty topicref has a @keyref attribute, are the contents of the key-defining topicref propagated en masse to the reference, minus invalid elements? I presume that's the reason the rule for @href-bearing elements is worded the way it is, but I want to make sure.

Finally, an observation: having different content propagation rules for @href-bearing and non-@href bearing strikes me as somewhat user-hostile. It's not always obvious to an author which elements are @href-bearing and which are not (and as my question C states, the distinction isn't always inherently for processors, either). Authors might be easily confused by seeing two references to the same key with different resolved contents. We're seriously considering an implementation whereby all non-topicref @keyref-bearing elements are processed via rules 1 and 3 (with some special handling of <link>) so as to simplify what an author needs to understand to have their content appear as expected. Since <keyword> is allowed inside most @href-bearing elements, I think this would effectively be a subset of what the spec, as written, mandates, and not an outright diversion.

To boil it down, I guess I'd like somebody to explain to me why it's important to treat <author> and <ph> differently for purposes of effective text.

Any help you can provide would be greatly appreciated. We're hoping to get this into our next release.

Chris

[1] http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/processing_key_references.html#processing_key_references



Chris Nitchie
Senior Software Engineer

T 734.352.2879   F 734.997.0201
E cnitchie@ptc.com

PTC.com




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