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: Rendering keyref-bearing elements: using topicmeta vs local content


Title: 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
syeo@justsystems.com

XMetaL Community Forums: http://forums.xmetal.com

For partners only: http://www.justpartnercenter.com



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