Oxygen XML Forum

Posted: **Tue Dec 02, 2025 6:32 pm**

Hello, I've been a long-time user of Oxygen 26 and now in the process of switching to 28 due to the lmns support.
However, I'm experiencing errors with content that has been working perfectly in Oxygen 26 with no errors. I guess these are some new requirements of a newer DITA-OT, but no matter what I do to search for a solution, all the solutions that I was able to find and test (useless ChatGPT and such) simply give more errors, so I need human support.

1. In my main DitaMap, I have the fragment for a glossary which is in the navigation:

Code: Select all

<topichead chunk="to-content" id="glossary">
        <topicmeta>
            <navtitle>Glossary</navtitle>
        </topicmeta>
        <topicref href="topics/glossary/glossary.ditamap" format="ditamap"/>
    </topichead>

The glossary map file, in the correct location as stated above (topics/glossary/glossary.ditamap), is:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Glossary</title>
    <topicref href="dot1x.dita" keys="dot1x"/>
(...)
</map>

(tried using glossref instead of topicref, same problem)

All the *.dita files for the glossary are in the same directory, for example, topics/glossary/dot1x.dita:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary Entry//EN" "glossentry.dtd">
<glossentry id="dot1x">
    <glossterm>802.1X</glossterm>
    <glossdef><p>Description</p></glossdef>
    <glossBody>
        <glossAlt>
            <note>In spoken language, 802.1X is often pronounced as “dot-one-ex”.</note>
        </glossAlt>
    </glossBody>
</glossentry>

As a result of publishing to webhelp, I get the following errors for all references to <term keyref="glossaryterm">:

[DOTX058W]: No glossary entry found for the 'dot1x' key on the <term> element. Check display text and hover text for terms and abbreviations.

However, upon transformation, the glossary works correctly, and when hovering over the term in other files, the hover contains the description so the error is irrelevant.

How can I get rid of these errors please?

What I also tried and failed:
- getting rid of the extra ditamap and including all topics as topicref in the main dita

Posted: **Wed Dec 03, 2025 12:09 pm**

Hello,

How did you define the "glossaryterm" key used in <term keyref="glossaryterm">? Are you using other elements similar to <term> with the same keyref? (e.g. abbreviated-form)
I've tested defining <keydef keys="glossaryterm" href="topics/glossary/dot1x.dita#dot1x"/> and the output is generated without any error in <oXygen/> XML Editor 28.0, build 2025112606.
You can also try to run the Validate and Check for Completeness tool available in the DITA Maps Manager to see if you don't have duplicate keys.

Regards,
Julien

Posted: **Wed Dec 03, 2025 3:16 pm**

Thanks for the reply, Julien!
I never used <keydef> when using Oxygen 26. It was working perfectly as-is.
I tried switching from <topicref> in my glossary.ditamap to <keydef> instead, as you suggested, and then I get tons of other errors:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Glossary</title>
    <keydef href="dot1x.dita#dot1x" keys="dot1x"/>
(...)

[DOTX061W]: The @href attribute value 'dot1x' contains a fragment identifier, but it does not reference a topic element. The @href attribute on a <topicref> element should only reference topic-level elements.
[DOTX023W]: Unable to retrieve navtitle from target: 'glossary.dita#dot1x'.
[DOTX027W]: Unable to retrieve linktext from target: 'glossary.dita#dot1x'.

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Glossary</title>
    <keydef href="dot1x.dita" keys="dot1x"/>
(...)

[DOTX061W]: The @href attribute value 'dot1x' contains a fragment identifier, but it does not reference a topic element. The @href attribute on a <topicref> element should only reference topic-level elements.
[DOTX023W]: Unable to retrieve navtitle from target: 'glossary.dita#dot1x'.
[DOTX027W]: Unable to retrieve linktext from target: 'glossary.dita#dot1x'.

Then, to be sure there are no duplicates, I changed all these to term_glossaryterm e.g. term_dot1x. And I tried both a keyref and a topicref.

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>Glossary</title>
    <keydef keys="term_dot1x" href="dot1x.dita" format="dita"/>
    <topicref href="dot1x.dita"/>
(...)

[DOTX058W]: No glossary entry found for the 'term_dot1x' key on the <term> element. Check display text and hover text for terms and abbreviations.

I do not understand what changed and why it is so, but I may have to consider not upgrading to 28 and staying with 26 instead then. Well, at least the transformation is successful and everything works as before, only I get this warning spam every single time...

Posted: **Thu Dec 04, 2025 11:22 am**

Hello,

Do you have the possibility to send us a small sample where we can reproduce the issue at support@oxygenxml.com?
Have you tried to run the Validate and Check for Completeness tool available in the DITA Maps Manager to see if you don't have duplicate keys?

Regards,
Julien

