DITA Publishing

DITA Documents

As with other document content, DITA files are stored in IBM FileNet P8 as Document objects. The Document class is extended to include subclasses that represent topics (DitaBase), maps (DitaMap), and processing profiles (DitaVal). The DitaBase and DitaMap classes have a rich set of metadata that maps to key DITA elements and attributes to provide a powerful query capability. The base DITA-specific document subclasses are shown in the following figure:

DitaBase

The DitaBase class contains metadata that is common to all of the standard DITA information types (concept, glossentry, reference, task, and topic). The DITA Classifier assigns the DitaBase metadata values based on element and attribute nodes extracted (by using XPath) from DITA topics and maps. The DitaBase class is further subclassed to represent specific DITA information types, as shown in the following figure:

DitaMap

The DitaMap class contains metadata that is common to all DITA maps. The DitaMap class is further subclassed to represent the DITA bookmap specialization, which provides metadata that represents collections of DITA topics that are organized as a book. Using XPath, the DITA Classifier retrieves the <map> (or <bookmap>) element's id and title attributes and assigns them to the DitaMap class' DitaId and DitaTitle properties. If the DITA map uses the bookmap specialization, the map is added as a DitaBookMap object and additional properties are assigned by the DITA Classifier. The DitaMap and DitaBookMap classes are shown in the following figure:

DitaVal

The DitaVal class represents a DITA processing profile. The IBM FileNet P8 Publish Style Template Manager searches for objects of this type to identify processing profiles that are stored in the IBM FileNet P8 system.

DITA Relationships

DITA relationships are tracked by using IBM FileNet P8 compound documents. The ComponentRelationship class is extended to represent the different types of DITA relationships, as shown in the following figure.

The ComponentRelationship subclasses are defined as follows:

• DitaBaseref is the superclass for all DITA-specific component relationship classes.
• DitaConref specifies a relationship between a DITA map or topic that contains a content reference (as specified by a conref attribute) and the map or topic that contains the referenced content fragment.
• DitaImageref specifies a relationship between a DITA topic and an image that is part of the current information set.
• DitaLinkref specifies a link relationship to another file in the current information set.
• DitaMapref specifies a relationship between a DITA map and submap.
• DitaTopicref specifies a relationship between a DITA map and a local resource (for example, a DITA, HTML or PDF file).
• DitaXref specifies a cross-reference relationship to another file in the current information set.

Using XPath, the DITA Classifier parses a DITA topic or map file to identify relationships and creates corresponding relationship objects. For more information, see DITA Classifier.

The following figures show the default types of relationships that can be created between DITA maps or topics and other Document objects in an IBM FileNet P8 system. If needed, you can add other component relationship types to support your specific DITA publishing requirements. See Setting Up a DITA Project.

DITA Map Relationships

A DitaMap object supports three types of component relationships: DitaConref, DitaMapref, and DitaTopicref. These relationships can link a parent DitaMap object to a child content fragment, submap, or topic (DITA, HTML, or PDF file).

DITA Topic Relationships

A DitaBase object supports the following types of component relationships: DitaConref, DitaImageref, DitaLinkref, and DitaXref. These relationships can link a parent DitaBase object to a child content fragment, image, link destination, or cross-reference destination.

Using DITA Component Relationships

The Document class defines the following properties for retrieving ComponentRelationship objects or the documents to which they are bound.

• ChildDocuments
• ChildRelationship
• ParentDocuments
• ParentRelationships

Using these properties, you can find all of a parent component's direct child components, and all of the parent components that reference a child component. The DitaBaseref subclasses (DitaConref, DitaImageref, DitaLinkref, DitaMapref, DitaTopicref, and DitaXref) allow queries to be limited to a specific type of relationship. For example, you can define a query that, from a child component, finds all parent objects that reference a specific conref (as identified by the DitaElementId property).

DITA Classifier

DITA Publishing provides a custom classifier that plugs into the IBM FileNet P8 document classification framework. When a DITA file is checked in with the AUTO_CLASSIFY option set, the DITA Classifier does the following tasks:

1. Assigns a document class (based on the root element of the DITA file).
   Note: If the document exists and the correct document class is assigned (as determined by the document root element), the classifier does not reassign the document class. Therefore, if the root element did not change, non-DITA properties that you might have set are not overwritten when the document is checked in. However, if you manually modified any of the DITA-specific properties, those properties are updated to match the corresponding values in the DITA document.
2. Assigns values to the document's DITA-specific properties (based on DITA elements and attributes).
3. Creates component relationship objects for child references (xrefs, images, links, and so on). If a referenced object doesn't exist, the classifier creates a zero-length stub file with a major version number of 0 and a minor version number of 1 (along with any containing folders that do not exist).

