Title: Rendering keyref-bearing elements: using topicmeta vs local content
> I haven't been able to think of a
specific case in which you would put a
> keyref on a <keyword> element in a
topic and expect
local
content
>
to win
over topicmeta
content.
<glossref> would provide a
case, I should think.
From: Nitchie, Chris [mailto:]
Sent: Thursday, April 14, 2011 5:34 PM
To: Su-Laine Yeo;
dita
Subject: RE: [dita] Rendering keyref-bearing elements: using
topicmeta vs local content
I
worry a little bit about using @lockmeta, because you may have
non-resource-only key defining topicrefs for which @lockmeta will serve two
functions - behavior of the metadata with regard to the referenced topic, and
behavior of any references to that key - and the two would be inextricably
tied together. That is, there’s no way to code a topicref such that the
metadata in the topicref should take precedence over the metadata in the topic
(@lockmeta=”no”) and that this metadata should override any local text
for key references (@lockmeta=”yes”), and vice-versa. That said, I don’t have
a better suggestion, and I doubt such a situation would arise very often, but
it strikes me as a potential concern.
As
for some key references in the same map expecting the reference to win and
others expecting the definition to win, the solution for the latter is not to
include any link text in the key reference, as in example 2. Then, regardless
of how the key definition is coded, the appropriate text will be used. This
doesn’t strike me as a big problem.
Chris
From: Su-Laine Yeo
[mailto:]
Sent: Wednesday, April 13,
2011 8:19 PM
To: dita
Subject: [dita] Rendering
keyref-bearing elements: using topicmeta vs local content
Hi
everyone,
An issue which we
discussed in this week's TC meeting was how to render a keyref-bearing
element, such as a <term> or <xref>, if there is both content
within that element and content in <topicmeta> within the
key-defining element. For example (to lift an example from Tony Self's DITA
Style Guide), keyref
can be used to
replace general information with specific information:
------------------------------------------------
Example
1
<map>
<keydef
keys="car_name">
<topicmeta><keywords><keyword>Liberty</keyword></keywords></topicmeta>
</keydef>
</map>
and
<topic>
…
Your <keyword
keyref="car_name">car</keyword> has high intensity discharge
headlamps.
…
</topic>
------------------------------------------------
If the keyref
in Example 1 can be resolved, the sentence in the topic will
be rendered as: "Your
Liberty has high intensity discharge
headlamps." In this example, the author has deliberately put the word "car" in the topic
<keyword> so that if the keyref cannot be resolved, the sentence will read: "Your
car has high intensity discharge
headlamps." This
example shows that it can be useful to have the local content be treated as
fallback text, and for topicmeta content to win.
Now consider this
example, in which keyref is used to put a convenient
handle on a URL, but there is no intention of replacing general information
with specific information:
------------------------------------------------
Example 2
<map>
<keydef
keys="about_acme" href="http://www.acme.com/about">
<topicmeta><linktext>About Acme Corporation</linktext></topicmeta>
</keydef>
</map>
and
<topic
id="topicA">
…
The <xref
keyref="about_acme">history</xref> of Acme Corporation started in
1999.
…
</topic>
<topic
id="topicB">
…
Related
links:
<link
keyref="about_acme"></link>
…
</topic>
------------------------------------------------
In Example 2 topic A, you would want local content to win so that
the sentence
will be rendered as
"The history of Acme
Corporation started in 1999" and not "The About Acme Corporation of Acme
Corporation started in 1999." But you would want to have some <linktext>
defined in the map so that in topic B, link text appears where
there is no local content. This example shows that you would sometimes
want topicmeta
content to be treated
as fallback text, and want local content to
win.
I haven't been able to
think of a specific case in which you would put a
keyref on a <keyword> element in a topic and expect local content to win over topicmeta content.
At Tuesday's meeting, we
discussed using
the @lockmeta
attribute on <topicmeta> to indicate whether local content or
topicmeta content should win. The description for@lockmeta says,
"Indicates whether any of the meta information should be replaced by meta
information in the referenced topic. If the value is yes, the information
inside <topicmeta> should not be replaced with information from the
topic." (http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicmeta.html#topicmeta). Semantically, this
attribute seems appropriate. However one
possible issue is that by default,
@lockmeta is assumed to be
no, meaning that local content should win. In order to make topicmeta content
win, the user will have to explicitly set @lockmeta="yes".
Question for
discussion: Are we
comfortable with having the keyref FAQ say that if lockmeta="yes", topicmeta
content will win, and that if lockmeta="no" or is not set, local content will
win? In
practice, is the need
for this level of control important enough to justify the addition of this logic? I'm
not entirely sure of the latter myself.
Note that if we prescribe
this usage of @lockmeta, topic writers will still have to use keys in a way that
either assumes either
topicmeta will win for all uses of a particular key, or local content will win for
all uses of the key. The following example illustrates a case in which the
writer of topicA assumes local content win and the writer of topicB
assumes topicmeta will win.
------------------------------------------------
Example 3
<map id="Map
for Liberty">
<keydef
keys="car_maintenance" href="http://www.acme.com/maintentance/liberty>
<topicmeta><linktext>Maintaining the
Liberty</linktext></topicmeta>
</keydef>
</map>
<map id="Map
for Outback">
<keydef
keys="car_maintenance" href="http://www.acme.com/maintenance/outback">
<topicmeta><linktext>Maintaining the
Outback</linktext></topicmeta>
</keydef>
</map>
<topic
id="topicA">
…
Be sure to
<xref
keyref="car_maintenance" href="http://www.acme.com/maintenance">maintain
your car</xref>.
…
</topic>
<topic
id="topicB">
…
Related
links:
<link
keyref="car_maintenance" href="http://www.acme.com/maintenance">About
Maintenance for Acme
Cars</link>
…
</topic>
------------------------------------------------
Su-Laine
Su-Laine
Yeo
Solutions Consultant
JustSystems Canada,
Inc.
Office: 1 (778)
327-6356
XMetaL
Community Forums: http://forums.xmetal.com
For
partners only: http://www.justpartnercenter.com
