DITA and Flare
Before we look at Flare's support for DITA in detail, let's just briefly review the main features and benefits of DITA itself. DITA (which stands for Darwin Information Typing Architecture) is an XML-based end-to-end architecture for authoring and delivering technical information in a range of formats. It originated within IBM in the early part of this decade, and was donated to the OASIS standards organization in 2004. Since then, interest in DITA has grown rapidly and authoring tool support is now beginning to gain momentum.
The key features and benefits of DITA are:
- Its topic-based paradigm, which makes information re-use easier and makes it a very suitable source format for software user assistance
- Its structured and semantic mark-up, which makes for increased consistency and more effective content management
- Its unique support for "specialization", which enables it to be customised for specific domains and industry sectors while still maintaining the underlying structures
- The fact that it is an open and non-proprietary standard, which means that resources such as transforms and specializations can be shared throughout the technical communications community.
One of the key questions is: if you are already a Flare user, is it worth you adopting DITA with the arrival of Flare 5? Or should you just continue using Flare's XHTML Editor for creating content? DITA's topic-based paradigm alone does not provide a compelling reason to embrace DITA since Flare is already topic-based itself, and enables topics to be re-used across multiple projects through the global project linking feature (introduced in Flare 4.0). However, Flare does not in itself yet provide a structured authoring environment; so without DITA it is not possible to constrain authors to write specific types of topic to a particular outline or structure V for example, always to ensure that task topics contain at least one instructional step. Structured authoring is one of the key advantages that moving to DITA would bring, and it is particularly beneficial for large teams of authors where consistency of approach can be a key issue. Structured authoring also makes content easier to manage and re-purpose.
Specialization, although a unique and very important feature of DITA, cannot be viewed as a benefit of adopting DITA from a Flare user's point of view, since Flare 5 does not yet officially support specialized content (although some early adopters of Flare 5 have apparently had success with it).
If existing Flare users do decide to create DITA-based content, then they will have to do so in a separate authoring tool such as PTC's Arbortext Editor or XMetaL Author Enterprise from JustSystems — Flare's own editor is still restricted to working with XHTML-based content in version 5.
What about authors who are already committed to DITA and are considering adopting Flare for the first time — what can Flare 5 offer them? The answer is that Flare 5 provides a very powerful and flexible publishing engine. It is true that DITA already has, in the form of the freely available DITA Open Toolkit and associated open source Apache tools, a ready-made set of tools for generating outputs including PDF and HTML Help. However, the DITA Open Toolkit is relatively primitive, has no graphical user interface, offers very restricted facilities for changing the look-and-feel of the output without advanced coding, and does not enable you to generate a browser-based Help format such as Flare's WebHelp. Flare, on the other hand, offers highly flexible publishing, the ability to apply custom style sheets, easily configure the window or skin of the output, and to select from a wide range of target formats including WebHelp, WebHelp AIR, PDF, and HTML Help.
Another advantage of using Flare is that it is possible to take advantage of advanced features including Master Pages (which enable you to add headers, such as breadcrumbs, and footers to every topic) and automatic linking of glossary terms.
Flare also offers the possibility of seamlessly merging DITA-based content with other source formats such as Word, FrameMaker or HTML into a single output such as a PDF document or HTML Help system. The way this publishing workflow works is that the Flare project is linked to the required source documents (in DITA, Word, or FrameMaker format). This source content is then converted by Flare to XHTML before being generated to the required output format in the usual way from Flare. The key aspect of this workflow is that, since the source documents are linked to the Flare project, any subsequent modification to the source documents will cause the corresponding XHTML content to be updated accordingly. This means that the generated content is always fully up-to-date. See Figure 1 for a graphical representation of this workflow.
Figure 1: Possible publishing workflow
How Flare imports DITA
The process for importing DITA-based content in Flare 5 is very similar to the process established in earlier versions of Flare for importing Word and FrameMaker documents. You start by adding a special "DITA Import File" to your project — this contains all the parameters and options that control the import process, and enables the import to be repeated at any time with precisely the same settings. You set the required parameters and options using Flare's dedicated DITA Import Editor, shown in Figure 2.
Figure 2: Flares DITA Import Editor
You can select either individual DITA documents (which usually have either a .dita or .xml extension) or ditamap files. Ditamap files are analogous to table of contents (TOC) files because they reference a number of DITA topics and specify a hierarchy for the topics. Hence, by selecting a single ditamap file you can import a large number of DITA topics.
One of the key settings is the Link option, which enables you to retain a link to the source document(s) so that the imported XHTML content can be easily updated from subsequent modifications to the source DITA document(s). This makes possible the workflow described in the previous section and shown in Figure 1 above.
You would only choose not to select the Link option if you planned to do a "one-off" import and to subsequently update the imported information within Flare. This workflow only really makes sense if you have decided to switch away from DITA to Flare, because otherwise you would be in the situation of maintaining the same content independently in both DITA and Flare).
Irrespective or whether you link or not, Flare converts the source DITA topics into ordinary XHTML Flare topics. It does this by mapping each of the semantic DITA elements (such as <steps> and <example>) to a named class of the nearest equivalent XHTML element. For example, the DITA
| DITA Element | Mapped XHTML Element | <p> | <p> |
|---|---|
| <title> | <title> and <h1 class="tasktitle"> |
| <shortdesc> | <p class="shortdesc"> |
| <context> | <div class="context"> |
| <prereq> | <div class="prereq"> |
| <step> | <li class="step"> |
| <cmd> | <span class="cmd"> |
| <stepresult> | <div class="stepresult"> |
| <result> | <div class="result"> |
| <example> | <div class="example"> |
The Stylesheet tab of the DITA Import Editor includes a Conversion Styles button (see Figure 3).
Figure 3: Stylesheet tab of the DITA Import Editor showing the Conversion Styles button
By clicking this, you can access the DITA Import Styles Editor (shown in Figure 4). This has a very similar interface to the Advanced View of Flare's Stylesheet Editor, and it enables you to define formatting properties for each of the source DITA elements. These formatting properties are stored in a new stylesheet that is applied to each of the imported topics. Alternatively, by associating an existing stylesheet, you can have the new styles combined with the styles from an existing stylesheet. This approach gives a lot of flexibility, but can be slightly confusing to begin with — especially as it is rather different from the way in which stylesheets are handled for imported Word and FrameMaker documents.
Figure 4: DITA Import Styles Editor
Because of the class attributes and other metadata stored by Flare, the resulting XHTML topics are arguably as semantically rich as the original DITA topics, and you have complete control over their formatting through the DITA Import Styles Editor described above.
If you imported a ditamap file then, as well as all the referenced DITA topics being imported, the ditamap itself is imported as a Flare TOC file. In theory, Flare even supports the import of nested ditamaps, which result in linked TOC files within the Flare project. However, you should take care to check that the topics referenced by these nested ditamaps have been imported successfully. It is also important to note that Flare 5 doesn't cope with bookmaps, which are now very common but could be viewed as specializations and therefore not officially supported by Flare.
How Flare generates DITA
Flare supports the generation of DITA by providing a new Target Output Type of DITA. In my view this is much less useful than Flare's ability to import DITA; since Flare does not yet provide a structured authoring environment, it is not possible to guarantee that its DITA output will conform to the strict structure rules of DITA. In other words, the DITA output may not be valid, and may be considered weakly typed. I have also discovered that when you generate DITA output from topics that have been imported from a DITA source, the resulting DITA topics are less semantically rich than the original source topics. For example,
I can't really think of a sensible use case for generating DITA content from Flare, unless you plan to integrate the resulting DITA content into a separate DITA-based content management system or publishing system. But in that case, you would be losing your single source and would risk duplication of effort if you needed to keep your Flare-based content and external DITA content synchronised.
One of the unique features of DITA is its support for Relationship Tables. These enable you to define complex linking relationships between topics, outside of the topics themselves. For example, you could use a Relationship Table to specify that a set of task topics should all include hyperlinks to each other, and that they should also include hyperlinks to a specific concept and specific reference topic. This information, instead of being contained within the topics themselves, is stored within the ditamap in a special reltable section. The hyperlinks (or cross-references in the case of print-based targets) are only added into the topics at publishing time. The advantage of this approach is that it enables much more flexible re-use of topics since the relationships can de redefined based on the requirements of a particular output generated from a specific selection of topics.
In order to provide support for this approach, Flare 5 now has a new project file type of "Relationship Table". This project file enables you to store topic relationships in almost exactly the same way as in DITA reltables; and it supports the same range of relationship types, including one-way or two-way linking. The concepts behind Relationship Tables and the way in which they operate are very complex, and Flare's Help system provides an extremely clear and comprehensive explanation of their various features and nuances. The explanation is based around a number of useful simple examples.
The way Relationship Tables are used in Flare differs from DITA in one significant respect: instead of being stored within a ditamap and implemented automatically a publishing time across all topics referenced by the ditamap, you have to insert a special new "Relationships Proxy" in any topic that you wish to contain links specified by the Relationship Table. In my view, it might have been neater and simpler for Flare to have provided a facility for selecting a Relationship Table within the DITA Target settings, and have them applied automatically to all topics as a result. However, an advantage of using a Relationship Proxy is that it enables to you specify the precise location of the inserted hyperlinks (or cross-references) instead of just having them inserted at the end of the topic. You do also have the ability to insert a Relationships Proxy within the master page for the target, which is a way of avoiding having to insert it into every topic individually.
Conrefs are the mechanism by which DITA supports transclusion: that is, the inclusion of part of a document into another document by reference. On import into Flare 5, conrefs are converted into Snippets. These match the functionality of conrefs, but with a slight difference: the content referenced by a conref is stored inside an ordinary topic, whereas Snippets are special reusable content objects that are referenced from other topics but not used as topics themselves. The Flare model of using Snippets for re-usable content actually makes this re-usable content easier to identify and track.
When you generate DITA out of Flare, any Snippet references are converted to DITA conrefs, and the Snippets themselves are converted to DITA topics that are not referenced from the generated ditamap.
Other DITA editing tools use their own special mechanisms for transclusion, which Flare may or may not be able to import successfully. XMetaL Author Enterprise, for example, has a feature called "Reusable Components" that is based on DITA conrefs but presented with a more intuitive workflow. I have not been able to successfully import these Reusable Components into Flare.
According to MadCap Software, Flare version 5 represents only the beginning of their support for DITA, and they are working towards full support for native DITA authoring in a future version of Flare. The way it would work is that you would decide at the start of a project between the use of the existing XHTML/MadCap schema combination for validation, or DITA validation. When native DITA authoring is supported, you could consider Flare as a possible candidate for all your structured content development and publishing needs.
Flare's current DITA support comprises the ability to import and generate DITA-based content. This could be useful to existing Flare users who wish to incorporate DITA-based content within their Flare projects. These users will need a separate DITA authoring tool to create and maintain the DITA-based source. In my view, the ability to generate DITA from Flare is less useful. Existing users of DITA may be attracted to Flare 5 as a means of publishing their DITA content to a range of formats including WebHelp, HTML Help and PDF. In a future version of Flare it may be possible to edit DITA-based content directly.
Further reading
Online Community for the DITA OASIS Standard
DITA 101 by Ann Rockley, Steve Manning, and Charles Cooper
Improving Relationships in Relationship Tables
