Cooking with XML:

From Document Design to Delivery

Presented to Bay Area Publications Managers Forum

by Paul Tyson

Tuesday 2002-02-26 18:30/20:00

paul@precisiondocuments.com

Cooking with XML

From Document Design to Delivery

Introductory remarks
How to XML
Managing XML

Introductory remarks

What I know about you
What you should know about me
XML and data quality

You are publications managers and editors who want to know more about how XML can help you produce publications. You've heard the sales talks and the media buzz, but need to see how it really works.

I worked in aircraft technical publications for eighteen years. For the last ten years I have worked with SGML systems for the creation and delivery of technical publications.

Most of the benefits of XML come from improvements in data quality. Higher quality data leads to process and product improvements. Historically, quality in publications is determined by the appearance and usefulness of the final documents. But the visual rendition of a document is derived from electronic data, so it is an inescapable fact that characteristics of the data will affect the appearance and behavior of the documents in some way.

A good introduction to data quality is Data quality for the information age, by Thomas C. Redman.

Document design

What & why of document design
Deliverables of the design process
Methodology
Document design exercise

What & why of document design

Explicit description of document type
Planning is required to meet all needs

Every document has some identifiable structure. The structure is explicit or implicit. Every document is an instance of a general class of documents (possibly the only instance). In other words, we can always imagine another document similar to the one in front of us that exhibits the same features.

The details of the structure don't matter. You select characteristics to define document structure based on your needs. Only by planning and analysis can you identify the required components of your document structure.

Deliverables of document design

Document type definition (DTD)
Notes, diagrams, explanations

A DTD is a set of declarations, using a specified syntax, that identifies the elements in the document. It also specifies the allowable relationships among elements.

Document design is much more an exercise in thinking than in writing code. A DTD does look vaguely like computer code--and, in reality, it is--but that's what it takes to make ourselves understood to the machine. Just as importantly, we must make ourselves understood to our coworkers, supervisors, customers, implementors, and successors. And plain old words and pictures are invaluable.

Document design methodology

People: SMEs, authors, editors, users
Activities:
- Gather requirements
- Analyze documents
- Create document model
References:
- Maler, Eve and El Andaloussi, Jeanne. Developing SGML DTDs: from text to model to markup.
- Megginson, David. Structuring XML documents.
- Industry standard DTDs
Tools: Flipchart, whiteboard, notecards, . . .

The document design process is driven by two imperatives:

Distinguish things that are different.
Connect things that are related.

The things to be distinguished and connected are document components. You should keep a very broad notion of "components" while designing documents, because the things you can describe with structural markup go beyond what you can actually see in a document.

There are three ways to indicate relationships using structural markup:

Hierarchy
Sequence
Semantics

In other words, you can connect things by:

Specifying the allowable parents and children for each type of component.
Specifying what types of things can appear before or after them.
Specifying how some application (computer or human) can relate one type of thing to another.

Hierarchy is the most definite and robust indication of relationship; sequence is the easiest but weakest; semantics is the most complicated and flexible method.

Visual document design

Near&Far Designer
XML Authority

Document creation

Freedom of choice!
Methods for creating documents:
- Automated conversion from non-XML data
  - Word processing format
  - Database
- Interactive editing (native XML)
Demo XML-aware editing applications
- emacs psgml mode
- Arbortext Epic
- SoftQuad XMetal

Converting non-XML data

Frequency:
- One-time only (legacy conversion)
- Repeatable production process
Conversion techniques:
- Map word processing styles (or other proprietary notation) to XML
- Pattern detection
- Database reports

Pros	Cons
Less disruptive to writers Lower software costs Appropriate for large-scale one-time conversion of legacy data Appropriate for database records such as parts lists and tables	Requires highly consistent input Costly to develop automation rules for complex or irregular data For recurring process, must find and fix defects in XML after each batch Does not significantly improve document data quality

Interactively creating XML documents

Essential features:
- Context-sensitive markup insertion
- Validation
Helpful features:
- Speedy edit features
- Display document structure
- Styled display of content
- Graphics display
- Interface customization
- Connectability to document repository
- Scripting extensions

Selecting an XML editor

How "clean" is the saved XML?
Match features of editor to requirements of your production system.
Standalone documents or document collections?
Editor screen styles: standard or proprietary? reusable?
Setup procedures for new document types

Using XML to represent your documents lets you become more document-centric than application-centric. When documents instead of applications become the center of your universe you will have more options and capabilities.

Applying Style

The need for style
Methods for describing and applying style:
- Direct association
- Transformation
- Embedded formatting specifications

The need for style