Posted: **Thu Dec 04, 2025 1:13 pm**

Hi, Julien, I have posted the code that's causing the problem, I can send them to you as files as well and possibly do a small sample as a completely separate project and see if that also causes the same problem.
As mentioned in the previous reply, I ran the check and there are duplicate keys elsewhere but none in the glossary, and to be sure, I renamed all the glossary keys to be term_glossaryterm which you can see in my answer.

EDIT: I've created the sample but without a publishing template, and I have no errors with the sample. Could a publishing template be causing this, because it's been brought over from oxygen 26?

EDIT2: I also ran the transformation to WebHelp Responsive directly on the ditamap and there are no errors! So this must be related to the publishing template. Is there anything I need to do with the publishing template when migrating from Oxygen 26 to 28?

Using this as opt:

Code: Select all

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<publishing-template>
    <name>User Guide</name>
    <description/>
    <webhelp>
        <preview-image file="light-tree.png"/>
        <html-fragments>
            <fragment placeholder="webhelp.fragment.after.top_menu" file="html-fragments/header.xml"/>
            <fragment placeholder="webhelp.fragment.footer" file="html-fragments/footer.xml"/>
            <fragment placeholder="webhelp.fragment.head" file="html-fragments/head.xml"/>
        </html-fragments>
        <parameters>
            <parameter name="webhelp.show.main.page.tiles" value="no"/>
            <parameter name="webhelp.show.main.page.toc" value="yes"/>
            <parameter name="webhelp.top.menu.depth" value="3"/>
            <parameter name="args.copycss" value="yes"/>
            <parameter name="args.figurelink.style" value="TITLE"/>
            <parameter name="args.tablelink.style" value="TITLE"/>
            <parameter name="clean.output" value="yes"/>
            <parameter name="force-unique" value="true"/>
            <parameter name="webhelp.custom.resources" value="params/webhelp.custom.resources/files" type="filePath"/>
            <parameter name="webhelp.show.top.menu" value="no"/>
            <parameter name="webhelp.sitemap.base.url" value="https://our-url.com/"/>
            <parameter name="webhelp.google.search.script" value="html-fragments/googlecse.html" type="filePath"/>
            <parameter name="webhelp.google.search.results" value="html-fragments/googlecseresults.html" type="filePath"/>
            <parameter name="webhelp.enable.ai.friendly" value="yes"/>
        </parameters>
        <resources>
            <css file="light.css"/>
            <css file="params/args.css/custom.css"/>
            <logo file="images/logo.png" target-url="https://our-main-url/"/>
            <favicon file="images/favicon.png"/>
        </resources>
        <online-preview-url>https://www.oxygenxml.com/samples/DITA-WebHelp-Responsive/tree/light/</online-preview-url>
        <tags>
            <tag type="layout">tree</tag>
            <tag type="color">gray</tag>
            <tag type="color">light</tag>
        </tags>
        <xslt>
            <extension file="xsl/metadata.xsl" id="com.oxygenxml.webhelp.xsl.dita2webhelp"/>
            <extension file="xsl/metadata-main.xsl" id="com.oxygenxml.webhelp.xsl.createMainPage"/>
        </xslt>
    </webhelp>
</publishing-template>

Posted: **Fri Dec 05, 2025 6:44 pm**

Hi,

The issue is caused by the "webhelp.enable.ai.friendly" parameter from the OPT file, this tells the engine to generate additional files, including companion Markdown files, the DOTX058W warning is thrown during the DITA to Markdown processing.
I've reproduced the problem and added an issue on DITA-OT part: https://github.com/jelovirt/org.lwdita/issues/243
From what I've tested this warning isn't a big issue and the Markdown file is correctly generated.

When a fix will be available for this warning, I will notify this thread.

Regards,
Julien

Posted: **Fri Dec 05, 2025 7:19 pm**

Thank you! Yes, it's more of an annoyance than a problem at the moment but looking forward to the fix nevertheless so I don't miss out on more important messages.

Posted: **Mon Jan 12, 2026 9:42 am**

Hello, is there any progress on this fix, please?...
The huge list of false warnings generated makes it more likely to not notice an actual error in between these...
Perhaps if this is a DITA-OT issue, and thus a fix cannot be expected in any sensible time, some kind of log filtering could be applied to get rid of this error in the transformation output, please?...

Posted: **Thu Jan 15, 2026 11:08 am**

Hello,

We've already implemented the fix in the lightweight DITA plugin on our end. If you’d like to test it, feel free to reach out to us at support@oxygenxml.com. We can provide you with a beta version of the Oxygen Publishing Engine so you can verify whether the warning persists.

Regards,
Julien

Oxygen XML Forum

DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)

Re: DITA OT errors DOTX058W in Oxygen 28 (none in Oxygen 26)