htmlhelp2 plugin bad links

[mmoulder]

I created a new delivery for htmlhelp2 so we could do context sensitive links, but by default it builds the files in the same location as the map which causes are links to be bad since the maps are at the same level as the topics. For example our directory structure is:

maps
tasks
concepts
etc

The chm files get built in the maps directory and link to /tasks, which obviously doesn't exist under maps. I am not sure what xmetal did to resolve this issue, since we can build chm files out of xmetal just fine, but once we use the htmlhelp2 it dies. Any thoughts from anyone would be great.

Reply

[Su-Laine Yeo]

For those who don't follow the dita-users group on Yahoo!, it's been answered here: http://tech.groups.yahoo.com/group/dita-users/message/16534 .

Reply

[mmoulder]

What I am wondering really is what Xmetal does to allow it to work with the map files being in the map directory? It works fine when I do that building using xmetal, just not directly with the open toolkit.

Reply

[Derek Read]

As part of the process for generating output, XMetaL “sandboxes” the files you are working on before handing the sandboxed version over to the DITA OT (one additional step before the DITA OT begins its processing).

Reply

[wetcoastwriter]

As part of the process for generating output, XMetaL “sandboxes” the files you are working on before handing the sandboxed version over to the DITA OT (one additional step before the DITA OT begins its processing).

So, Derek, I got to this discussion because I've been trying to figure out what the cms and fs sandboxing commands (in the Advanced tab of the Configure Output dialog box). Here were my guesses:

cmd_cms_sandboxing – This controls a restricted environment in the repository which certain functions are prohibited. Sandboxes are used when executable code has come from an external
source that is not entirely trusted.
cmd_fs_sandboxing – This controls the sandboxing environment on the file server.

So, first off, am I right? Second off, if we leave the CMS environment (which we have done, actually) do we change these settings?

Under what circumstance would we ever change these settings?

Thanks,
Wanda

Reply

[Derek Read]

Basically both of these params tell XMetaL to create a copy of the files in a structure that is flattened (all files in one folder with all links re-referenced to point to copies in that folder).

When cmd_cms_sandboxing=yes AND you are using a CMS based on our “XMetaL Connector” APIs then this parameter takes effect and makes sure the DITA OT can find everything and the links will all work. If cmd_cms_sandboxing=no AND you are using a CMS then most likely output will fail. If a CMS is not being used then it doesn't matter what this setting is as it does not come into play. So, basically it is not a good idea to change this setting, it will either do nothing (no CMS) or may break your output (with CMS). You can ask your CMS vendor if they have based their integration with XMetaL Author on “XMetaL Connector”.

The param cmd_fs_sandboxing is similar, but was really implemented for testing purposes. When set to “yes” it does the same “flattening” and re-linking as above when a CMS is not being used. In my opinion it should not have been exposed like this. It is not meant to be used by clients and should be left set as is (removing it will have the same result as setting it to “no”).

Reply

[wetcoastwriter]

Thank you so much, Derek.

Reply

[hrahman]

Dees the htmlhelp2 plugin work from within XMetaL? I'm getting errors trying to get it to work using WinAnt…any help would be appreciated. I'm getting build errors at the present.

Reply

[Derek Read]

@hrahman:

I have not tested this plug-in. However, if it is compatible with the DITA OT version included with your installation of XMetaL Author Enterprise it should work. But how it works will depend on the design. Some plug-ins rely on other portions of the DITA OT (such as the XHTML transtype), some do everything on their own. I suspect this one might replace or modify the existing CHM transtype (which in turn relies on XHTML).

XMetaL Author Enterprise (all versions up to 8.0) does not include a “deliverable” for this plug-in so one might need to be created to run it from within the XMetaL Author Enterprise “Generate Output” dialog. Again, it depends how the plug-in was written. If it replaces or extends the existing CHM output then the “deliverable” for the existing CHM output might trigger it instead.

Note: XMetaL Author Enterprise 8.0 includes DITA OT version 1.7.

I'm not sure how busy I will be next week but I might look into getting this working. However, what I have read about it makes me question its usefulness for most people.

In most development + documentation environments I am aware of an HTML Help Workshop “alias” file is maintained by either development or documentation with the two teams coordinating on id values because the development team usually needs to maintain the same id values in their code (in the alias file these typically start with the string “IDH” as recommended by Microsoft). Maintaining an alias file should be fairly easy for most teams as existing pairs of values (example: IDH_introduction = introduction.html) are seldom changed unless your application undergoes major UI changes, and adding a new pair of values is trivial to do in any text editor. Maybe I just don't understand why someone would want to try to maintain these things in their DITA source instead — I'll have to read more about it.

Once you have an alias file it is very simple to create a context sensitive CHM file using any version of XMetaL Author Enterprise and the existing “HTML Help (CHM)” deliverable. That deliverable provides a way to specify the path to the alias file which is then automatically linked to in the generated HHP file that HTML Help Workshop uses to build the CHM.

Reply

[hrahman]

Thank you for your help. I have created an alias file and corresponding mapping file. When I configure the CHM output, I specify an “alias” and “map” file. The problem I'm having now is that XMetaL automatically changes the names of those files and so my mapping doesn't work. Furthermore, it sets the alias file to a “.ali” extension which gets ignored.

If I take the hhp file generated by XMetaL and modify it to include the correct  “alias” and “map” files, the context help works.

Is this a bug or am I missing something?

Thanks!
Hennah

Reply

[Derek Read]

I can't reproduce your issue where XMetaL Author Enterprise is renaming these files. There is no code in place that would do that so I'm not sure what might be causing it. You are simply specifying the paths to these two files (or just the alias file) in the “Edit Deliverable Type” dialog?

Reply

[Author]

Posts