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:
- the dit2jh transform that produces a viewable JavaHelp structure (use xt, or modify the stylesheet to use Saxon- or Xalan-specific
methods for "multiple output documents")
- the dit2htm transform that tests a newly-added localization method using the Lang external parameter (use Saxon or similar
engine which supports "external parameter passing")
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:
- Fully specialized all elements in topic.dtd (see file topic-spec.ent, which imbeds into topic.dtd)
- Added %univ-atts; to all remaining content and prolog elements.
- Moved comments to follow XML declarations in sample docs.
Discrete changes:
- Introduced new element comment into synph; also, added some link elements into its content model.
- Allowed %synparts.ph; within %xreftext.cnt;
- Allowed oper and delim within %sem.ph;
- Defined %synph.cnt; with extended content to enrich reftopic's pt
element
- Added @scale to table; @base to num; @country-code to currency;
- Added a parameter entity declaration for %topicreftypes; for use by @type assignments
- Added @othertype attribute to relational links that have fixed values for their @type
- Expanded the content model for %perils.cnt
;
- 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)
- Made the @id of topic implied instead of required (applications can check)
- Added implied @refid to rel (an alternate handle, so must be optional)
- Added the value 'sample' and other tokens to @role in %rel-atts;
- Added new @otherrole attribute
to %rel-atts; to support user-defined roles.
- Added the value 'content' to relgroup/@collection-type
- Added element desc into content group for relgroup
- Modified date/time content and attributes; will document guidelines for content
(use ISO!)
- Added select and input into more content models for more interactive contexts
- Increased the match of syntax diagram markup with that of IBMIDDoc (previous was BookMaster-like)
- 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.
- 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.
- 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:
-
Introduced element state to %data.ph; for defining non-binary conditions
- Introduced element boolean as another %data.ph; member
- Added a new topicref element. include is now deprecated for topic-level content reference
- Added new semantic table structure: semtable
Renamings:
- Renamed @ref to @bibref for cite and @linkref for link
; applied other -ref renaming consistently
- Renamed Required_Cleanup to required-cleanup (change to lowercase for consistency; change '_' to '-' for a reported problem with some parsers)
- 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:
- Removed apl, xph (obsolete phrase types)
Return to Top
Other DTD changes
task.dtd changes:
- 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.
- Added new @importance attribute to step and substep elements (based on same-named new attribute for " topic.li ".
- Changed the specialization base of stepresult, others from " topic.li " to " topic.liblock ".
Return to Top
meta_xml.ent changes:
- Moved audience, copyright up one level; made the occurrances for copyrdate "one or more"
- 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:
- Added a @scale attribute to table; allows overall text scaling, absolute or relative
- Added @colnum to entry (restoring a too-stringent "simplification" choice made earlier)
- Added @RowHeader to table as an accessibility aid; identifies row-major orientation of intended headings
(matches IBMIDDoc convention)
- Added desc element following title (for example, to support HTML accessibility)
- 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:
- Changed the top-level logic to allow more graceful fall-through (include/topicref now works).
- Added 'space' to @spec value in date, time, currency, other match patterns.
- Added the overlooked rules for literal and samp.
- Changed 'all' fig frame support from table border to an HTML div with CSS properties
(accessibility issue).
- Changed section title output from paragraph to div (tighter formatting).
- Added non-selection of title for section fall-through.
- 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:
- Added '$img-path' to generation of @src for mmobj template.
- Added 'label-placement' format macros for fig and table.
- Added 'link-top-section' to set whether or not to insert "return to top" links.
- Added specialization-enabled templates for glossary list and qalist.
- Added 'gen-user-header' and 'gen-user-footer' stubs for user overrides to stock output.
- $do-place-ing = 'yes' places an "Information Navigation Graphic" for section titles.
- Added NLS support via external strings.xml file.
See Here for an example of the use of this parameter.
New stuff:
- Updates for all element renaming in topic.dtd.
- Added flag and parm template rules to match upgrade to synph content model
.
- Renamed the common.xsl stylesheet to dit2htm.xsl (provide a naming pattern that allows for new outputs).
- Added dit2fo.xsl
to complement dit2htm.xsl.
- Added topicmerge.xsl to process new topicref element (same function as include, which may be deprecated).
- Added new "spec-only".xsl stylesheet; fully specialization enabled template for developing completely new applications.
- Added dtdfix1.xsl to help migrate ditd00-level source to dita01 level.
- 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:
- 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)
- This stylesheet produces an offset single column style similar to IBM documents.
- 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).
- 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:
- folder-example.xml in the samples directory. This example represents the grouping of topics in a simple sequence for on-demand applications
like "a-little-better-than-HTML" printing or for packaging for distribution to other writers.
- bkbook-example.xml in the samples directory. This example represents the reuse of topic-oriented content for book-like delivery applications,
such as PDF output or helpsets for conventional online help applications.
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.