DITA and XMetaL Discussion

  • kenfesta

    Broken index links

    Participants 2
    Replies 3
    Last Activity 10 years, 4 months ago

    Our webhelp generated in Xmetal 6 was working fine.

    However, now that we've switched to XM7, the index links are broken.

    The index link seems to insert a copy of the one of the folders…

    Here is the broken link from the index:


    When I search for the topic, it comes up fine…


    Is this a keyspace problem? An OT problem? An Xmetal problem? Any pointers for framing this investigation would be good.



    Reply to: Broken index links

    I've since figured out where this is breaking. If you link to a file that is outside the current folder structure, then it breaks all of the index link(s) in the manner shown above. This can be a link to a graphic, a topic reference from a ditamap, a conref, pretty much anything.

    In the rest of the webhelp output, everything works fine (hyperlinks, images, TOCs, etc).

    Has anyone else experienced this?



    Reply to: Broken index links

    OK, this mystery is still not completely solved. One of the problems stems from the fact that our implementation probably uses keywords in a way that XMetal doesn't handle (and I can understand that). The other problem, though, is that we had our ditamaps in a folder that was parallel to all of our “chapter-level” folders. We're not sure exactly where the error is introduced, but it can be fixed as described below. If you don't use keywords in this way, and are having a problem with one extra folder in your broken index path, you'd either want to move your ditamaps to a parent folder, or modify webhelp.js as described below, except that you'd used one “../” instead of two. More complete explanation as follows:

    Broken Index Links
    The Xmetal webhelp index breaks under 2 separate conditions (that we know of). These conditions each result in a separate (extra, link-breaking) folder to the URL that the index tries to access in the output. One condition is caused by our keyword implementation, and the other is caused by ditamaps that are in folders parallel to the other content folders. The basic takeaway is that the XMetal webhelp javascript seems to be unable to properly navigate relative paths whenever it has to go up a level and then back down.

    Keyword problem
    We were using keywords in the following way:


    One oddity is that when you add a keyword using the GUI (which is adding a keyword element from the element list and then browsing to another file using the conref attribute (from the Attribute Inspector), XM uses an absolute path. In our implementation, a relative path is used (I assume the XML was edited directly to get to a relative path).

    Ditamaps in parallel folders
    The other extra folder in the index link stems from the fact that each of our ditamaps was in a parallel content folder. It seems that ditamaps always need to be in the same folder as the topics, or in a parent directory. We could have solved this by moving all of our maps to a parent folder. However, we chose to modify webhelp.js in a way that allowed us to use our current folder structure.

    Webhelp.js is located here:
    C:Program Files (x86)Common FilesXMetaL SharedDITA_OTdemowebhelpcustomizationcommonxmwebhelpscript
    Of course, this file will also be found in the %appdata% directory once webhelp is generated.

    The following line of code was altered, to force the index array to start from the correct folder:


    listAnchor = listAnchor.replace(/{HREF}/, indexArray[1]);


    listAnchor = listAnchor.replace(/{HREF}/, '../../'+indexArray[1]);



    Reply to: Broken index links

    I was having a problem with my index inserting extra directories in the path and come here to look for help.

    Well, here it is! Many thanks, kenfesta, changing the line of code in Webhelp.js did the trick and saved my bacon!


  • You must be logged in to reply to this topic.

Lost Your Password?