problem with rendering Webhelp using a DITA map that references DITA files in other locations

[surangamas]

Hi:

I was testing the Webhelp transformation with Oxygen yesterday, and came across a problem: if I create a DITA map file ( a bookmap file to be exact) that topic-references DITA files that are not in the same directory as the DITA map file, although Oxygen could still transform files to Webhelp, but when you click the topic from the dropdown menu in Webhelp (that is: the topic whose source file is located outside the DITA map directory), the link would not work. Yet if all the topic files are located in the same directory as the DITA map file, Oxygen would transform a flawless Webhelp output. Is it that I might not have followed the DITA best practice? Or is it a problem with Oxygen's webhelp output mechanism? If the problem is the former, then I would say isn't DITA map supposed to work that way - referencing topics that are located anywhere, and not limited to topics that are located in the same directory?

Just to give you an idea, here is a bare bone structure of my DITA map:

Code: Select all

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

<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">

<bookmap>

    <booktitle>

        <mainbooktitle>ditamap test</mainbooktitle>

        <booktitlealt class="- topic/ph bookmap/booktitlealt ">test</booktitlealt>

    </booktitle>

    <bookmeta>

        <authorinformation>

            <organizationinfo class="+ topic/data xnal-d/organizationinfo ">

                <namedetails class="+ topic/data xnal-d/namedetails ">

                    <organizationnamedetails/>

                </namedetails>

                <addressdetails class="+ topic/ph xnal-d/addressdetails "><thoroughfare

                        class="+ topic/ph xnal-d/thoroughfare "/><locality><localityname

                            class="+ topic/ph xnal-d/localityname "/></locality><administrativearea

                        class="+ topic/ph xnal-d/administrativearea "/><locality><postalcode

                            class="+ topic/ph xnal-d/postalcode "/></locality>

                    <country class="+ topic/ph xnal-d/country "/></addressdetails>

                <contactnumbers>

                    <contactnumber class="+ topic/data xnal-d/contactnumber "/>

                </contactnumbers>

            </organizationinfo>

        </authorinformation>

        <metadata>

            <prodinfo>

                <prodname></prodname>

                <vrmlist>

                    <vrm version="1.0"/>

                </vrmlist>

            </prodinfo>

        </metadata>

    </bookmeta>

    <frontmatter>

        <booklists>

            <toc/>

        </booklists>

    </frontmatter>

    <chapter>

        <topicref href="chapter.dita">

            <topicref href="chapter1.dita"/>

            <topicref

                href="../%my_dir%/1.dita"/>

            <topicref href="../%my_dir%/2.dita"/>

            <topicref href="../%my_dir%/3.dita"/>

            <topicref href="../%my_dir%/4.dita"/>

            <topicref href="../%my_dir%/5.dita"/>

            <topicref href="../%my_dir%/6.dita"/>

            <topicref href="../%my_dir%/7.dita"/>

        </topicref>

    </chapter>

    <backmatter>

        <booklists>

            <indexlist/>

            <figurelist/>

            <bibliolist/>

        </booklists>

    </backmatter>

</bookmap>

When Oxygen transformed these files to Webhelp, the links to 1.dita to 7.dita did not work, any input is appreciated.

[Costin]

Hello,

As you already figured out, this happens due to your file / folder hierarchy where your DITA Map (bookmap) refers resources from folders outside of the main DITA Map folder (the "basedir").
The problem is that not all your resources are located within the "basedir" directory like the DITA-OT assumes.
So this is neither related to bad practice, nor an oXygen specific issue, but it is related to the DITA-OT (the open toolkit which oXygen uses for DITA transformation scenarios), having some known issues occurring when there are references pointing to locations outside of the processed DITA Map directory.

However, this problem determined us to add a "fix.external.refs" parameter into our DITA Map -> WebHelp transformation scenarios. The parameter tells oXygen if it should try fixing such references in a temporary files folder, before the DITA Open Toolkit is invoked on the fixed references.
Therefore, to avoid this issue, you should edit the WebHelp transformation scenario and set the "fix.external.refs.com.oxygenxml" parameter to "true".

I hope this helps.

Best Regards,
Costin

[surangamas]

Hi Costin:

Setting "fix.external.refs.com.oxygenxml" did fix this problem, thank you for your help!

[surangamas]

I meant: setting "fix.external.refs.com.oxygenxml" to "true" did fix my problem, thanks again.

[surangamas]

Hi Costin:

Sorry this is a little off-topic, a quick question: where are the CSS files that control the look and feel of the Oxygen editor? I mean, let's say for Menucascade, if I want the font inside this element to show as green-color font on the editor screen (just for the sake of this discussion), where do I go about changing it? Thanks.

[Radu]

Hi,

The easiest way to find the CSSs where Oxygen styles various DITA XML elements is to select the element (or to place the caret directly inside it), right click and choose "Inspect Styles". The Styles Inspector should allow you to see all defined styles and open the CSSs at that particular location.
For example if you open the CSS:

OXYGEN_INSTALL_DIR\frameworks\dita\css\core\-domain-ui-d.css

you can add to it:

Code: Select all

*[class~="ui-d/menucascade"]{

    color:green;

}

Regards,
Radu

[surangamas]

Hi Radu:
Got it, thanks for the quick reply.