XML is a way to divide a stream of characters into meaningful pieces.
By omitting formatting information, we:
- Simplify many document processing problems
- Gain more control of formatting operations
Formatting requires a vocabulary to describe:
- Character glyphs and their properties
- Line-breaking and page layout characteristics
- Placement of graphic elements
- Other formatting specifications
How to get from one language (structural markup) to the other (formatting specifications)?

Style methods

	Direct Association	Transformation	Embedded formatting
Standard (ISO, MIL, or W3C)	CSS FOSI	DSSSL XSLT	XSL-FO
Nonstandard or Proprietary*	Frame+SGML Wordperfect+SGML Xyenterprise XPP ________________	Balise Omnimark ________________	MIF RTF TeX ________________
* Specifications for these languages and formats were not produced by a recognized standards-making organization.

Standard style languages do not produce any different results than proprietary or nonstandard ones. They can, however, simplify the process of specifying and applying style. Styles and transformations expressed in a standard language are usually more portable and reusable than others.

Style by direct association

CSS: Cascading Style Sheets
- W3C Recommendation (CSS2, 1998-05-12)
- Originally created for HTML, but has been extended for XML
- Includes formatting properties for visual, aural, and tactile media
- Browser support varies
FOSI: Formatted Output Specification Instance
- US military specification (MIL-PRF-28001)
- Earliest standard for formatting SGML
- Implemented in Arbortext Epic suite

CSS and FOSI


<e-i-c gi="para">
 <charlist>
  <font
      size="12pt"
      weight="medium">
  <indent leftind="0.5in">
  <presp nominal="6pt">
  <textbrk startln="1">
</e-i-c>

	CSS	FOSI
1	para {	<e-i-c gi="para">
2		<charlist>
3		<font
4	font-size: 12pt	size="12pt"
5	font-weight: normal	weight="medium">
6	start-indent: 0.5in	<indent leftind="0.5in">
7	space-before: 6pt	<presp nominal="6pt">
8	display: block	<textbrk startln="1">
9	}	</e-i-c>

Select this rule for elements named para.
Begin a charlist element (FOSI only).
Begin a font element (FOSI only).
Set the font size to 12 points.
Set the font weight to normal. In FOSI, close the font element begin tag.
Set the start indent to 0.5 inches.
Set the space before this block to 6 points.
Make this a block-like formatting object.
End the style rule.

Limitations of direct association

Difficult to specify complex formatting requirements
Stylesheet author has little control over processing
Dynamic capabilities are limited

If you view a formatted document as a tree-like structure, you can solve the problem using a general method of tree transformation.

Style by transformation

DSSSL: Document Style Semantics and Specification Language
- ISO standard (ISO/IEC 10179:1996)
- Defines processing model and language for tree transformations.
- Built on a formal data model called "groves"
- Major implementations are OpenJade (open source) and DSSSLprint (by NextSolutions, in Japan)
XSLT: XSL Transformations
- W3C Standard (version 1.0, 1999-11-16)
- Processing model and language structure similar to DSSSL, but syntax is XML
- Less formal, general, and powerful than DSSSL
- Several implementations, including free, open source, and commercial ones

DSSSL and XSLT


<xsl:template match="para">
  <fo:block
    font-size="12pt"
    font-weight="normal"
    start-indent="0.5in" 
    space-before="6pt">
      <xsl:apply-templates/>
  </fo:block>
</xsl:template>

	DSSSL	XSLT
1	(element para	<xsl:template match="para">
2	(make paragraph	<fo:block
3	font-size: 12pt	font-size="12pt"
4	font-weight: 'normal	font-weight="normal"
5	start-indent: 0.5in	start-indent="0.5in"
6	space-before: 6pt	space-before="6pt">
7	(process-children)	<xsl:apply-templates/>
8	)	</fo:block>
9	)	</xsl:template>

Select this rule for elements named para.
Create a block formatting object.
Set the font size to 12 points.
Set the font weight to normal.
Set the starting indent to 0.5 inches.
Set the space before this block to 6 points. Close the fo:block begin tag.
Process the children of the current element. Formatting objects produced by processing the children can inherit certain characteristics assigned by this transformation rule.
Close the block formatting object.
Close this node transformation rule.

The key to the power of this method is shown on line 7 of this example. This gives the stylesheet author full control over processing at each node in the source document tree. Normally, you would process the children of the current element. But you can choose instead to process selected children, or you can process any other element in the document in any way you want. You can process nodes based on the content or structure of the source document.

It is hard to overstate the power of this technique. There are few document processing problems that cannot be solved with a tree transformation specification.

Embedded formatting specifications

