Page 1 of 1

When do XREFs style as broken?

Posted: Fri Jun 03, 2016 3:00 am
by ArbitraryName
I am noticing some strange behavior in XREF validation inside of oXygen. (Note I am working with internal references)

It seems that some complex, large topics, which have broken XREFs style those as red saying "REFERENCED ID PATH....NOT VALID". To me, this is a great feature.

However, I was trying to show this to another user, and I made a small topic with a valid and invalid XREF and the XREF was not styled broken. If I clicked the link icon, I would get the validation message back "Reference: ourId/dead was not found." But the XREF still stays underlined and appearing styled valid.

Is there something I am missing on how the XREF gets styled valid/invalid?

XML below for my broken example...

Code: Select all

<learningContent id="ourId">
<title />
<shortdesc />
<p id="horses"> gets highlighted when link is clicked</p>
<p />
<p />
<p />
<p />
<p />
<xref href="#ourId/dead">still shows good</xref>
<p id="cheese">
<xref href="#ourId/horses">Good, and shows good</xref>

Re: When do XREFs style as broken?

Posted: Fri Jun 03, 2016 9:01 am
by Radu

Thanks for the sample. Usually when editing a topic and working with links you receive validation information from two places:

1) Automatic validation.
Automatic validation adds error markers under the xrefs which are considered to have various problems. Automatic validation never checks other referenced topics (because it needs to be fast, it is performed every time you type something).
For example if you have a reference like this:

Code: Select all

<xref href="notExisting.dita#topicID/elementID"/>
automatic validation will check and report if the referenced file exists on disk. But if you have a reference to an existing topic:

Code: Select all

<xref href="existing.dita#topicID/elementID"/>
automatic validation will not check if the topic and element IDs actually exist because it would need to actually parse that referenced topic and it would not be fast anymore.

2) Whenever you have an empty <xref> element Oxygen tries to compute the title of the referenced target element. It does this because when you edit in the Author visual editing mode you want the content to appear as closest as possible to the published output.
For this, Oxygen tries to parse the referenced topic (in your case it's the same topic) and if it cannot find the target it will report the error in-line in the document. This is the validation you are referring to.
In the case of your sample document, the xref's are not empty, they have text inside them so Oxygen no longer tries to find a target element title for them so it does not report the error. So if in your example you remove the text from the xrefs, Oxygen will try to retrieve text from the target element and report problems in-line in the document.


Re: When do XREFs style as broken?

Posted: Fri Jun 03, 2016 6:55 pm
by ArbitraryName
Thanks Radu.

Is there a way for us to kick off that full validation? Like could we create a button in our framework that did xref validation?


Re: When do XREFs style as broken?

Posted: Mon Jun 06, 2016 11:05 am
by Radu
Hi Wes,

Yes, this is possible.
Whenever automatic validation is done for DITA, besides various custom checks by default there is also a Schematron schema which gets invoked and it is located in:


There is also a Schematron schema which does full link checks and it is located in:


You have two possibilities (the first one is easier and the other is more elegant):

1) Open the "dita-1.2-for-xslt2-links-checker.sch" and copy the entire "pattern" element that if defines, then open the dita-1.2-for-xslt2-mandatory.sch and paste that pattern element inside it. This should then allow automatic validation to also apply this pattern which actually parses and checks the referenced topics.

2) In the Oxygen Preferences->"Document Type Association" page there is the default DITA framework configuration defined. You can extend it and in the "Validation" tab you can edit the default DITA validation scenario and add another module to it which does validation according to the dita-1.2-for-xslt2-links-checker.sch. When you define that extra module you can also decide if you want it to be applied on automatic validation or only on manual validation (when you manually click the validate button).
More about how you can share a framework extension with others: ... aring.html