Contents:
 Installing DITA
 Using DITA stylesheets
 Changes for this release
 Documents
 Sample documents
 Important closing words...

DITA Readme

This document describes the package content, change history, and some release notes for the package called "dita01.zip" on developerWorks (see the resources listed for Introduction to the Darwin Information Typing Architecture, or DITA).

Installing DITA

Please read and understand the IBM Darwin Information Typing Architecture Specification Agreement.
The DITA package has the following directory structure:
Dita contains docs, dtd, samples, and ss.  both docs and samples contain their own images subdirectories.
Use an unzip tool to extract the package into a location of your choice.

Using DITA stylesheets

These are examples of command-line invocations of popular XSLT engines to produce this particular document (DITA-readme.xml) as an HTML result:

Sample processing invocations
using Xalan-Java/ LotusXSL-Java:
c:\pkg\dita\docs>java org.apache.xalan.xslt.Process -in DITA-readme.xml -xsl ..\ss\dit2htm.xsl -out DITA-readme.html
using Xalan-C++/ LotusXSL-C++:
c:\pkg\dita\docs>testXSLT -in DITA-readme.xml -xsl ..\ss\dit2htm.xsl -out DITA-readme.html
using saxon:
C:\pkg\dita\docs>saxon DITA-readme.xml ..\ss\dit2htm.xsl > DITA-readme.html
using xt:
C:\pkg\dita\docs>xt DITA-readme.xml ..\ss\dit2htm.xsl > DITA-readme.html
using the "Lang" parameter with saxon:
C:\pkg\dita\docs>saxon DITA-readme.xml ..\ss\dit2htm.xsl Lang=sp > DITA-readme.html
The resulting output should exhibit the Spanish replacement text from the internationalization support file, strings.xml. This method is only a proof-of-concept demo... it is just one possible method of internationalization / localization support that might be used with XSLT-based production tools. Various stylesheets likely still contain literal English text that could be separated into localizable variables.
The DITA team has had good luck with most of the common XSLT transformation engines. Current engines do not all have completely interoperable features. Some of the non-interoperable features exercised in demo transforms include:
All DITA XML documents in this package have internal stylesheet links that support direct viewing with properly updated Internet Explorer 5. Internet Explorer 6 apparently supports both the draft version of XSLT and the the current XSLT 1.0 specification "out of the box."

Changes for this release

Following the initial public distribution of DITA in March 2000, IBM's "XML Workgroup" has been using the tools in several significant prototypes. Based on feedback both from external forums and these prototype activities, the Workgroup has provided some updates to the DITA tools in several areas.

Updates to the standard DTD (topic.dtd)

General changes:

  1. Fully specialized all elements in topic.dtd (see file topic-spec.ent, which imbeds into topic.dtd)
  2. Added %univ-atts; to all remaining content and prolog elements.
  3. Moved comments to follow XML declarations in sample docs.

Discrete changes:

  1. Introduced new element comment into synph; also, added some link elements into its content model.
  2. Allowed %synparts.ph; within %xreftext.cnt;
  3. Allowed oper and delim within %sem.ph;
  4. Defined %synph.cnt; with extended content to enrich reftopic's pt element
  5. Added @scale to table; @base to num; @country-code to currency;
  6. Added a parameter entity declaration for %topicreftypes; for use by @type assignments
  7. Added @othertype attribute to relational links that have fixed values for their @type
  8. Expanded the content model for %perils.cnt ;
  9. relgroup now nests in rel as well as in relgroup; the intent is to use it like a list item model for trees (may be problematic; this change is for testing only)
  10. Made the @id of topic implied instead of required (applications can check)
  11. Added implied @refid to rel (an alternate handle, so must be optional)
  12. Added the value 'sample' and other tokens to @role in %rel-atts;
  13. Added new @otherrole attribute to %rel-atts; to support user-defined roles.
  14. Added the value 'content' to relgroup/@collection-type
  15. Added element desc into content group for relgroup
  16. Modified date/time content and attributes; will document guidelines for content (use ISO!)
  17. Added select and input into more content models for more interactive contexts
  18. Increased the match of syntax diagram markup with that of IBMIDDoc (previous was BookMaster-like)
  19. Added a new @importance attribute to li and a few other block-level elements; this will replace the former @optreq attribute, which had no significance to li, the archetype of specializations which DO use @optreq.
  20. Added figbody/@layoutspec as a placeholder for working on some ways to organize mulitple elements within a figbody. This is not a proposed feature at this time.
  21. Added semtable/@relativecols as a placeholder for working on ways to ensure appropriate width controls for printed versions of a semantic table. There is no support for this feature in the stylesheets in this package.

