Errors caused by link to topic with xref in shortdesc

[robander]

Expected Behavior

When I have the following condition:

1. Topic contains <xref> to another topic xref-in-shortdesc.dita
2. The referenced topic has a short description, and that short description also contains an <xref> to finaltarget.dita
3. The xref inside that short description is missing link text or <desc>

The topicpull step ends up grabbing the short description from the middle file xref-in-shortdesc.dita, putting that in a variable, and then processing the variable. The result is that the <xref> to finaltarget.dita is processed again but in the context of that variable, which causes the processor to look for it in our XSLT directory, and ends with errors. Happens with both preprocess and preprocess2, here is the error log from preprocess:

C:\DCS\test\apiref>\dita-ot\dita-ot-3.1.2\bin\dita -i in.ditamap -f html5
[topicpull] I/O error reported by XML parser processing file:/C:/DITA-OT/dita-ot-3.1.2/xsl/preprocess/finaltarget.dita: C:\DITA-OT\dita-ot-3.1.2\xsl\preprocess\finaltarget.dita (The system cannot find the file specified.)
[topicpull] file:/C:/DCS/test/apiref/xref-in-shortdesc.dita:5:68: [DOTX031E][ERROR]: The file finaltarget.dita is not available to resolve link information.

This worked at some point in the past (at least, the xref inside shortdesc was processed to get text) but could have been broken as far back as 1.8 -- the text was pulled and no errors were thrown.

Actual Behavior

Errors appear as shown above. preprocess2 has the same issue:

C:\DCS\test\apiref>\dita-ot\dita-ot-3.1.2\bin\dita -i in.ditamap -f pdf
[topicpull] I/O error reported by XML parser processing file:/C:/DITA-OT/dita-ot-3.1.2/xsl/preprocess/dd3f451dd1448c00ddc872728d9573466227ad65.dita: C:\DITA-OT\dita-ot-3.1.2\xsl\preprocess\dd3f451dd1448c00ddc872728d9573466227ad65.dita (Thesystem cannot find the file specified.)
[topicpull] file:/C:/DCS/test/apiref/xref-in-shortdesc.dita:5:68: [DOTX031E][ERROR]: The file dd3f451dd1448c00ddc872728d9573466227ad65.dita is not available toresolve link information.

Possible Solution

Once everything is in the variable context, I'm not sure how easy it is to get away from this. Most likely, the only way around it is to update the copy-shortdesc mode so that when it finds an xref, it actually goes to process the file, but I'm not sure yet.

Steps to Reproduce

Samples attached:
xrefshortdesc.zip

Copy of the error message, log file or stack trace

Shown above

Environment

• DITA-OT version: 3.1.2
• Operating system and version: Windows
• How did you run DITA-OT? dita command
• Transformation type: html5 and pdf

[stefan-jung]

This is probably also related to DITA-OT 2.5.x and to other linking elements like <term> and so on. I remember I went crazy because the error message is absolutely useless for authors.

To other crazy people: If you like to avoid problems related to this bug, you may want to use a Schematron rule to prohibit links completely in <shortdesc>.

<sch:pattern id="no-linking-in-shortdesc" see="https://github.com/dita-ot/dita-ot/issues/3078">
    <sch:rule context="*[contains(@class, ' topic/shortdesc ')]">
        <sch:report test="*[@keyref] or *[contains(@href, '.dita')]">
            Do not link to other topics in &lt;shortdesc&gt;. This does not work.
        </sch:report>
    </sch:rule>
</sch:pattern>

[raducoravu]

+1 Same problem when generating the PDF. Similar to your case, console output shows that the target file is searched in a very strange location, instead of being searched in the transformation temporary files folder, it's searched in the place where the XSLT is located:

[topicpull] I/O error reported by XML parser processing file:/D:/projects/oxygen-dita-ot-3.x/xsl/preprocess/bdc88ce59a00abe01b1103acb5739f573e7a34d5.dita

[raducoravu]

Somewhere in the "topicpullImpl.xsl" there is a document() function using the relative reference to the file. Somehow the "$linkElement" which should be used to retrieve a base URI is a node set which is not part of a document.

[raducoravu]

BTW, attached sample project is incomplete, it's missing a "xrefshortdesc\haslink.dita" attaching a complete sample:
xrefshortdesc.zip

[robander]

Interesting timing, I just had somebody run into this again yesterday (completely different author / set of content, but same message from topicpull trying to open a topic in the xsl/ directory).

[raducoravu]

Think I found the problem, in "topicpullImpl.xsl" there is a variable called "shortdesc" which gets computed and there is an apply-templates on it. But variables no longer have base-uri().

[robander]

Yes - that sounds right. Over the last few years we've had more pieces of code that put elements into variables, and when working on content in the variable the context is lost.

