conkeyref broken referring to composite

jdbecker · Post by **jdbecker** » Tue Aug 29, 2023 7:50 pm

Hi,
coming from an antique Oxygen 16, I was just greeted by a ton of broken conkeyrefs.
Quoting from https://www.oxygenxml.com/dita/stylegui ... abase.html
… the composite or ditabes topic is now obsolete … However, ditabase still has some use as a container for re-use information, because it allows concept, task, reference and other information type elements to be contained within the same topic. This can be useful if you want to organise snippets of conref source information into a single topic.

While the quote only mentions conref, otherwise that's exactly my use case. Unfortunately a large share of my conkeyrefs all point into the second or later topic within their ditabase <dita> (still plenty separate documents), while nowadays Oxygen appears to restrict itself to the first topic. Is there any flag or setting to keep the old behaviour?

Thanks,
Dirk

Post by **Radu** » Wed Aug 30, 2023 7:40 am

Hi Dirk,

The DITA standard has always stated that:
https://www.oxygenxml.com/dita/1.3/spec ... ssing.html

For references to topics, maps, and non-DITA resources, the value of the @keyref attribute is simply a key name (for example, keyref="topic-key").

For references to non-topic elements within topics, the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element (for example, keyref="topic-key/some-element-id".)

So a conkeyref like this "keyName/someID" can only indicate to a non-topic element like a paragraph.

If you want to conkeyref to a topic inside a <dita> container you would need to create a specific key pointing to it like:

Code: Select all

<keydef href="composite.dita#innerTopic2" keys="innerTopic2"/>

Code: Select all

<keydef href="composite.dita#innerTopic3" keys="innerTopic3"/>

Indeed Oxygen used to be more relaxed when resolving conkeyrefs in the Author visual editor mode, probably at some point about 3-4 years ago we changed it to do things by the book, according to the specification. We do not have a setting for controlling this because we did the right thing by obeying the specification.
The publishing may also be sometimes more relaxed than the specification, I added some time ago an issue for it as well but it has not been implemented:
https://github.com/dita-ot/dita-ot/issues/2816

In my opinion you should adjust your DITA XML content to adhere to the specification.

Regards,
Radu

jdbecker · Post by **jdbecker** » Wed Aug 30, 2023 12:26 pm

Hi Radu,

I'm speaking about the case of non-topic elements, and if that matters, conkeyref rather than keyref to them.

point into the second or later topic

For the key name part of the conkeyref, let's have a keydef point to the root of the composite.
Your 25.1 "Edit Key Definition Properties" Editor is fine for that, it still has an entry "Composite root - dita" in the "ID" dropdown.

Code: Select all

 <keydef href="composite.dita" keys="composite"/>

For below ditabase file, the title in the reference//example, which btw was inserted with the 25.1 conkeyref picker again without complaints, results in the error message "[Document]:Element ID 'ti2' not found in topic with ID 'about'."
I know I could move that particular title into the first topic id="about", but this is just an example of the problem to keep the quote short.

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita>
	<topic id="about">
		<title id="ti1">Title 1</title>
		<body>
			<p>What's below</p>
		</body>
		<related-links id="rl1"/>
	</topic>
	<concept id="second">
		<title id="ti2">Title 2</title>
		<related-links id="rl2"/>
	</concept>
	<reference id="third">
		<title id="ti3">Title 3</title>
		<refbody>
			<example>
				<title conkeyref="composite/ti2"/>
			</example>
		</refbody>
	</reference>
</dita>

jdbecker · Post by **jdbecker** » Wed Aug 30, 2023 3:43 pm

Hi Radu,
as you refer to the spec, the relevant topic would be
http://docs.oasis-open.org/dita/v1.2/os ... ibute.html
http://docs.oasis-open.org/dita/dita/v1 ... fattribute

For content references from map elements to map elements or topic elements to topic elements, the value of the conkeyref attribute is a key name, where the key must be bound to a map element (for references from map elements) or a topic element (for references from topic elements). For all other elements, the value of the conkeyref attribute is a key name, an optional solidus ("/"), and the ID of the target element, where the key name must be bound to the map or topic that contains the topic element.

Likely with a typo, that final "topic element" would better read "target element".

My bad that I took what the ancient Oxygen accepted.

So shouldn't a strict DITA processor treat a keydef referring to a ditabase without specified topic ID as non-topic resource? The conkeyref UI would not even list the key, also the conkeyref resolver would not refer to an arbitrary (the first) topic within.
OTOH given your current fallback to take the first topic, the conkeyref UI should only offer contained target element IDs.

Btw, thanks for the link to the glossentry issue, it made me reconsider any plans to move my terms to a glossary.

Regards,
Dirk

Post by **Radu** » Wed Aug 30, 2023 4:26 pm

Hello Dirk,

Please see some remarks below:

My bad that I took what the ancient Oxygen accepted.

We should have probably been more restrictive from the start. The DITA Open Toolkit publishing engine is still more flexible than the specification states so as an editing tool we are somewhere in the middle, should be accept keyref constructs considered illegal by the specs but which work in the published output? And we finally took the decision to adhere more to the specs.

So shouldn't a strict DITA processor treat a keydef referring to a ditabase without specified topic ID as non-topic resource? The conkeyref UI would not even list the key, also the conkeyref resolver would not refer to an arbitrary (the first) topic within.
OTOH given your current fallback to take the first topic, the conkeyref UI should only offer contained target element IDs.

I'm not sure if I read in the specs (but I cannot find right now where) or from discussion with the people who wrote the specs, the idea was that when referring to a DITA composite file with a key the referenced topic is the first topic in the composite container.
And I agree our actions which allow inserting a conkeyref or a cross ref to such a key should take care to avoid listing ids from any other topic inside the composite. I will add an internal issue for this.

Btw, thanks for the link to the glossentry issue, it made me reconsider any plans to move my terms to a glossary.

You would basically need a key defined for each glossentry reference you would make later on. Because a glossentry is a "topic" type.

Regards,
Radu

conkeyref broken referring to composite

conkeyref broken referring to composite

Re: conkeyref broken referring to composite

Re: conkeyref broken referring to composite

Re: conkeyref broken referring to composite

Re: conkeyref broken referring to composite