RE: [dita] Question on key resolution for complex <topicmeta> content

Title: RE: [dita] Question on key resolution for complex <topicmeta> content

Actually, for elements with a @keyref which can take a @href, the first rule for determining replacement text should be to resolve the indirect reference as if it were a direct one, right? E.g. say you have:

<map>

<keydef keys ="foo" href=""foo.dita">
        <topicmeta><keywords><keyword>bar</keyword></keywords></topicmeta>

</keydef>

</map>

<topic>

...

<xref keyref ="foo"></xref>

...

</topic>

Then this should be resolved as if it were:

<topic>

...

<xref href = ""foo.dita"></xref>
...

</topic>

For example, if HTML output is generated, the hyperlink text should be the title of the "foo.dita" topic. The way the spec is currently written implies that the hyperlink text should be "bar". I believe what is intended is for the hyperlink text to be "bar" if and only if the keydef element doesn't resolve to a resource.

Cheers,

Su-Laine

-----Original Message-----

From: Su-Laine Yeo [mailto:]

Sent: Monday, February 21, 2011 4:54 PM

To: dita

Subject: RE: [dita] Question on key resolution for complex <topicmeta> content

Thanks Chris, Robert, and Michael. I concur with Chris about the

intention being different from what the spec says. Let's finish getting

this darned thing ironed out. Otherwise questions about this passage are

going to keep coming back to us every time a different developer tries

to implement keyref and we're going to feel like we're on a

time-travelling spaceship. I think what we need is the following:

Someone should own the task of doing a rewrite of the following

statement:

"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... For elements that in addition to @keyref or

@conkeyref do specify an @href attribute (such as author, data,

data-about, image, link, lq, navref, publisher, source, topicref, xref,

and their specializations), 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."

Then the TC should review and approve it. Then it can go into the keyref

FAQ and/or DITA 1.2 erratum.

As a question that might be easier to answer quickly, would the

following processor behaviour be considered compliant with DITA 1.2?

********************

For elements with a @keyref which cannot take a @href, determine the

element contents as follows:

- First choice: Use content from the first <keyword> or <term> within

<keywords> within <topicmeta>.

- Second choice if there is no <keyword> or <term> in <topicmeta>: Use

the contents of the <linktext> element in <topicmeta>.

- Third choice if there is no <keyword> or <term> or <linktext> in

topicmeta:  Use the contents of the <navtitle> element in <topicmeta>.

- Fourth choice if there is no <keyword> or <term> or <linktext> or

<navtitle> in <topicmeta>: Use the contents of the local element, i.e.

the one with the @keyref on it.

For elements with a @keyref which can take a @href, determine the

element contents as follows:

- First choice: Use the contents of the <linktext> element in

<topicmeta>.

- Second choice if there is no <linktext> in topicmeta:  Use the

contents of the local element, i.e. the one with the @keyref on it.

For elements with a @keyref which can take a @href and can also contain

a <desc> subelement, determine the contents of the <desc> subelement as

follows:

- If <topicmeta> contains a <shortdesc> element, copy the contents of

the <shortdesc> into the <desc> element.

- If <topicmeta> does not contain a <shortdesc> element, and a local

<desc> element already exists, use the contents of the local <desc>

element.

- If <topicmeta> does not contain a <shortdesc> element, and a local

<desc> element does not exist, do not create an empty <desc> element.

When you copy content from <topicmeta>, include markup that is valid in

the new context. Strip any markup that is not valid in the new context.

********************

Cheers,

Su-Laine

-----Original Message-----

From: Nitchie, Chris [mailto:]

Sent: Monday, February 21, 2011 10:46 AM

To: Robert D Anderson; Su-Laine Yeo

Cc: dita

Subject: RE: [dita] Question on key resolution for complex <topicmeta>

content

I think this is correct, but as seems to often be the case lately, it's

not what the spec says WRT elements with @href. From 2.1.3.4.3.3:

"For elements that in addition to @keyref or @conkeyref do specify an

@href attribute (such as author, data, data-about, image, link, lq,

navref, publisher, source, topicref, xref, and their specializations),

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."

I suspect changing the words "key definition element" to "the linktext

element within the key definition element's topicmeta element" would

line the spec up with what Robert lays out below.  I've long been

flummoxed by this passage when it comes to processing text replacement

for common xrefs, and I'm glad to hear that this isn't how it's supposed

to work. The only reason I can think of for the above language is if the

intention is for the body of a <topicref> with a @keyref to have its

entire contents replaced by those of the key-defining topicref, but

that's what conref/conkeyref is for, right?

I also don't think mentioning @conkeyref in this context is appropriate,

but that's a different, much less serious issue.

Chris

-----Original Message-----

From: Robert D Anderson [mailto:]

Sent: Monday, February 21, 2011 11:34 AM

To: Su-Laine Yeo

Cc: dita

Subject: Re: [dita] Question on key resolution for complex <topicmeta>