[raducoravu]

A possible fix would be to pass an extra parameter as a tunneled parameter:

        <xsl:apply-templates select="$shortdesc">
          <xsl:with-param name="baseContextElement" select="." tunnel="yes"/>
        </xsl:apply-templates>

then pass this extra parameter through the "dita-ot:getTargetElement" function to the "dita-ot:getTargetDoc" function where the "baseContextElement" if available would be used instead of the "$linkElement" parameter in the document() function.
The fix seems to be working on my side but as I do not know how to create an automatic test for this I will just leave this as a suggestion.

[raducoravu]

One more problem is that there is a "move-meta-entries" stage which copies metadata (like shortdesc) from topics to maps. So this stage copies the "shortdesc" from the topic to the map. But the "topicpull" stage is responsible of enriching the shortdesc in the DITA topic to also expand xrefs.
So ideally the "topicpull" should be done before the "move-meta-entries" if we also want in the DITA Map generated in the temporary files folder to have the shortdesc with the xref properly expanded.

[raducoravu]

The question maybe for @jelovirt would be what possible side effects would be if in the build file "plugins\org.dita.base\build_preprocess.xml" in the ""preprocess"" target we would move the call to the "topicpull" stage before the call to the "move-meta-entries" stage.

[robander]

I don't think we want to do that, especially with preprocess2 moving all of map processing early, it's not a great idea to move one of the all-topic steps before one of the map steps. (I know these steps switched places in the first couple years of DITA-OT but cannot remember all of the reasons that they ended up in this order.)

[raducoravu]

As a general overview of this issue, there are two aspects:

1. Links from topics to a topic containing a shortdesc with an xref.
   This can be clearly fixed in the XSLTs as we discussed above.
2. The "move-meta-entries" ANT target which copies the "shortdesc" from the topic to the DITA Map would need to be done after the topic's shortdesc is properly expanded by the "topicpull" stage or it would need to duplicate some code from the "topicpull" XSLTs to expand the computed shortdescs.
   The "shortdesc" copied from the topic to the DITA Map is most probably not used for anything in the plain HTML5 output but for example in our Oxygen WebHelp output we display the "shortdesc" of the topic in the table of contents. The HTML5 output could use it as well for tooltips in the table of contents, for setting a @title attribute to all references in the TOC.

[raducoravu]

👍 One more report:
https://www.oxygenxml.com/forum/viewtopic.php?p=53982#p53982

again a short description contains an xref, and at some point in the [topicpull] stage we get this error in the console view (using DITA OT 3.3.1):

         DITA-OT3.x\plugins\org.dita.base\xsl\preprocess\process_edit.dita (The system cannot find the file specified)

so the "process_edit.dita" is searched for in the wrong folder.

[robander]

@raducoravu do you still have the code set up that used $baseContextElement to fix this? I tried to do something like that just now and it didn't seem to work, so I think I missed something. If you could make a pull request with the code change, and allow maintainer edits, I could verify it and then add a test case to the same pull request?

[raducoravu]

I will do this on Monday

[raducoravu]

@robander added my changes as a possible pull request, they don't need to be integrated as they are if you have a better solution, it's just for you to know what I did on my side.
As I said before there are two aspects for the problem and the XSLT changes fix only the first aspect.

[raducoravu]

👍 We had another end user asking for a fix for this on DITA OT 2.5.4.

[raducoravu]

Attaching the end user's samples for which html5 publishing still reports errors like "The file topic_a.dita is not available to resolve link information." even with my fix applied.
sample_xref_in_shortdesc.zip
In those samples there are three DITA topics, the short description for each topic has an xref to the title of the next topic in a circular fashion with the shortdesc of the last topic having an xref to the title of the first topic.
The reported errors seem benign as the tooltips properly resolve on each link in the shortdesc of each topic.

Why are the errors still reported?
So for expanding the reference from topic A's shortdesc to topic B the topicpull XSLT code finds the xref to topic B and loads topic B in a document. Then it applies the template which resolve topic B's title but the XSLT processing also tries to resolve topic B's shortdesc. Because it tries to resolve topic B's shortdesc, it goes into that shortdesc, finds a reference to topic C, tries to expand that and so on.
As in the end topic B's title will appear as a tooltip when hovering over the xref to it, resolving its shortdesc is not quite necessary but the information does appear in the processed topic so possibly it might be used by some customizers.

I give up :(

[raducoravu]

Probably one more problem. Again, topic is searched for in the wrong folder:
https://www.oxygenxml.com/forum/post56095.html#p56082

[stale]

This issue has been automatically marked as stale because it has not been updated recently. It will be closed soon if no further activity occurs. Thank you for your contributions.