Book validation follows cross-book @conref into target book content

chrispitude
Posts: 328
Joined: Thu May 02, 2019 2:32 pm

Book validation follows cross-book @conref into target book content

Post by chrispitude » Fri Dec 04, 2020 11:08 pm

Hi all,

Each of our books has its own key scope. We create crossbook links using scoped keyrefs, and we reuse content across books using scoped conkeyrefs.

However, I noticed something interesting. If a writer accidentally uses a cross-book @conref to reuse a single element from another book topic file:

Code: Select all

<p conref="peer_topic_2.dita#peer_topic_2/reuse_me"/>
then "Validate and check for completeness" in the current book issues missing-key errors for any key references in any content in the @conref'ed file, whether it was used or unused by the @conref. But if we use a @conkeyref instead:

Code: Select all

<p conkeyref="peer_map.peer_topic_2/reuse_me"/>
then book validation doesn't complain.

Is this expected behavior? I can educate my writers to use @conkeyref for cross-book links, but I figured I'd ask here if the @conref behavior is expected or a bug. You can reproduce the behavior in the attached testcase as follows:

1. Open the OPENME1.xpr project file.
2. Open the OPENME2.ditamap map file.
3. Run "Validate and check for completeness" and note the missing keys for topic1 and topic3 from topic2.dita (the @conref target).
4. If you comment out the <p @conref> element in topic.dita, the validation errors go away.

oxygen_validate_scope.zip
(3.55 KiB) Downloaded 27 times

chrispitude
Posts: 328
Joined: Thu May 02, 2019 2:32 pm

Re: Book validation follows cross-book @conref into target book content

Post by chrispitude » Fri Dec 04, 2020 11:48 pm

Rereading my own post, I'm thinking that maybe a @conkeyref pulls the target topic into a scoped context (thus allowing keys in that file to resolve), whereas a @conref pulls the target topic into the current book's context instead?

chrispitude
Posts: 328
Joined: Thu May 02, 2019 2:32 pm

Re: Book validation follows cross-book @conref into target book content

Post by chrispitude » Sat Dec 05, 2020 12:11 am

Actually, I think I disproved my own theory of key scope by experimentation. In the following modified testcase:

oxygen_validate_scope_v2.zip
(3.63 KiB) Downloaded 31 times

I added a broken <xref keyref> inside topic_2.dita. Even so, the @conkeyref scenario does not report it as a missing key definition.

There seems to be a (probably intentional?) difference in Oxygen's validation behavior, where @conref steps into the target file and validates its contents, and @conkeyref does not. Or something like that.

Radu
Posts: 7538
Joined: Fri Jul 09, 2004 5:18 pm

Re: Book validation follows cross-book @conref into target book content

Post by Radu » Mon Dec 07, 2020 12:15 pm

Hi Chris,

When the Oxygen Validate and Check for Completeness encounters that conkeyref it already has enough information to detect that it points to a topic defined in a peer DITA Map. We took the decision back in Oxygen 18.1 to not follow such references at all, otherwise there would have been no separation between the different publications when validating, Oxygen would have crawled through that peer reference to other references inside the other book map and start reporting problems in the other publication which in a way is separate. The validation time would have also increased.
When Oxygen encounters the conref it considers the conreffed topic as part of the current publication so it parses it entirely and reports what problem it can find on it.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Post Reply