IBM® FileNet® P8 DITA Publishing provides a DITA-based information development solution that is built upon the following IBM FileNet P8 functionality:
Document
class is extended to
represent DITA topics, maps, and processing profiles (DITAVAL files). See DITA
Documents.Document
and ComponentRelationship
subclasses when a DITA document is checked in.
See DITA Classifier.Document
and ComponentRelationship
subclasses
provide a powerful query capability that supports content reuse. See DITA Query.Because DITA Publishing is built upon core IBM FileNet P8 functionality, it can be easily customized. For example, you can add support for a DITA specialization, write a specialized query, or develop your own publishing application. See Working with DITA Publishing for examples.
Notes:
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 figure below.
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 (using XPath) from DITA topics and maps. The DitaBase
class is further subclassed to represent specific DITA information types, as shown in the figure below.
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 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 figure below.
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 stored in the IBM FileNet P8 system.
DITA relationships are tracked 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. See DITA Classifier for more information on this process.
The following figures show the default types of relationships that can be created between DITA maps or topics and other
Document
objects in a 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.
Note: The label "DitaBase" refers to any one of the DitaBase
subclasses
(DitaConcept
, DitaGlossEntry
, DitaReference
, DitaTask
, or DitaTopic
).
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.
The Document
class defines the following properties for retrieving ComponentRelationship
objects or the documents to
which they are bound.
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 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:
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 table below.
Root Element | Document Class |
---|---|
<bookmap> | DitaBookMap |
<concept> | DitaConcept |
<dita> | DitaBase |
<glossentry> | DitaGlossEntry |
<map> | DitaMap |
<reference> | DitaReference |
<task> | DitaTask |
<topic> | DitaTopic |
Once the document class is determined, the DITA Classifier uses XPath to retrieve key metadata 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.
If the document is a topic (subclass of DitaBase
), the following properties are retrieved.
Note: If the document class is DitaBase
(and, therefore, the document's root element is <dita>,)
the classifier doesn't retrieve any properties from the document. This is because a DITA document whose root element is <dita> can contain
multiple concepts, tasks, topics, etc.
Property | Datatype | XPath |
---|---|---|
DitaId | string | /*/@id |
DitaTitle | string | /*/title/text() |
DitaNavTitle | string | /*/titlealts/navtitle/text() |
DitaSearchTitle | string | /*/titlealts/searchtitle/text() |
DitaKeywords | multi-value string | //keyword/text() |
DitaAuthors | multi-value string | //author/text() |
DitaAudiences | multi-value string | //audience/@type |
DitaCategories | multi-value string | //category/text() |
DitaBrands | multi-value string | //brand/text() |
DitaProdNames | multi-value string | //prodname/text() |
DitaPlatforms | multi-value string | //platform/text() |
If the document is a generic DITA map (DitaMap
), the following properties are retrieved.
Property | Datatype | XPath |
---|---|---|
DitaId | string | /map/@id |
DitaTitle | string | /map/@title |
If the document is a bookmap specialization (DitaBookMap
), the following properties are retrieved.
Property | Datatype | XPath |
---|---|---|
DitaId | string | /bookmap/@id |
DitaTitle | string | //mainbooktitle/text() |
DitaSearchTitle | String | //booktitlealt |
DitaKeywords | multi-value string | //bookmeta/keywords/keyword/text() |
DitaAuthors | multi-value string | //bookmeta/author/text() |
DitaPublishers | multi-value string | //publisherinformation |
DitaAudiences | multi-value string | //bookmeta/audience/@type |
DitaCategories | multi-value string | //bookmeta/category/text() |
DitaProdNames | multi-value string | //bookmeta/prodinfo/prodname//text() |
DitaBrands | multi-value string | //bookmeta/prodinfo/brand/text() |
DitaPlatforms | multi-value string | //bookmeta/prodinfoplatform/text() |
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.
Type | Class | XPath | Notes |
---|---|---|---|
content fragment | DitaConref | //@conref | A DitaConref object is created for each conref attribute that links to another file in the
current information set. If the content reference and content fragment are in the same file or if the content fragment is
external to the current information set, no relationship is created. |
image | DitaImageref | //image/@href | If the image is external to the current information set, no relationship is created. |
link | DitaLinkref | //link/@href | If the link destination is in the current file or in a file external to the current information set, no relationship is created. |
map reference | DitaMapref | //topicref[@format="ditamap"]/@href | A DitaMapref object is created for each topicref element whose format attribute is set to
"ditamap". |
topic reference | DitaTopicref | //topicref[@format!="ditamap"]/@href | If the resource is external to the current information set, no relationship is created. |
cross-reference | DitaXref | //xref/@href | If the cross-reference destination is in the current file or in a file external to the current information set, no relationship is created. |
By default, the classifier assigns the following ComponentRelationship
property values. You can customize these
properties to support other behavior. See Compound Document Concepts for more information on
these ComponentRelationship
properties.
Property | Default DITA Classifier value |
---|---|
ComponentCascadeDelete | NO_CASCADE_DELETE |
ComponentPreventDelete | ALLOW_BOTH_DELETE |
ComponentRelationshipType | DYNAMIC_CR |
CopyToReservation | FALSE |
VersionBindType | LATEST_MAJOR_VERSION |
Notes:
Using the classes and properties described in DITA Documents and DITA Relationships, you can write sophisticated queries that support content retrieval and reuse. Some example queries are listed below. See Searching for DITA Metadata for a code example that demonstrates how to execute the queries using the Content Engine API.
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'
This query retrieves a single topic reference (topicref) ComponentRelationship
row (including specializations of
DitaTopicref
) that references a given child document and topic ID.
Note: If the child document contains only one DITA topic, the AND clause is not required.
SELECT TOP 1 id FROM DitaTopicref WHERE ChildComponent = OBJECT('{GUID}') AND DitaId = 'some-id'
This query retrieves the most recent version of DITA topics (tasks, concepts, etc.) where the given user is specified as an author.
SELECT id FROM DitaBase WHERE user IN DitaAuthors AND IsCurrentVersion = true
DITA Publishing allows a customer-installed instance of the DITA Open Toolkit to be used as a rendition engine. For additional 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:
DITARenditionEngineConnection
extends RenditionEngineConnection
to include the following: Note: If this is a "copy-only" operation, the handler does only the first two items.
DITARenditionEngineConnection
and
PublishStyleTemplate
objects. The DITA publish request handler also specifies a temp directory (located under the working directory)
that is used by the DITA Open Toolkit for processing files, .PublishTemplate
object and Publish Options XML.