Configuring DITA Reference Importing

Content Management > PTC Server connection Document Bursting > Configuring DITA Reference Importing

In a document-type-specific burst configuration file, you can configure how references in Darwin Information Type Architecture (DITA) documents are handled during a burst operation. You can configure bursting for the following types of DITA references:

• Topic references

• Specializations of topic references

• Content references

The customrefspec element can contain as many customref elements as is necessary to configure the handling of DITA references. The customref elements in the configuration file are processed in the order in which they appear in the file.

The customref element has the following attributes:

• mode — Determines how DITA references are imported.

This attribute is required. The mode supports the following values:

◦ dita-full — Defines a reference as a DITA topic reference.

In this case, the file referenced by the topic reference (or a specialization of a DITA topic reference) is imported into the repository and, if appropriate, burst. The topic reference in the referencing file is modified to point to the Logical ID of the referenced document object. Note that if the topic reference element has a scope attribute with a value other than local, the import operation aborts.

This mode is also used for other DITA elements that can reference external content, such as the link, data, and data-about elements.

If a topic reference references a DITA Ditabase document and does not specify one of the topics in the Ditabase in the reference, the reference stored in the repository will be to the entire Ditabase document.

◦ dita-partial — Defines a reference as a DITA content reference.

In this case, the file containing the element referenced by the content reference is imported into the repository and, if appropriate, burst. The portion of the content reference containing the referenced file is modified to point to the Logical ID of the referenced document object. Note that if the content reference element has a scope attribute with a value other than local, the import operation aborts.

DITA content references are handled in the following ways:

▪ Objects referenced by a content reference do not appear in the Browser when you expand a compound document.

▪ Objects that reference another object through a content reference are not displayed by the Browser's View > Used By feature.

▪ When you choose to check out or check in an object and all of its dependant objects, objects referenced by a content reference are not included in the operation.

▪ When you create a baseline of a DITA document, the baseline will not include any objects referenced by a content reference.

This mode is also used for other DITA elements that can reference external content, such as the xref, lq, and fragref elements.

◦ standard — Defines a reference as a non-DITA specific reference.

In this case, the referenced file is imported into the repository. The original reference is modified to point to the Logical ID of the imported object.

• elemname — Defines the element that contains the referencing attribute.

This attribute is optional. If the elemname attribute is defined, the attrname attribute must be defined as well.

• attrname — Defines the attribute that contains the reference.

This attribute is required. Elements that contain this attribute are processed based on the setting of the mode attribute.

In some cases, a circular reference in DITA documents that are being imported might cause the affected document to not be completely imported. An example of a circular reference is when a DITA map contains a topic reference to a topic that contains a content reference to a second topic that contains a link to the first topic. The import process detects and skips circular references during the import. When a circular reference is encountered, an error message is displayed when the import process completes. The affected document is displayed in the Arbortext Editor messages window. To resolve the error, the affected document must be checked out of the repository, changed in some way (such as adding a space and removing it), and checked back into the repository. The document must be changed in some way, because attempting to check in an unchanged object just cancels the check out.

Following is an example customrefspec section from the default document-type-specific burst configuration file for a DITA Map: