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

<oXygen/> general issues.
surangamas
Posts: 47

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

Thu May 19, 2016 5:39 pm

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
Posts: 365

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

Thu May 19, 2016 8:14 pm

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
Costin Sandoi
oXygen XML Editor and Author Support
surangamas
Posts: 47

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

Fri May 20, 2016 12:01 am

Hi Costin:

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

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

Fri May 20, 2016 12:02 am

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

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

Fri May 20, 2016 12:23 am

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
Posts: 5563

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

Fri May 20, 2016 8:28 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Return to “Other Issues”

Who is online

Users browsing this forum: No registered users and 1 guest