How flag circular references in DITA topics?

[jackhameister]

Hello Oxygen engineers,
We are using Oxygen Author v22.1 64-bit with a DITA 1.3 XML content set. A user created a bookmap that referenced a topic that had a circular reference in it to that same topic. For example, the topic’s file name was,...

Code: Select all

t_MyTopicWithXrefToSameTopic.dita

... and the cross reference’s (xref’s) href value was this,...

Code: Select all

<xref href="t_MyTopicWithXrefToSameTopic.dita"/>

Now, when she published that topic’s bookmap to Oxygen Author’s default Webhelp Responsive or PDF transformation scenarios, the editor does not throw up an error, as that xref is valid DITA XML. Also, doing a completeness check on the bookmap in the DITA Maps Manager does not flag this circular xref in one of its referenced topics.

How can I find these circular references so that I can remove them before publishing? Would there be a Schematron solution for this issue, where I could add the .sch to the DITA Maps Manager’s “Schematron Additional Schematron checks” field? If so, do you have an example of the .sch that I could use?

Thanks.

[Radu]

Hi Jack,

These are valid self-links and as you say they end up being valid links even in the published output.
Such links can also be written like this:

Code: Select all

<xref href="#."/>

So I do not see this as a potential problem to report in the "Validate and check for completess" dialog. Maybe in a longer topic somewhere near the bottom of the topic someone wants to link to the beginning of the same topic for some reason.

So yes I think a Schematron file like this could be built to report such problems:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
    xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
    <sch:pattern>
        <sch:rule context="xref">
            <sch:report test="tokenize(base-uri(), '/')[last()] = @href">Should not have a selfy link.</sch:report>
        </sch:rule>
    </sch:pattern>
</sch:schema>

You can either refer to it in the "Validate and check for completeness" configuration dialog or if you want to automatically check for this problem while editing create a DITA framework configuration extension which adds an extra validation stage:

https://blog.oxygenxml.com/topics/shari ... rules.html

Regards,
Radu

[jackhameister]

OK, great, thanks for the selfy Schematron. It works for that use case I described above, where the xref’s href value is the file name like this:

Code: Select all

<xref href="t_MyTopicWithXrefToSameTopic.dita"/>

But, we use a Content Management System (Astoria), and an xref’s href looks like this in a topic:

Code: Select all

<xref href="/astoria/_id_00000018WIA20772F20GYZ_t_MyTopicWithXrefToSameTopic.dita?lm=1666365186000" ast:aid="00000023WIG20772F202021GYZ" ast:anno="can"/>

And, your selfy Schematron does not work for that larger href value with database information in it. But, note the topic’s file name in the href value. Could your Schematron be adjusted to work for a value like that, where it parses out the file name from that larger href value to do pattern matching and reporting on?

Thanks much.

[Radu]

Hi,

Maybe something like this should work:

Code: Select all

<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
    xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
    <sch:pattern>
        <sch:rule context="xref">
            <sch:report test="ends-with(replace(@href, '\?lm=(.*)', ''), tokenize(base-uri(), '/')[last()])">Should not have a selfy link.</sch:report>
        </sch:rule>
    </sch:pattern>
</sch:schema>

so from the xref @href I remove the "?lm=..." part and then I only check that the entire @href value ends with the file name of the topic.

Regards,
Radu

[jackhameister]

That works!

Case closed.

Thanks much.