Configuring Document Object Boundaries
In a document-type-specific burst configuration file, you can create document object boundaries based on any of the following:
• An element name.
• The presence of any value for a specific element attribute.
• The presence of a specific value for a specific element attribute.
• Boolean XPath expressions
Consider the following usage guidelines regarding object boundary rules:
• If you add a rule that bursts on an element's specific attribute value, you do not necessarily have to have a general rule for bursting the remainder of those elements with the same name.
• You can use all methods on the same element name. For example, a single burst configuration could have all of the following rules:
◦ Burst all chapter elements that specifically have a role attribute value of install.
◦ Burst all chapter elements that have any other value for its role attribute.
◦ Burst all remaining chapter elements.
Arbortext Editor and Arbortext Publishing Engine search for boundary rules in the following order:
1. An attribute boundary rule matching the element name and its attributes.
2. If none is found, an XPath boundary rule for the element name.
3. If none is found, an element boundary rule for the element name.
4. If none is found, the non-element XPath boundary rules are evaluated in order.
Element-Name-Based Object Boundaries
The boundaryspec element can contain as many element elements as is necessary to implement the desired element object boundaries. Each element entry has the following attribute settings:
• name — This is the name of the element you want to configure as an object boundary. Every occurrence of this element name will be a separate document object. Element names are case-sensitive and must match the element name in the document type definition (DTD) or XML schema exactly.
• objecttype — This setting can be set to the value entity, to create a file entity object or xinclude to create an XML inclusion object. The XML inclusion setting is only available with XML documents.
• filemapping — This setting controls the format used for the object reuse information stored for burst elements. If object reuse is not enabled in the system-wide burst configuration file, the filemapping attribute is ignored. If object reuse is enabled, the filemapping attribute supports the following values:
◦ off — Object reuse is disabled for this element.
This is the default value.
◦ dita — The file system path and the element ID of the burst element is maintained for object reuse.
This value is intended to be used for DITA documents. DITA documents can reference elements that are part of larger documents, so the PTC Server connection needs to maintain more specific information about DITA documents for object reuse. The following information is maintained for an element in a DITA document:
file_system_path#element_id
The
element_id is the
ID attribute defined in the document type configuration file (
.dcf) file. If no ID attribute is defined in the
.dcf file, the
id attribute is used by default. The element ID for the element is used for the object reuse information. If the referenced document is not an XML or SGML file, or if no element ID is located in the referenced document, then just the file system path is maintained.
In general, you should structure these rules such that the higher-level elements precede the lower-level elements. (For example, list chapter before sect1 before sect2.) Each element name can have only one element entry.
Element-Attribute-Based Object Boundaries
The boundaryspec element can contain as many attrbndryrule elements as necessary to implement the desired element object boundaries. Each attrbndryrule entry has the following attribute settings:
• elemname — This is the name of the element for which you want to examine attribute data. Elements names are case-sensitive and must match the element name in the document type definition (DTD) exactly.
• attrname — This is the name of a valid attribute for the element named by elemname. If no specific attrvalue is specified, the PTC Server connection will create new document objects based on the presence of any setting for this attribute. Attribute names are case-sensitive and must match the attribute name in the DTD or schema exactly.
• attrvalue — This optional attribute is the specific value for the attribute named by attrname for the element named by elemname. If the attribute value is present, then this rule (that is, attrbndryrule) will be enforced. If this attribute is omitted, the PTC Server connection will create new document objects based on the presence of any setting for the attribute named by attrname. Attribute values are case-sensitive.
• objecttype — This setting can be set to the value entity, to create a file entity object or xinclude to create an XML inclusion object.
• filemapping — This setting controls the format used for the object reuse information stored for burst elements. If object reuse is not enabled in the system-wide burst configuration file, the filemapping attribute is ignored. If object reuse is enabled, the filemapping attribute supports the following values:
◦ off — Object reuse is disabled for this element.
This is the default value.
◦ dita — The file system path and the element ID of the burst element is maintained for object reuse.
This value is intended to be used for DITA documents. DITA documents can reference elements that are part of larger documents, so the PTC Server connection needs to maintain more specific information about DITA documents for object reuse. The following information is maintained for an element in a DITA document:
file_system_path#element_id
The
element_id is the
ID attribute defined in the document type configuration file (
.dcf) file. If no ID attribute is defined in the
.dcf file, the
id attribute is used by default. The element ID for the element is used for the object reuse information. If the referenced document is not an XML or SGML file, or if no element ID is located in the referenced document, then just the file system path is maintained.
XPath object boundaries
Boundary rules can be specified using boolean XPath expressions. Each expression is evaluated with the element as the context node. The expression must be a boolean expression. Though XPath expressions are more flexible than the other boundary rule types, they are generally slower. Therefore, for performance reasons, you may want to avoid using XPath expressions in cases where the other rule types will suffice.
|
|
Non-empty string expressions evaluate to true. Be sure to always use a boolean operator (=, !=, <, >, <=, or >=).
|
XPath-based boundary rules use the xpathbndryrule element. xpathbndryrule elements are children of the boundaryspec element, coming after any element and attrbndryrule elements. An expr attribute specifies the XPath expression. An optional elemname attribute specifies the element for which the rule is applied, otherwise it is applied to all elements. The objecttype and filemapping attributes have the same values as for the attrbndryrule element.
Multiple element-specific XPath rules can be specified for each element type, and multiple non-specific (without elemname) rules can be specified. If any rule evaluates to true, the element is considered an object boundary. Element-specific rules are not necessary, since the XPath expression can test the element name. However, element-specific rules may improve performance.
Following are some XPath examples:
<xpathbndryrule elemname="chapter" expr="@role='paper'"
objecttype="entity"/>
<xpathbndryrule elemname="chapter" expr="@role"
objecttype="entity"/>