New elements:

  1. Introduced element state to %data.ph; for defining non-binary conditions
  2. Introduced element boolean as another %data.ph; member
  3. Added a new topicref element. include is now deprecated for topic-level content reference
  4. Added new semantic table structure: semtable

Renamings:

  1. Renamed @ref to @bibref for cite and @linkref for link ; applied other -ref renaming consistently
  2. Renamed Required_Cleanup to required-cleanup (change to lowercase for consistency; change '_' to '-' for a reported problem with some parsers)
  3. For more consistency among title-like presentations, changed all label elements to title; changed all @label attributes to @title (except for syntax diagram markup, which is still under design)

Deleted elements:

  1. Removed apl, xph (obsolete phrase types)

Return to Top

Other DTD changes

task.dtd changes:

  1. Added an alternative content model for choices: either a description-level choice element, or an ifcond element that allows repeating sets of issue and outcome elements.
  2. Added new @importance attribute to step and substep elements (based on same-named new attribute for " topic.li ".
  3. Changed the specialization base of stepresult, others from " topic.li " to " topic.liblock ".

Return to Top

meta_xml.ent changes:

  1. Moved audience, copyright up one level; made the occurrances for copyrdate "one or more"
  2. Changed the @task attribute of xmeta to @job (to eliminate confusing the value of this attribute with the infotype of the current topic, as with the task dtd).

tbl_xml.ent changes:

  1. Added a @scale attribute to table; allows overall text scaling, absolute or relative
  2. Added @colnum to entry (restoring a too-stringent "simplification" choice made earlier)
  3. Added @RowHeader to table as an accessibility aid; identifies row-major orientation of intended headings (matches IBMIDDoc convention)
  4. Added desc element following title (for example, to support HTML accessibility)
  5. The DTD directory now includes an alternative table model, tbl_xch.ent, which is based on the full "Oasis Table Exchange Model".

Return to Top

Updates to the standard HTML output stylesheet (dit2htm.xsl)

Fixes:

  1. Changed the top-level logic to allow more graceful fall-through (include/topicref now works).
  2. Added 'space' to @spec value in date, time, currency, other match patterns.
  3. Added the overlooked rules for literal and samp.
  4. Changed 'all' fig frame support from table border to an HTML div with CSS properties (accessibility issue).
  5. Changed section title output from paragraph to div (tighter formatting).
  6. Added non-selection of title for section fall-through.
  7. Removed nearly all direct element matches so that matches can rely more fully on specialization (exceptions are some contextual things to deal with).

Override tweaks:

  1. Added '$img-path' to generation of @src for mmobj template.
  2. Added 'label-placement' format macros for fig and table.
  3. Added 'link-top-section' to set whether or not to insert "return to top" links.
  4. Added specialization-enabled templates for glossary list and qalist.
  5. Added 'gen-user-header' and 'gen-user-footer' stubs for user overrides to stock output.
  6. $do-place-ing = 'yes' places an "Information Navigation Graphic" for section titles.
  7. Added NLS support via external strings.xml file. See Here for an example of the use of this parameter.

New stuff:

  1. Updates for all element renaming in topic.dtd.
  2. Added flag and parm template rules to match upgrade to synph content model .
  3. Renamed the common.xsl stylesheet to dit2htm.xsl (provide a naming pattern that allows for new outputs).
  4. Added dit2fo.xsl to complement dit2htm.xsl.
  5. Added topicmerge.xsl to process new topicref element (same function as include, which may be deprecated).
  6. Added new "spec-only".xsl stylesheet; fully specialization enabled template for developing completely new applications.
  7. Added dtdfix1.xsl to help migrate ditd00-level source to dita01 level.
  8. Added some examples of delivery context stylesheets. These will be documented as time permits through DITA's forum on developerWorks (DITA forum)
.

Return to Top

Features of the new FO output stylesheet (dit2fo.xsl)

Notes:

  1. This stylesheet is a demo only, developed to begin exploring production issues with the XSO FO method of printing. Many of the concerns may be only temporary as the various vendors increase their support. Nevertheless, among the many concerns for enterprise publishing are:
    • Interoperability of a single stylesheet between different FO engines
    • Extensive language support
    • Extensive font support
    • Extensive imbedded graphics support
    • Localization methods for all targeted languages
    • Quality of book-like features using XSL-based methods of construction and rendering
    • Common function of any resulting deliverables across renderers used in all languages (PDF bookmarks, for example)
  2. This stylesheet produces an offset single column style similar to IBM documents.
  3. This stylesheet may not work with all current FO formatters. XSL FO formatters that we were aware of during development included FOP, Antenna House, XEP, and XSL Formatting Composer (IBM).
  4. Fonts refer only to those available in the base Adobe PDF specification.

Return to Top

Documents

This package contains a "docs" directory that contains documentation for core features of DITA.
DITA-readme.xml This document (DITA Readme)
DITA-rm.xml The DITA "road map" article from developerWorks.
DITA-dsf.xml The DITA specialization architecture explanation from developerWorks.
DITA-faq.xml The DITA FAQ article from developerWorks.
DITA-onomasticon.xml A pronouncing gazetteer for DITA, and an example of term-to-glossary linking.
DITA-disclosures.xml An explanation of the DITA concept of "progressive disclosure" mechanisms for user assistance.
DITA-cmdef.xml An explanation of content model definitions for DTD-based schemas, a mechanism used to define DITA content models
DITA-semantics.xml An explanation of a proposed method of associating semantics with the DITA architecture. The topic dtd features these attributes for possible use by future applications.

Hint: The elementref specialization in the dtd directory suggests that support is in place for such things as, say, a language reference. Watch the DITA forum for announcements about additional materials and for explanations of new features in this package.

Sample documents

This package contains a "samples" directory with documents that illustrate design features of DITA.
anapi-(various files).xml Demonstrates specialization from reftopic base.
exprep.xml Demonstrates specialization from task base.
semtable-demo.xml Demonstrates the new semantic table structure (both major and minor axis headings) and another example of using classdef for inheritable headings.
classdef-demo-man.xml Demonstrates the classdef mechanism for defining inheritable titles (for any element that has a @classif attribute) in a generic reftopic. This example demonstrates both a "single use" example and an example which can be used as a template for a set of related descriptions processed together.
The directory also includes documentation for the sample bkbook.dtd that extends the basic dit2fo.xsl transform for book-like structures.
For examples of aggregation of multiple topics into "delivery context" structures, see:
These documents use the topicref element within different "delivery context" dtds to organize information for reuse. The current processing architecture involves a two-pass method: first create a fully-resolved result instance of the indicated topic references within the delivery context, and then use appropriate stylesheets on the result instance for extended renderings.
For folder-example.xml, use the merge.xsl stylesheet to produce an intermediate, validating folder instance, then use fld2fo.xsl to render a result FO instance for quick printing.
For bkbook-example.xml, use the topicmerge.xsl stylesheet to produce an intermediate, validating bkbook instance, then use bkbook8x11.xsl to render a result FO instance as a book-like PDF.
These stylesheets use the XSLT import mechanism with overlay template rules to provide the processing context for default topic presentation.

Important closing words...

The wisdom in the IBM Darwin Information Typing Architecture Specification Agreement included with this package is very important. The DITA design is progressing, but still quite evolutionary. The DITA team encourages you to use the dtds and tools and to help us advance the design, with the understanding that this package–as a prototype activity–is unsupported. As with any new technology, always do an appropriate risk assessment and ensure that you have a backup plan.
Now, specialize away!
Don Day
dond@us.ibm.com
IBM Corporation, Austin, Texas

Related Information

Roadmap for the Darwin Information Typing Architecture
Specialization in the Darwin Information Typing Architecture
DITA User Forum