XSL: Extensible Stylesheet Language (XSL-FO)
- W3C Standard (version 1.0, 2001-10-15)
- Defines XML representation of formatting characteristics
- Builds on CSS formatting properties
- A few implementations, including free, open source, and commercial ones

XSL-FO


<fo:block
    font-size="12pt"
    font-weight="normal"
    start-indent="0.5in"
    space-before="6pt">
  [element content]
</fo:block>

	XSL-FO
1	<fo:block
2	font-size="12pt"
3	font-weight="normal"
4	start-indent="0.5in"
5	space-before="6pt">
6	[element content]
7	</fo:block>

Create a block formatting object.
Set the font size to 12 points.
Set the font weight to normal.
Set the starting indent to 0.5 inches.
Set the space before this block to 6 points. Close the fo:block begin tag.
The content of this element will be formatted according to the specified characteristics (including any inherited characteristics).
Close the block formatting object.

Old SGML hands learned to rigorously separate logical structure from formatting information. Now we have an entire document type devoted to expressing formatting information!

But an even more important principle of SGML is that you can design a document type to describe anything you want--including formatting specifications. Even if XSL-FO doesn't include all the formatting characteristics you need, you can easily extend it.

Delivery options

XML+CSS in a browser
XML+XSLT -> HTML (or XML) in a browser
XML+XSLT -> non-XML (word processor, WinHelp, etc.)
XML+XSLT -> XSL-FO -> PDF,PostScript
XML+FOSI -> PDF,PostScript
XML+DSSSL -> PostScript, PDF, MIF, RTF, XML, XSL-FO
SGML -> XML . . .
SGML+DSSSL -> . . .

XML + CSS in a browser

Advantages	Disadvantages
Simple--easy to develop and implement	Simple--doesn't support complex formatting requirements or dynamic processing
Flexible: use in standalone, file-based system or server-controlled system	Not all browsers consistently support XML and CSS.

XML + XSLT to HTML

Advantages	Disadvantages
Use built-in HTML semantics	Limited by HTML
Moderately easy to develop and implement	Not all browsers consistently support HTML and CSS
Full transformation capabilities of XSLT	Server-based or other external process must be used for just-in-time transformations.

XML + XSLT to multiple outputs

Advantages	Disadvantages
Single-source documents and style information	Requires higher investments in document design, data creation, and transformation specifications
Flexible--works with any production or delivery method
Easy to maintain, modify, and troubleshoot

Managing XML

Skill sets
Architectural considerations
Cost of implementation

Required skill sets

Everyone:
- Principles of structural markup
- Familiarity with basic syntax of XML
- Knowledge of your document types
Writers:
- Competence with editing application
Style specialist:
- Vocabulary, principles, and methods of style specification
- CSS, XSL-FO
Transformation specialist:
- XSLT or DSSSL
- One or more XSLT engines
Application specialist:
- Expert knowledge of XML editing application

Deciding on architecture

Focus first on good document design and high-quality data
Develop pilot applications
- Prototype with available tools
- Most processes will scale well
- Beware of break points for expensive processes
Anticipate requirements as completely as possible
Design for change and growth
Beware of "solutions"

Cost of implementation

Nonrecurring costs

Training: 20-40 hours/person
Editing Software: up to $1,300.00/seat

DTD development (80 elements):

Document design	35-440 hours
Application setup	40-80 hours
Stylesheet creation	80-120 hours
TOTAL:	155-640 hours

Overall effect on production: should reduce hours/page, but additional features could disguise this
Benefits: data quality, flexibility, control

See $GML: The billion dollar secret, by Chet Ensign, for case studies of successful SGML implementations.

Cooking with XML:

From Document Design to Delivery

Presented to Bay Area Publications Managers Forum

by Paul Tyson

Cooking with XML

From Document Design to Delivery

Introductory remarks

Document design

What & why of document design

Deliverables of document design

Document design methodology

Visual document design

Document creation

Converting non-XML data

Interactively creating XML documents

Selecting an XML editor

Applying Style

The need for style

Style methods

Style by direct association

CSS and FOSI

Limitations of direct association

If you view a formatted document as a tree-like structure, you can solve the problem using a general method of tree transformation.

Style by transformation

DSSSL and XSLT

Embedded formatting specifications

XSL-FO

Delivery options

XML + CSS in a browser

XML + XSLT to HTML

XML + XSLT to multiple outputs

Managing XML

Required skill sets

Deciding on architecture

Cost of implementation

Thank you!

Paul Tyson

paul@precisiondocuments.com

408-375-8851

Precision Documents

www.precisiondocuments.com