STC Intercom, September/October 2009
XML is rapidly becoming part of the required knowledge for technical communicators. This article discusses the three most important reasons that you should consider XML: automation, baseline architecture, and consistency.
Download the PDF 
(144K)
My latest XML Strategist article, “The ABCs of XML,” is available as a PDF file (144K). This article was originally published in the September/October 2009 issue of Intercom.
The technical side of XML is not much more difficult than HTML; if you can handle a few HTML angle brackets you can learn XML. […] If […] you don’t like using styles and
prefer to format everything as you go, you are going to loathe structured authoring.Â
Just trying to make sure that there are no surprises. The article itself is a very basic introduction to the principles that make XML important for technical communication: automation, baseline architecture (sorry…I had problems with B), and consistency.
In addition to a gratuitous (and entertaining) swipe at “noisome” DITA “fanboys,” Roger Hart argues that we need to reconsider the disadvantages of automated formatting:
The thing is, [separation of content and formatting has] all been taken rather stridently to heart in certain quarters, leading to a knee jerk reaction whenever author-controlled formatting/pagination/lineation is mentioned as anything other than bleak, sulphurous devilry. This is twaddle. […]
Uncertainty in meaning is anathema to user intelligibility. If we’re going to make sure we’re not writing poetry, there’s definitely value in having poetry’s level of control over semantic blocks.
Of course, it’s fully possible that this is an expensive distraction.
Possible? It’s definitely expensive. It’s possible that it’s a distraction.
I think Hart perhaps unintentionally put his finger on the real issue: value. How much value (in the form of improved comprehension) is added to a technical document when you are able, in the words of commenter Brian Harris, to “lovingly handcraft” each page?
How much value (in the form of cost avoidance) is added to an organization when you are able to spit out a reasonably formatted document in a few minutes?
Actually, I have a different question. How far should we take this argument? Here’s an example of the pinnacle of handcrafting:
Compared to the Book of Kells (above), the Gutenberg Bible looks quite pedestrian:
You can just imagine the scribes with their quills, lapis, gold leaf, and other implements muttering, “That Gutenberg and his noisome fanboys. He can’t even render two colors without our help. Poser. It’ll never last.”
Formatting automation removes cost from the process of creating and delivering content. For technical documents that change often and are perhaps delivered in multiple languages, it removes a lot of cost. Let’s assume that handcrafted pages can improve ease of reading and comprehension with careful copy-fitting and adjusted spacing (Hart’s article mentions “headings, line breaks, intra-word, etc”). This increases the cost of the content.
What happens when content is expensive? Fewer people get to see it.
I think we can all agree that e-books offer none of the typographic sophistication in question here. Bill Gates (yes, that Bill Gates)Â wrote in 1999:
It is hard to imagine today, but one of the greatest contributions of e-books may eventually be in improving literacy and education in less-developed countries. Today people in poor countries cannot afford to buy books and rarely have access to a library.Â
Essentially, we can produce documents inexpensively and give more people access to them as a direct result of lower cost, or we can climb on our typographic high horse and whine about word spacing.
I’m with the noisome fanboys.
Recently I had to write some XSL transforms in which I wanted to ignore the DOCTYPE declarations in the source XML files. In one case, I didn’t have access to the DTD (and the files wouldn’t have validate even if I did). In the other case, the XML files were DITA files, but I had no need or interest in validating the files; I simply needed to run a transform that modified some character data in the files.
In the first case, I ended up writing a couple of SED scripts that removed and re-inserted the DOCTYPE declaration. By the time I encountered the second case, I wanted to do something less ham-fisted, so I started investigating how to direct Saxon to ignore the DOCTYPE declaration.
My first thought was to use the -x switch in Saxon. Perhaps I didn’t use it correctly, but I couldn’t get it to work. Even though I was using a non-validating parser (Piccolo), Saxon kept telling me that the DTD couldn’t be found.
I went back to the drawing board (aka Google) and found a note from Michael Kay that said, “to ignore the DTD completely, you need to use a catalog that redirects the DTD reference to some dummy DTD.” Michael provided a link to a very useful page in the Saxon Wiki that discussed using a catalog with Saxon. After a bit of experimentation, I got it working correctly. In this blog post, I’ve distilled the information to make it useful to others who need to ignore the DOCTYPE in their XSL.
Before I describe the catalog implementation, I’d like to point out a simple solution. This solution works best when a set of XML files are in a single directory and all files use the same DOCTYPE declaration in which the system ID specifies a file:
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
However, there are many cases in which this simple solution doesn’t work. The system ID (“topic.dtd” in the previous example) might specify a path that cannot be reproduced on your machine…or the XML files could be spread across multiple directories…or there could be many different DOCTYPEs…or…
In these cases, it makes more sense to set up a catalog file. To specify a catalog with Saxon, you must use the XML Commons Resolver from Apache (resolver.jar). You can download the resolver from SourceForge. The good thing is, if you have the DITA Open Toolkit installed on your machine, you already have a copy of the resolver.jar file. The file is in %DITA-OT%libresolver.jar. You specify the class path for the resolver in the Java command using the -cp switch (shown below).
The resolver requires you to specify a catalog.xml file, in which you map the the public ID (or system ID) in the DOCTYPE declaration to a local DTD file. The catalog.xml file I created looks like this:
<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<public publicId="-//OASIS//DTD DITA Topic//EN" uri="dummy.dtd"/>
<public publicId="-//OASIS//DTD DITA Concept//EN" uri="dummy.dtd"/>
<public publicId="-//OASIS//DTD DITA Task//EN" uri="dummy.dtd"/>
<public publicId="-//OASIS//DTD DITA Reference//EN" uri="dummy.dtd"/>
</catalog>
Putting it all together, I created a DOS batch file to run Java and invoke Saxon:
java -cp c:saxon9saxon9.jar;C:DITA-OT1.4.3libresolver.jar ˆ
-Dxml.catalog.files=catalog.xml ˆ
net.sf.saxon.Transformˆ
-r:org.apache.xml.resolver.tools.CatalogResolver ˆ
-x:org.apache.xml.resolver.tools.ResolvingXMLReader ˆ
-y:org.apache.xml.resolver.tools.ResolvingXMLReader ˆ
-xsl:my_transform.xsl ˆ
-s:my_content.xml
The switches following the Java class (net.sf.saxon.Transform) are Saxon switches.
Note, I’m using Windows (DOS) syntax here. If you are using Unix (Linux, Mac), separate the paths in the class path with a colon (:) and use the backslash () as a line continuation character.
When you run Saxon this way, you’ll notice two things: first, Saxon doesn’t complain about the DTD (yay!), but secondly, there is no DOCTYPE declaration in the output. I’ll address how to add the DOCTYPE declaration back to the output XML file in my next blog post.
Recently, I ran across an article by Rob Cherny in Dr. Dobb’s Journal. He suggests that the added features in HTML 5 combined with an end to the development of XHTML point to a brighter standards-based future. He sees closed solutions like Flash, Silverlight, and JavaFX being supplanted directly by HTML 5 code. His view is that the web owes its success to standards.
It’s tempting to agree. Standards certainly allow for collaborative growth. Though I’m not the least bit convinced that collaborative growth is the foundation of the web’s success. I believe that the web’s incredible success is really traceable to the simplicity and flexibility of HTML. Each new version takes us further from that simplicity.
Through the browser war years we saw the impact of new features in HTML—incompatibility among browsers. My sense is that the success of Flash is largely due to the fact that Adobe owns both ends of the problem. They create the tools that generate Flash code as well as the viewer. Web developers can pretty much assume that what they see, when they build a Flash-based solution, is what the end user will see.
I fear that we will head right back to the bad old days if HTML 5’s complex capabilities are widely employed. I suspect that ‘wait and see’ will last a pretty long time. I have other concerns about HTML 5—more on that later. What do you think—will your organization take advantage of these new capabilities as soon as they are available?
For its 2010 catalog, IKEA used Verdana font instead of the customized Futura it’s used for years. To say people noticed the switch would be an understatement:
“Ikea, stop the Verdana madness!” pleaded Tokyo’s Oliver Reichenstein on Twitter. “Words can’t describe my disgust,” spat Ben Cristensen of Melbourne. “Horrific,” lamented Christian Hughes in Dublin. The online forum Typophile closed its first post on the subject with the words, “It’s a sad day.” On Aug. 26, Romanian design consultant Marius Ursache started an online petition to get Ikea to change its mind. That night, Verdana was already a trending topic on Twitter, drawing more tweets than even Ted Kennedy.
As a fan of IKEA and its products, I can understand the reaction. If you showed me a page out of an IKEA catalog with just text and prices (and no pictures or funky product names, of course!), I could tell you in a heartbeat that the content was from IKEA.
Verdana may be easier to read if you’re looking at the IKEA catalog online, but that font lacks the designer-y flair of Futura. Because IKEA is known for its affordable cutting-edge design, Verdana just doesn’t seem to quite fit the bill.
This situation reminds me of a comment a friend made about a failed hotel in Raleigh, NC. He said, “Did you see the awful Brush Script on the hotel’s sign? Those people clearly didn’t know how to run a business.” I doubt the Brush Script killed the hotel, but that bad design decision gave my friend (and probably many others) a very unfavorable impression about the company.
Earlier this week, Sarah O’Keefe and I were doing some web research and came upon a web site that used Comic Sans. My reaction to that site was less than positive. I loathe Comic Sans, and I find it hard to take any company seriously that uses a font that emulates text in a comic book.
A company’s use of fonts can become iconic–think about the fonts used by Coca-Cola and FedEx in their logos, for example. Font choice does have an effect on how people perceive content, a product, or a company.
I don’t think reactions to fonts are limited to just those who work in publishing and design. No snobbery here at all. (But if noticing fonts makes me a card-carrying font snob, you better believe that card would have no Comic Sans on it.)
For more about the impact of fonts, check out the documentary Helvetica:
After my summer of complaints and criticism of STC and its various issues, I was more than a little surprised to be asked to manage the Design, Architecture, and Publishing track for next year’s STC Summit.
Hoist on my own petard (my obsession with Wordnik continues)…what could I do but agree. Or, go into exile.
Several of the other conference organizers are people I know quite well:
(I’m sure that the other track managers are excellent as well, but I don’t know them personally.)
Here is the description of the Design, Architecture, and Publishing track:
Choice of appropriate design and architectures can improve the efficiency, usability, and quality of an organization’s technical publishing. This track explores issues in information design and system architectures for publishing, with particular emphasis on systems and solutions for organization-wide publishing. Suggested session topics include:
- Visual communication, integrating text and graphics, page layout
- Single-source publishing, for multiple delivery formats, multiple purposes, and multiple audiences
- Methodologies and solutions for content management
- Comparing and selecting delivery formats
- Issues in structured authoring and publishing, including migration, design, and deployment
- XML-based publishing
- Using industry-standard publishing architectures, such as DITA
- Accommodating localization workflows in the publishing process
- Moving unstructured content to structure
And now I need your help in two areas:
Some notes on this year’s process:
If you have questions, leave a comment or contact me. I look forward to seeing lots of compelling proposals.
(or should that be “Liberated typoes?”)
We have opened up free access to two of our white papers:
These used to be paid downloads.
Why the change of heart? Most of our business is consulting. To get consulting, we have to show competence. These white papers are one way to demonstrate our technical expertise.
(By this logic, our webcasts should also be free, but I’m not ready to go there. Why? We have fixed costs associated with the webcast hosting platform. Plus, once we schedule a webcast, we have to deliver it at the scheduled time, even if we’d rather be doing paying work. By contrast, we can squeeze in white paper development at our convenience.)
What are your thoughts? We are obviously not the only organization dealing with this issue…
If you are reading this, then we have succeeded in migrating our web site over to WordPress.
Of course, the process of managing our own content always takes a back seat to working with our customers’ content, so the process took longer than you might expect.Â
We did learn a couple of things, most of which should sound awfully familiar if you are working on your own content strategy:
But I hope you like the new site and blog. Please poke around and leave us feedback.
by Sheila Loring
DITA XML is of little use to readers unless it’s converted to some kind of output. The DITA Open Toolkit (DITA OT) provides transforms and scripts that convert DITA to PDF output and a long list of other formats.
Producing PDF output from DITA content can be challenging. DITA XML is converted to an XSL-FO file, a combination of content and formatting instructions. You must know XSL-FO to customize the PDF, even just to add simple content such as headers and footers, logos, and so on.
To forgo the programming, you can choose a page layout or help authoring tool, but these tools also have pitfalls. Page layout programs have varying degrees of DITA support. Help authoring tools let you style the PDF through CSS, but you can’t fine-tune page layout as you can in page layout programs.
These are just a few examples we discuss in our white paper “Creating PDF files from DITA content.” Read the white paper online (in HTML or PDF).
