Home Forums DITA and XMetaL Discussion XMetaL 11 Unable to resolve paths with file:// Reply To: XMetaL 11 Unable to resolve paths with file://

Derek Read

Reply to: XMetaL 11 Unable to resolve paths with file://

Referencing files outside the folder of the map file is not something the DITA Open Toolkit has really supported. You may wish to follow this discussion: https://github.com/dita-ot/dita-ot/issues/1762

However, you might try using the DITA OT parameter “generate.copy.outer” documented here:

That parameter can be set using Tools > Configure Output on the Advanced tab by adding the following into the “Other output parameters” section:

ANT_PARAM_generate.copy.outer  =  3

That should help in the case where your file is outside the folder structure of the map, but not in the case where it is on another computer.

If that parameter does not help then the version of the DITA OT being run may have some issues.
By default the version of the DITA OT that is run with XMetaL Author Enterprise 11 is DITA OT 2.4, however, version 2.2 is also installed. You can change the DITA OT version to 2.2 by swapping the underscores between these two settings:


As far as I know there are no parameters supported by the DITA OT itself that allow you to reference files on another computer and have that content be parsed as an input file to the DITA OT (map or topic).

However, if you are generating output to PDF or some other file format  that results in a single file (CHM maybe) then you might try the XMetaL Author Enterprise setting “cmd_fs_sandboxing  =  yes”. This setting was created specifically to support the Japanese edition of XMetaL Author Enterprise but may help in other situations. Most Japanese authors name their files using Japanese characters (of course) but the DITA OT generally cannot handle non-alphanumeric file names. This setting creates a copy of all referenced files (this is the part that would help with your files on the server), renames them using alphanumeric characters (in order to get around the Japanese language issue), and adjusts all links to point to the new file names. You can set this in Tools > Configure Output on the Advanced tab inside the “Other output parameters” section:
cmd_fs_sandboxing  =  yes

If you are generating output to an HTML-based format then having files outside the map's directory structure might make sense, but for most people I don't think it does. References to files outside the map's directory structure are usually to existing files that are not expected to be copied or moved. Regardless, when you reference a file in a folder that is outside the map's folder structure but on the same drive then the DITA OT can create an additional folder for that file (see the setting ANT_PARAM_generate.copy.outer above). However, in cases where a file is located on a different drive or a different computer the behaviour is undefined. The cmd_fs_sandboxing parameter can help because it effectively flattens the entire folder structure, but that may not be wanted because it also renames files. That's necessary because of the folder flattening, and is probably a minor issue unless your readers use the file names to navigate.

The best solution, probably for all possible cases, is to store, edit and generate output from local files. In cases where you wish to share or store files centrally you can have them delivered locally by a CMS or some other system before asking the DITA OT to do anything with them to avoid limitations with the DITA OT.