keydefs cannot be found (newbie question)

[palun]

Hi all,
I used to have my keydefs directly in my bookmap, inside the frontmatter element. This worked fine, but it wasn't very elegant. So I decided to move all keydefs into a separate map and then simply add a reference to this map, like so:

Code: Select all

<mapref href="../common/my_keys.ditamap"/>

The problem now is that the keydefs cannot be found any more! In Author, I get this message:

Description: Key definition 'ProductName' not found in the DITA Map. Keys are gathered from the root map: my_bookmap.ditamap.

Does this mean I have to update all my key references, in all my topics, with the path to the newly created keys map?! (Answer is probably obvious, but as I said, I'm a DITA newbie.)

Thanks!
/ulf (using Author 19.1)

[Radu]

Hi,

Where exactly did you add that <mapref> in the bookmap?
It's hard to say what went wrong, could you maybe post some sample DITA content with how the mapref looks like and in what context you added it?
Also make sure that if you have profiling conditions applied (a DITAVAL filter for example) that the mapref is not referenced in a context which is excluded by some DITAVAL condition.

Regards,
Radu

[palun]

Hi Radu,

I added the mapref last in frontmatter (same place my original keydefs were). Looks like this:

Code: Select all

<frontmatter>

        <topicref format="ditaval" href="bm_GENtrace%20Operator%20Guide.ditaval" print="no" scope="peer" toc="no">

            <topicmeta>

                <navtitle>DITAVAL file</navtitle>

            </topicmeta>

        </topicref>

        <preface/>

        <notices/>

        <booklists>

            <toc/>

        </booklists>

        <mapref href="../common/my_keys.ditamap"/>

    </frontmatter>

(There's probably nothing wrong with the path - the map can be opened via "Open file at cursor" in Author.)

The keydef map looks like this:

Code: Select all

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd">

<map>

    <title>GENtrace keys</title>

    <keydef keys="ProductName">

        <topicmeta>

            <keywords>

                <keyword>GENtrace</keyword>

            </keywords>

        </topicmeta>

    </keydef>

    .

    .

And a keyref may look like this:

Code: Select all

<p>You must have attended the <ph keyref="ProductName"/> operator training.</p>

/ulf

[Radu]

Hi,

The only problem that I see is that the reference:

Code: Select all

  <mapref href="../common/my_keys.ditamap"/>

is to a DITA Map outside of the folder where the main published DITA Map is located. The publishing engine has always had problems when this is done, there is a special transformation scenario parameter which can be set to overcome this:

https://www.oxygenxml.com/doc/versions/ ... -refs.html

Otherwise, in my tests, having the "my_keys.ditamap" in the same folder as the main DITA Map I could not find any problem using keys from the submap.
As a non-related observation, I see you have a reference to a DITAVAL file in the master DITA Map. What is it for?

Regards,
Radu

[palun]

Radu,

Thank you for your answer!

Reg. keydefs: OK I understand. It's a shortcoming (bug?) in DITA OT. But, just to be sure I understand completely, here's an example:

Let's say I have a folder structure like companies/products/manuals and I want to use company- or product-related keyrefs in one of the manuals. How do I do that if I cannot refer to keys in underlying folders...?! [Should I just abandon the folder structure all together, and put all files in one single, (very crowded) folder?]

BTW: You say it's the publishing engine that may have problems with keydefs in underlying folders. But I get these problems when validating. (I haven't published anything yet...)

Reg. the DITAVAL file: I haven't started looking at/learning about ditaval yet. I just assumed there should be (normally is) a ditaval file associated with each document (manual). (Your comment makes me suspect I was wrong )

Cheers,
/ulf

[Radu]

Hi,

So:

How do I do that if I cannot refer to keys in underlying folders...?! [Should I just abandon the folder structure all together, and put all files in one single, (very crowded) folder?]

You can refer to DITA submaps placed in subfolders of the main folder (where the main published DITA Map is located). But there are problems when you refer to maps/topics located in folders which are not subfolders of the main folder.

BTW: You say it's the publishing engine that may have problems with keydefs in underlying folders. But I get these problems when validating. (I haven't published anything yet...)

If you have validation problems, if you open the main DITA Map in the DITA Maps Manager view, use the "Validate and check for completeness" action and you obtain errors related to various keys not being found, then I suspect there is another problem with your project. But without having a sample project to test on my side I cannot give you more details. If you want to provide a sample DITA project you can directly email us (support@oxygenxml.com).

Reg. the DITAVAL file: I haven't started looking at/learning about ditaval yet. I just assumed there should be (normally is) a ditaval file associated with each document (manual). (Your comment makes me suspect I was wrong )

Usually the DITAVAL is not referenced in the DITA Map. If you duplicate and edit the transformation scenario you use for publishing, it has a "Filters" tab where you can specify a reference to a DITAVAL file.
We have a page with lots of videos about using Oxygen:
https://www.oxygenxml.com/videos.html

and you can search in it for "DITA profiling".

Regards,
Radu