Document Classification

The first task the DITA Classifier performs is document classification. The classifier looks at the root element of the DITA topic to determine the appropriate document class to assign. The default mappings are shown in the following table.

DITA-specific Document Properties

Once the document class is determined, the DITA Classifier uses XPath to retrieve key metadata that is defined in the document's elements and attributes. The metadata is specific to a particular object type (DitaBase, DitaMap, or DitaBookMap). You can customize the classifier to add or remove support for properties, depending on your DITA publishing requirements. See Setting Up a DITA Project.

DitaBase

If the document is a topic (subclass of DitaBase), the following properties are retrieved.

DitaMap

If the document is a generic DITA map (DitaMap), the following properties are retrieved.

DitaBookMap

If the document is a bookmap specialization (DitaBookMap), the following properties are retrieved.

Component RelationshipClassification

The third function of the DITA Classifier is to create ComponentRelationship objects that represent references to child objects. The DITA Classifier identifies relationships based on XPath values as shown in the following table.

By default, the classifier assigns the following ComponentRelationship property values. You can customize these properties to support other behavior. For more information about these ComponentRelationship properties, see Compound Documents.

DITA Query

Using the classes and properties that are described in DITA Documents and DITA Relationships, you can write sophisticated queries that support content retrieval and reuse. Some example queries are listed in the following section. See Searching for DITA Metadata for a code example that demonstrates how to run the queries by using the Content Engine API.

Determine if a content fragment is referenced.

This query retrieves a single content reference (conref) ComponentRelationship row (including specializations of DitaConref) that references a given content fragment element ID and child document.

 
 SELECT TOP 1 Id FROM DitaConref 
    WHERE ChildComponent =OBJECT('{GUID}') 
    AND DitaElementId = 'x' 

Determine if a topic is referenced by a map.

This query retrieves a single topic reference (topicref) ComponentRelationship row (including specializations of DitaTopicref) that references a given child document and topic ID.

 
 SELECT TOP 1 id FROM DitaTopicref 
    WHERE ChildComponent =OBJECT('{GUID}') 
    AND DitaId = 'some-id' 

Return all topics authored by the same user.

This query retrieves the most recent version of DITA topics (tasks, concepts, and so on) where the user is specified as an author.

 
SELECT id FROM DitaBase 
    WHERE user IN DitaAuthors 
    AND IsCurrentVersion = true

DITA Publishing

DITA Publishing allows a customer-installed instance of the DITA Open Toolkit to be used as a Rendition Engine. For more information about the DITA Open Toolkit, see DITA Open Toolkit Project Home.

DITA Publishing is integrated into the IBM FileNet P8 publishing framework as follows:

• The DITARenditionEngineConnection extends RenditionEngineConnection to include the following:
  • The database transaction timeout for DITA publishing requests. See DITADatabaseTimeout Property.
  • The directory where the DITA Open Toolkit is installed. See DITAHome Property.
  • Optional Java™ (JVM) arguments that are used to start the DITA Open Toolkit. See DITAJVMArguments Property.
  • The working directory where DITA component documents in the Content Engine are copied. See DITAWorkingDirectory Property.
• DITA-specific publish style template transformation options specify the output format, DITAVAL file and title (optional), and whether to do a "copy-only" operation (so that you can process the files outside of the IBM FileNet P8 system).
• A DITA publish request handler, which does the following tasks:
  Note: For a copy-only operation, the handler does only the first two items.
  • Copies the IBM FileNet P8 DITA project files (as specified in the project's top-level DITA map) to a unique folder in the working directory.
  • Logs information that is related to the publish operation.
  • Sets the CLASSPATH, ANT_HOME, and PATH environment variables that are used to start the DITA Open Toolkit. The variables are set by using one of the following methods:
    • Dynamic: The environment variables are set at runtime based on the contents of the DITA Open Toolkit folders.
    • Static: If a file named p8dita.env is present in the top-level DITAHome folder, the contents of that file are used to set the environment variables. For more information, see Creating a p8dita.env File.
  • Starts the DITA Open Toolkit on the specified DITA map by using the JVM arguments, output directory, transformation type, working directory, and DITAVAL file that is specified by the DITARenditionEngineConnection and PublishStyleTemplate objects. The DITA publish request handler also specifies a temporary directory (located under the working directory) that is used by the DITA Open Toolkit for processing files.
  • If the DITA Open Toolkit publish operation is successful, the handler checks in the rendered PDF by using the options that are specified by the PublishTemplate object and Publish Options XML.