I've asked to be made (co-) maintainer of this module because I think Drupal could make for a good web front-end for DITA content (see also http://idratherbewriting.com/2014/01/04/the-appeal-of-dita/).

However, I'm not sure whether this module should be developed any further or if there are other - and better - ways for integrating DITA and Drupal. Therefore I provide here some findings and thoughts in hope to elicit some feedback from the community.

The status quo - some observations

  1. The Drupal 6 and Drupal 7 version of this module differ in feature set and functionality. The Drupal 7 version isn't just an upgraded Drupal 6 version (see the readme file). So basically we're talking about two different modules for DITA integration.
  2. I've only tried the Drupal 7 version yet, but the module doesn't work out of the box (at least not for me). Actually, I haven't got it working at all yet.
  3. There are lots of dependencies for other modules or even external PHP libraries.
  4. The module is tightly coupled. Separate features are not separated into sub-modules.
  5. There are features which IMO should not be part of a DITA integration module, e.g. creating ditamaps from mind maps or validating the XML against a DTD or schema. There are other and better tools for this.

What features should a DITA integration module for Drupal provide?

(at least in an initial implementation)

  1. The module should only consume DITA files not produce them.
  2. The module shouldn't have to validate the DITA files. This can and should better be done externally further up in the workflow.
  3. The module should be able to import single topics and ditamaps.
  4. The module should convert DITA meta data into Drupal taxonomies.

Drupal alternatives

There are already quite some robust contributed modules for handling the import of XML content (see http://groups.drupal.org/node/21338 for an overview). IMO the most promising are the Feeds API (https://drupal.org/project/feeds) and Migrate (https://drupal.org/project/migrate) which also supports XML based sources (https://drupal.org/node/1152156).

These are only some thoughts off the top of my head. Any feedback from others is highly welcome!

TIA
Frank

CommentFileSizeAuthor
#1 DITA Task importer - Drupal 7.png97.15 KBfrank ralf

Comments

frank ralf’s picture

frank ralf commented
StatusFileSize
new DITA Task importer - Drupal 7.png97.15 KB
frank ralf’s picture

frank ralf commented

I've started evaluating the Feeds approach. For further information on using Feeds or Migrate for importing content see http://www.phase2technology.com/blog/incremental-imports-of-archival-con....

DITA XML Feed importer

For a basic DITA XML Feeds importer you need at least the following two modules:

  1. Feeds - the basic module
  2. Feeds XPath Parser - for parsing XML files

You can see the result of a first proof of concept in the below screenshot. I got some valuable pointers from these instructions for a DocBook XML importer.

DITA XML Feeds importer

frank ralf’s picture

frank ralf commented
Issue summary: View changes

I've also stumbled across some promising looking ontributed modules:

XML/XSLT related modules

  • XSL Formatter - A field formatter that runs given XML content (pasted data, linked URL or uploaded file) through a defined XSL stylesheet before rendering.
  • XML Field - Defines an XML field type. Provides an XML widget using CodeMirror (beginning with version 7.x-1.6). Provides XML related API functions for working with XML code. (Doesn't provide Feeds mapping yet.)
  • XML Content (only for Drupal 6) - XML Content is an XML entry, XSL transformation, and XML validation module that leverages PHP XML and XSL support, and the drupal output filter system. With XML Content, you can save XML inside the body of any node type, and have it display differently with XSL, or validated against a preconfigured schema.
  • XML Transform (sandbox project) - The XML Transform module enables you to store XML content in a node body and use the drupal built-in filter system to transform it with a pre configured XSLT stylesheet of your choice. It also provides optional XML input (on-submit) checks for well-formedness and schema-validation.
  • Feeds XSLT Pipeline Parser - This module provides a Feeds parser plugin implementing simple XSLT pipelines. XSLT is especially useful when importing document-style XML files.

Feeds enhancements

  • Feed Tamper - Feeds Tamper provides a small plugin architecture for Feeds to modify data before it gets saved.
  • Feeds Directory Fetcher - This is a very simple little module that provides a new feeds fetcher to the feeds module that fetches new files from a directory of files.
frank ralf’s picture

frank ralf commented
Title: The future of DITA and Drupal » The future of DITA integration for Drupal
tommiha’s picture

tommiha commented

The D7 port was done for our project and the DITA integration is working for us in our limited use (with some additional code very specific to our service). We have a CCMS for creating the DITA documentation and we use D7 just for publishing, so that is why the content creation features in the D6 module did not get ported.

Why we ended up porting the DITA import part of the DITA ingtegration module instead of using some generic XML importer is mainly that DITA integration has DITA OT in the middle providing support for our content even if we decide to change the DITA stucture. We don't need to set up a development project each time something changes, and the web developers don't have to study DITA (with us footing the bill). DITA OT is also where the validation steps in, it's not a feature of the module (as far as I have understood).

As to your points of what a DITA integration module should be able to do, I generally agree. I would add a requirement for mass import (you state 'single topics'), and the ablility to create menus out of the ditamaps and correctly connect the topics to the menu. Currently, our system imports the ditamaps into a taxonomy and the menu is created using Taxonomy Menu. I have been told that a simpler arrangement would be possible in D8.

frank ralf’s picture

frank ralf commented

Thanks for your feedback. You are right regarding the additional features. Feeds Directory Fetcher could provide mass import.

For creating menus from ditamaps I've been looking at hook_menu() which should be able to handle that with a custom module.

I hope to provide more information soon.

Kind regards,
Frank

tommiha’s picture

tommiha commented

Oh, and I would also add translations support into the mix, since that is the main driver for many DITA implementations (including ours). The import must add translations of DITA topics as node translations in Drupal as well as import translated menu items from translated ditamaps.

frank ralf’s picture

frank ralf commented

Thanks for the hint. That's becoming quite a wish-list ;-)

kagrainger’s picture

kagrainger commented

Following. Just putting together an e2e DITA solution for our docs and our shop already uses Drupal. I had originally thought about using the various Feeds modules that you mentioned in a comment, but then found the version control API and module, so thought I could do transforms locally, save source and output to a VCS, then import them all to our Drupal site. Obviously DITA integration would simplify and automate my life substantially. ;)

frank ralf’s picture

frank ralf commented

Hi Kate,

Thanks for your input and the pointer to https://drupal.org/project/versioncontrol.

Deciding which part of a DITA based webpublishing process (version controll, XSLT transformation etc.) could and should be handeled by Drupal is a difficult question. As you suggest I would run most of the transformations outside of Drupal (e.g. resolving cross references) so you get a 1:1 mapping of DITA files to Drupal nodes.

Cheers,
Frank

frank ralf’s picture

frank ralf commented

JFTR, related discussions in the Yahoo! DITA Users group:

frank ralf’s picture

frank ralf commented

Mark Hicks has created a new group at groups.drupal.org: DITA Tech Comm CMS.
Please join!

suzannewang’s picture

suzannewang commented

I am working on a dita online publishing project and I have tried the following approach:

1. convert dita files to html via dita-OT
2. Replicate ditamap via taxonomy vocabulary and terms.
3. upload html files via Import HTML Site Module.

The publishing procedure using this approach is sort of time consuming, however, the results are satisfying.
More details can be provided if anyone is interested.

Thanks,
Suzanne.