XML topics in a DITA map

[TMiles]

I am creating a reference work comprising entries, organised by higher-level subjects. Each entry will take the form of an individual XML file, structured with my own custom tags.

As I want to include some entries in multiple subjects, I am trying to manage the entire reference work using something akin to a DITA map. However, the presence of XML files in the DITA map is triggering errors.

Before I attempt to go any further, my questions are:
1. Is there any way to make the DITA map accept these XML files?
2. Could I simply ignore these errors and publish the reference work without any problems?
3. Is there an alternative way to reuse XML files, view the structure and then publish the entire reference work?

Thanks for your help.

[Radu]

Hi,

Please see some answers below:

1. Is there any way to make the DITA map accept these XML files?

In a DITA Map you can refer to any type of non-DITA file file if you specify the "format" attribute.
For example:

Code: Select all

<topicref href="test.xml" format="custom"/>

If you do that, Oxygen will not show errors for these references. But it will also not interpret them as DITA topics, for example it will not show their titles in the DITA Map. Oxygen will consider them some other kind of resources referenced in the DITA Map.

2. Could I simply ignore these errors and publish the reference work without any problems?

Code: Select all

The publishing engine processes the DITA map according to the DITA XML standard.

If you refer in the DITA Map to a file without the format attribute or with format=dita:

Code: Select all

<topicref href="abc.xml"/>

the publishing engine will consider this a DITA topic and will try to interpret it as such. When it probably will fail to do that, it will show errors and skip processing the file.
If you refer to the file using a "format="custom"" attribute on the topicref, the publishing engine will use the DITA Map to obtain a table of contents but will not process the topicreference because it does not point to a DITA topic.
That's how the standard works.

3. Is there an alternative way to reuse XML files, view the structure and then publish the entire reference work?

You could try to avoid using your custom XML format, either use regular DITA XML topics or try to create a DITA vocabulary specialization using your own XML elements but basing your XML structure on a base DITA topic (which may or may not be flexible enough).
https://www.oxygenxml.com/doc/ug-editor ... ation.html
Another approach is to create a DITA Open Toolkit plugin which adds support in the publishing engine for a custom XML format. Basically it adds support for the publishing engine to interpret a custom XML format as if it were a DITA topic, to translate it to a DITA topic on the fly, while publishing.
For example this open source plugin I created some time ago attempts to convert a JSON file to DITA XML at publishing time:
https://github.com/oxygenxml/dita-json
The plugin contributed a special conversion for the "json" format value which dynamically creates JSON to a DITA XML topic while publishing.

Code: Select all

 <keydef href="ui-strings.json" format="json" keys="uiStrings"/>

Or this open source plugin which attempts to convert on the fly references to AsciiDoc documents to DITA XML topics while publishing:
https://github.com/oxygenxml/dita-json

Regards,
Radu

[TMiles]

Thanks for your reply, Radu.

Do you agree that constructing an XML project (.xpr) with files listing entities to call on content from other files would be an alternative way to more or less achieve the same goal as a DITA map?

[Radu]

Hi,

The Oxygen project lists the files and folders you add to it. It's used for locating and editing various files referenced in it. It's like having a small Windows Explorer with some Oxygen specific functionality as a side view inside the application.
The Oxygen project has no relationship to publishing, you do not publish a project .xpr file.

Regards,
Radu