Publish of ditamap changes topicref href=…xml scope="external" to href=…html

[Anonymous]

I want to include a link to an example XML file in my  ditamap. Here is what I have:

 

However, when I generate the output for this ditamap. Xmetal processes that topicref to:
example-xml-file

But of course, there is no file  example-xml-file.html!
I just want the .xml file to be copied to the output folder and the ditamap  to say:
example-xml-file

What can I do?
Thanks,
Pete

Reply

[Derek Read]

This will be a DITA OT issue as far as I can tell (XMetaL Author Enterprise itself doesn't get involved directly in this process beyond handing your files over to the DITA OT).

I'll set up some tests and see what happens here. There has to be a way around this, it is just a question of how much work it would be to fix the issue and whether we can figure that out easily or whether it makes more sense to log this as a defect with the DITA OT project at SourceForge.

Reply

[gcrews]

I think it was a bug that has since been fixed in later versions of the toolkit:
http://sourceforge.net/tracker/?func=detail&aid=2832696&group_id=132728&atid=725074

Reply

[Derek Read]

OK, I see the issue. The code that the DITA OT uses to generate the TOC file is what is putting in the link that you don't want and it appears to be due to lack of any special handling when it encounters a link to a *.xml filetype inside a . Additional code would need to be added to the DITA OT to handle this use case, possibly with the inclusion of some additional attribute in the to identify this as a special topicref when producing the TOC (I have not thought through the exact details and they might be driven by the underlying existing code).

If you modify the href value and the filename so that it is “example-txt-file.txt” this should become a little more clear. It handles it properly in this case, so the confusion would seem to be simply the *xml file extension. If you really need the DITA OT to support this scenario I would suggest you submit a defect here describing the issue: http://sourceforge.net/tracker/?group_id=132728&atid=725074

You would also need to contend with what will happen when the reader clicks on such a link in their browser (or whatever software they are using to view the HTML). Depending on the content in the XML file, in some cases the browser might render the XML itself (usually in the forum of a “node tree”, or perhaps as the XML source), in some browsers it might complain there is no DTD (if you include a DOCTYPE), or it might attempt to pass the file to another application to open it. I'm not sure what you would expect. If the intention is to allow people to copy the XML for use elsewhere what will end up on the clipboard may also differ depending on how it is being rendered.

It might be more predictable to link to another file type that contains the same XML content. Perhaps TXT is sufficient for your purpose (if that is merely to allow someone to view the content of the file)? What a web browser does in that case (when it encounters a file with a TXT extension) may also differ from browser to browser.

You might try these options as well:

Move the link into a DITA topic
1) Create a that links to a regular DITA topic.
2) Inside the DITA topic include an that links to your XML file and optionally includes an appropriate amount of content inside or around the to describe what the link is to and what it contains. In this case the DITA OT does not alter the link (it will continue to point the the *.xml file). In this case you are left with the issue of what a particular browser does when someone clicks on a link to an XML file (as discussed above).

Include the source of the XML inside a topic
1) Create a to a regular DITA topic.
2) Inside the topic include the full text of the XML document. You may include this inside various elements intended for this purpose, perhaps makes the most sense. To avoid the need to escape characters inside the XML and include it verbatim you may wish to place it within a CDATA section inside the element.
Example of what the DITA source XML might look like:
[code]





]]>
[/code]

The DITA OT generates this when producing HTML from the DITA above:
[code]

<?xml version="1.0"?>
<!DOCTYPE foo PUBLIC "-//ORG//MY DOCTYPE//EN" "schemaname.dtd">
<foo>
	<bar/>

	<baz/>
</foo>

[/code]

…which ends up looking like this in a browser after all the entities have been interpreted:

Reply

[Derek Read]

— Good catch gcrews, I was unable to find a matching defect at SourceForge.

I think my other concerns are still valid however, and might come into play here, namely: What do you intend for the reader of your documentation to do with the XML file? That would still be a driving factor for me.

If the answer is that you don't care what happens, you simply want the reader to be able to navigate to it as a separate file (and let the browser decide what it does with it) then using a newer version of the OT is the solution. My opinion is that the last solution I offered (display the XML inline inside a topic) is the best one (it would be for any cases I can think of but I don't have all the details).

Yet another option would be to provide your XML file compressed into a ZIP file or other archive format you intend your readers to have a tool for dealing with (all current versions of Windows include unZIP capabilities).

Note that the only way to obtain DITA OT 1.5 for use with XMetaL Author Enterprise 6.0 is to obtain a copy of the “DITA 1.2 Configuration Kit” (that installer bundles and properly installs it integrated with XMetaL). However, installing the “Configuration Kit” also enables the DITA 1.2 DTDs by default. DITA 1.1 and 1.0 can still be configured but that would be one more step. Note as well that we consider this “Configuration Kit” beta software (similar but far superior capabilities will be included with our next official release).

The alternative is to wait for the next release (7.0) which will include the most recent version of the DITA OT included with what we ship.

If you are using a CMS and it has the ability to generate output using the DITA OT you may ask the CMS vendor to help you upgrade the version of the DITA OT  installed on the CMS server.

Reply

[Author]

Posts