content

Hi Su-Laine,

I hear that Michael and I had a to-do to come back on this. We discussed

it

while looking at both the quoted spec passage [1] and the original, TC

approved proposal [2]. Our analysis is based primarily on a few items:

* Additional language in [1] that specifically defines "matching

content"

* Items 22 and 23 in the "Technical requirements" from [2]

* Sample in Use Case 4 in [2]

In both documents, there are two distinct categories of key based

content

substitution -- 1 for elements without @href, and one for elements with

@href.

For elements without @href - the specification says that "matching

content

is taken from the <keyword> or <term> elements within <keywords> within

<topicmeta>". The first keyword or term is used if more than one is

specified. Based on use case #4 in [2], and on previous discussion on

the

TC list, the intent was to use <linktext> as fallback. Based on

processes

elsewhere and on user expectations, it seems logical that <navtitle>

should

be a further fallback, but that is not specifically addressed. So, our

understanding works as follows:

1. Take content from the first <keyword> or <term> within <keywords>

within

<topicmeta>.

2. If that is not found - the replacement text should be the full

contents

of the linktext element. The spec and proposal say that elements which

are

not allowed in the new context should be dropped; I think it makes far

more

sense to use a text-only version of the content. That is - if "This is

<b>important</b>" goes into a context that doesn't allow phrases, it's

better to use "This is bold" than to use "This is". But - that should

probably be a clarification (or at least specifically allowed) in DITA

1.3.

3. If linktext is not found, the same rule can be applied to the full

contents of <navtitle>.

For elements with href - we understand that the matching content is

meant

to come from the linktext element, with the same rules about dropping or

generalizing disallowed content. The specification states that for

<link>,

a <shortdesc> element in the key definition should become a <desc>

element

in the <link> element; I personally expect the same behavior to apply to

<xref>. I think that navtitle is again a logical fallback when linktext

is

not specified.

My own opinion is that DITA 1.3 should clarify the behavior for specific

elements with href, so that some can be handled differently. For example

-

I think DITA 1.3 should state that <image> places content from linktext

into <alt>. It could also allow author/@keyref to match an author

element

before falling back to linktext. These behaviors are not hinted at in

either the proposal or specification, so I think the cannot

realistically

be added to DITA 1.2 as a fix or clarification.

[1]

http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/processing_key_ref

erences.html

[2]

http://www.oasis-open.org/committees/download.php/26493/IssueNumber1207v

8b.html

Robert D Anderson

IBM Authoring Tools Development

Chief Architect, DITA Open Toolkit

From:   "Su-Laine Yeo" <>

To:     <>

Date:   02/07/2011 09:26 PM

Subject:        [dita] Question on key resolution for complex

<topicmeta>

            content

Hi everyone,

It is not entirely clear to my team, either from the spec or from

Eliot's

Understanding DITA Keys and Key Spaces article, how keys should be

resolved

if the <topicmeta> element within a <keydef> contains complex content.

The DITA 1.2 spec says:

"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... For elements that in addition to @keyref or @conkeyref do

specify an @href attribute (such as author, data, data-about, image,

link,

lq, navref, publisher, source, topicref, xref, and their

specializations),

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."

The first sentence says that the effective content is the "first

matching"

subelement in <topicmeta>. Does "first matching" "first element of

exactly

the same element type as the element which refers to the key," or does

it

mean something else?

The second sentence seems to say that the effective content should

include

multiple elements from <topicmeta> if they are valid in element which

refers to the key. E.g. say a <xref> element is resolved using a keydef,

and that keydef contains the following subelements:

<topicmeta>

<shortdesc>My short description content</shortdesc>

<keywords><keyword>keyword1</keyword><indexterm>indexterm1</indexterm></

keywords>

<keywords><keyword>keyword2</keyword><indexterm>indexterm2</indexterm></

keywords>

</topicmeta>

Should the processor should resolve this as:

Option 1:

<xref></xref>

Or should the processor resolve it as:

Option 2:

<xref>

<keyword>keyword1</keyword>

</xref>

Or as:

Option 3:

<xref>

<keyword>keyword1</keyword><indexterm>indexterm1</indexterm>

</xref>

Or as:

Option 4:

<xref>

<keyword>keyword1</keyword><indexterm>indexterm1</indexterm>

<keyword>keyword2</keyword><indexterm>indexterm2</indexterm>

</xref>

Cheers,

Su-Laine

Su-Laine Yeo

Solutions Consultant

JustSystems Canada, Inc.

Office: 1 (778) 327-6356



---------------------------------------------------------------------

To unsubscribe from this mail list, you must leave the OASIS TC that

generates this mail.  Follow this link to all your TCs in OASIS at:

https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

---------------------------------------------------------------------

To unsubscribe from this mail list, you must leave the OASIS TC that

generates this mail.  Follow this link to all your TCs in OASIS at:

https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php