The Society for Technical Communication is an individual membership organization dedicated to advancing the arts and sciences of technical communication. It is the largest organization of its type in the world. Its 25,000 members include technical writers and editors, content developers, documentation specialists, technical illustrators, instructional designers, academics, information architects, usability and human factors professionals, visual designers, Web designers and developers, and translators - anyone whose work makes technical information available to those who need it.

The STC Toronto Chapter was founded in 1959 (then the Society of Technical Writers) and is the largest chapter in Canada.

About this Newsletter:

Single Source Publishing with XML and XSLT
by Alan Houser

XML is an exciting enabling technology that promises unlimited flexibility for single-source publishing and freedom from proprietary software tools. A critical part of any XML publishing workflow is the transformation of your organization’s XML source files to a publishable format. This article summarizes the capabilities of the W3C standard language XSLT for single-source publishing of XML documents.

Many authoring and publishing applications provide support for single-source publishing. For example, Adobe FrameMaker and Quadralay WebWorks Publisher allow you to publish your FrameMaker documents to HTML and other online formats. FrameMaker’s conditional text feature allows you to create and maintain content for multiple audiences in a single set of FrameMaker source files. FrameMaker text insets allow you to re-use content across multiple documents.

Several authoring tools provide some capabilities for single-source publishing, and many organizations have used these capabilities successfully over large document sets. However, the support for single-source publishing from off-the-shelf software is usually limited.

In my STC Intercom article, Managing and Delivering your Content as Data, I discuss today’s new business requirements, which demand much greater control over your content. For example:

“We need to publish our technical documentation in PDF and HTML, in our call-center’s knowledge database. We also want to publish repair procedures to remote wireless devices for our field technicians.”

“We publish our documentation in multiple formats. We also support several similar, but different products. We provide information to three different audiences: end-users, application developers and a select group of customers whom we provide with internal information about our products. We also localize our documentation in five languages.”

Fortunately, XML allows us to treat our document content as data objects that we can select, manipulate and publish as dictated by our business requirements, instead of by the capabilities of our tools. How do we manipulate our XML documents? We use a standard programming language defined by the World Wide Web Consortium called XSLT.

Authoring vocabularies versus publishing vocabularies

An XML vocabulary defines element names, element attributes, and element content that an XML document can contain. A valid XML document conforms to a given vocabulary, defined by an XML document type definition (DTD), or perhaps an XML schema.

Your organization will probably define or select an authoring vocabulary — a DTD that will insure that your documents have consistent markup. Common authoring vocabularies include DocBook and DITA, and many organizations create their own.

When you publish your XML, you will need to translate your XML from your authoring vocabulary to a vocabulary that your publishing application understands. For example, a Web browser does not know how to render DocBook XML markup tags. If you are publishing to a Web browser, you must translate your authoring vocabulary to a language the Web browser understands; specifically HTML or XHTML. If you are generating PDF from XML using XML standards, you will translate your authoring vocabulary to an XML markup language called XSL-FO, which is understood by devices that render XML documents as PDF.

Transforming XML documents

Because the transformation of XML documents is a critical part of nearly any XML-based publishing workflow, the World Wide Web Consortium (W3C) defined a programming language specifically for the purpose of transforming XML documents. This language is XSL  Transformations, commonly known as XSLT. XSLT and its companion language, XPath, allow you to select specific chunks of XML documents and transform those chunks to other XML vocabularies for publishing.

An XSLT program is commonly referred to as a stylesheet. The beauty of the XML publishing process is that the XML document contains the content; while the stylesheet specifies the formatting information for a particular output device. If another output format comes along, you can write another XSLT stylesheet to translate your authoring vocabulary to that device’s publishing vocabulary.

Getting started with XSLT

XSLT is a programming language, so some prior programming experience in any language is helpful. However, there’s no reason that XSLT can’t be your first programming language. You should have an understanding of XML syntax, because you are working XML documents (an XSLT stylesheet is an XML document!). You should also know the XML vocabulary of the documents you are working with, as well as the target vocabulary. For example, if you are transforming your XML documents to HTML for publishing, you need to know HTML!

There are many good resources available for learning XSLT. The following is just a small sample:

• My co-authored book, XML Weekend Crash Course, (John Wiley and Sons, 2001) provides an introduction to several XML-related technologies, including XSLT.
• Learning XSLT by Michael Fitzgerald, (O’Reilly and Associates, 2004)
• IBM’s DeveloperWorks site offers articles and tutorials on XSLT and other XML-related technologies (registration required)
• XSLT Development, public classroom training by Front Runner Publishing Solutions, Inc.

In summary, XML and XSLT provide entirely new capabilities for single-source publishing, beyond the capabilities that are currently available through off-the-shelf tools. XML publishing with XSLT is especially suited for meeting many of today’s particularly complex publishing requirements.

Alan Houser is president of Group Wellesley, Inc., based in Pittsburgh, PA, and provides XML, XSLT, and structured FrameMaker training in Canada through Front Runner Publishing Solutions, Inc. Alan invites comments on this article to arh@groupwellesley.com.

Alan and Front Runner will be presenting a course entitled 'Extensible Stylesheet Language: XSLT Development' on November 10th, 11th & 12th, 2004. Please call (416) 515-0155 or email Veronica for pricing details.

Next Article