FrameMaker, DITA, xrefs: I could tell you, but…
Modifying FrameMaker cross-reference formats: it’s basic and one of the cool things about FrameMaker. But not if you’re editing DITA files using FrameMaker 9 or 10.
Dita
Vector images and the DITA Open Toolkit
Rendering vector images (such as line art or charts) for PDF output through the DITA Open Toolkit can be tricky. You would think that an exported GIF of a vector image would display beautifully in the PDF—but you would be wrong.
A simple use case for DITA conkeyrefs
I have struggled to understand the keyref and conkeyref features added in DITA 1.2.
It wasn’t until we started applying them to our proposal workflow that I finally understood them. I hope this use case also helps others.
The devolution of DITA editors
Most of the DITA work that we do at Scriptorium is “full-on” implementation. That is, our customer decides to move their content from [something that is not DITA] to a DITA-based system. There are variations on the theme, of course, but nearly all of our customers are concerned about managing localization costs and increasing content reuse.
Calculating the ROI of DITA
The Darwin Information Typing Architecture (DITA) provides an XML architecture for technical communication. Although implementing DITA is likely to be faster and easier than building your own XML architecture from the ground up, DITA is not suitable for everyone.
It’s not easy being…clean
This article was originally published in STC Intercom in March of 2011.
A standards-based workflow is challenging. This article discusses the issues with DITA (an XML standard for technical communication content) and XSL-FO (Extensible Stylesheet Language Formatting Objects, a standard used to create PDF from XML (http://www.w3.org/standards/xml/publishing).
Webcast: DITA Best Practices
In this webcast hosted by Scriptorium, author Tony Self discusses his new book, The DITA Style Guide, and how it fits into a DITA workflow.
Webcast: Attractive DITA: it is possible!
In this webcast, Sarah O’Keefe discusses the challenges of getting attractive output from DITA and demonstrates Scriptorium’s approach to web-based help and PDF.
Webcast: Calculating the ROI for XML and DITA topic-based authoring
In this webcast, Sarah O’Keefe discusses how to calculate the return on investment of an XML/DITA implementation for technical content.
If you are considering XML and DITA, but are trying to figure out whether you can justify the cost and effort, this session is for you.
The state of structure, 2011
Happy New Year!
In early 2009, we did a rather extensive survey on structured authoring. We asked about plans to implement structured authoring, existing implementations, biggest mistakes, and the like.
Conquering the Mark of the Web (DITA OT version)
Whew! Now I know how St. George felt after slaying the dragon. I’ve defeated the Mark of the Web beast and have lived to tell about it.
Adding new languages to the DITA Open Toolkit
The DITA Open Toolkit comes with support for many languages, but you can always find one that is not yet covered. Fortunately, adding a new language does not require any strange incantations.
Webcast: XSL techniques for XML-to-XML transformations
In this webcast, Simon Bate leads viewers through the key steps in using XSL (extensible stylesheet language) to perform XML-to-XML conversions, a process that differs from more traditional XML-to-PDF and XML-to-HTML conversions.
Anyone can write
This article was originally published in STC Intercom in September/October of 2010.
“Anyone can write.” How many times have you heard that tired cliché? And how did it ascend to a cliché? It’s pretty clear to me that most people are terrible writers. When someone says, “Anyone can write,” they actually mean, “Our writing standards are so low that anyone can meet them.”
Webcast: Extracting deliverables from DITA
In this webcast, Sarah O’Keefe of Scriptorium surveys DITA’s publishing options and weighs their practical implications.
Using Ant to find a needle in a haystack
Many content management systems (CMSs) take over the responsibility of file naming. For the most part, this is fine and is actually necessary for maintaining cross-references and conrefs within the CMS. When you use the CMS to build a DITA map, the CMS uses its own names in the <topicref> elements.
Tech Tips: Quick Word to DITA table conversion
The other day I had to convert a large table from Word to DITA. I started looking at Word XML output and thought about transforming it with XSL (which I have done in the past), but that seemed to be too much trouble for this document. Then I remembered a technique an old SQL coder showed me for loading large amounts of data into a SQL table. I realized this technique could be readily adapted to DITA.
Webcast: DITA Specialization 101
Simon Bate of Scriptorium Publishing introduces specialization in the DITA open toolkit and walks viewers through the fundamentals.
Webcast: Managing technical communicators in an XML environment
In this 41-minute webcast, Sarah explores how XML affects the management of technical communication and proposes a new system for measuring documentation quality.
Managing technical communicators in an XML environment
To understand how XML changes technical communication, we need to step back and look at how the rise of information technology has changed the content development process. Through the 1970s, most technical communication work had separate writing, layout, and production phases. Authors wrote content, typically in longhand or on typewriters. Typesetters would then rekey the information to transfer it into the publishing system. The dedicated typesetting system would produce camera-ready copy, which was then mechanically reproduced on a printing press.
In a desktop publishing environment, authors could type information directly into a page layout program and set up the document design. This eliminated the inefficient process of re-entering information, and it often shifted the responsibility for document design to technical communicators.
Webcast: DITA-FMx demonstration
This webcast demonstrates using the DITA-FMx plugin with FrameMaker 9 to author, edit, and create output from DITA content. Topics covered during the demo include creating DITA topics using different options and templates and generating a book from the map and then saving to a PDF file.
XML: The death of creativity in technical writing?
Originally published in STC Intercom, February 2010.
I spend a lot of time giving presentations on XML, structured authoring, and related technologies. The most common negative reaction, varied only in the level of hostility, is “Why are you stifling my creativity?”
Does XML really mean the Death of Creativity for technical communicators? And does creativity even belong in technical content?
White paper on whitespace (and removing it)
When I first started importing DITA and other XML files into structured FrameMaker, I was surprised by the excessive whitespace that appeared in the files. Even more surprising (in FrameMaker 8.0) were the red comments displayed via the EDD that said that some whitespace was invalid (these no longer appear in FrameMaker 9).
The whitespace was visible because of an odd decision by Adobe to handle all XML whitespace as if it were significant. (XML divides the world into significant and insignificant whitespace; most XML tools treat whitespace as insignficant except where necessary…think <codeblock> elements). This approach to whitespace exists in both FrameMaker and InDesign.
At first I handled the whitespace on a case-by-case basis, removing it by hand or through regular expressions. Eventually, I realized this was a more serious problem and created an XSL transform to eliminate the white space as a part of preprocessing. By using XSL that was acceptable to Xalan (not that hard), the transform can be integrated into a FrameMaker structured application.
I figured this whitespace problem must be affecting (and frustrating) more than a few of you out there,
so I made the stylesheet available on the Scriptorium web site. I also wrote a white paper “Removing XML whitespace in structured FrameMaker documents” that describes describes the XSL that went into the stylesheet and how to integrate it with your FrameMaker structured applications.
The white paper is available on the Scriptorium web site. Information about how to download the stylesheet is in the white paper.
If the stylesheet and whitepaper are useful to you, let us know!
Handling XSL:FO’s memory issue with large page counts
Formatting Object (FO) processors (FOP, in particular) often fail with memory errors when processing very large documents for PDF output. Typically in XSL:FO, the body of a document is contained in a single fo:page-sequence element. When FO documents are converted to PDF output, the FO processor holds an entire fo:page-sequence in memory to perform pagination adjustments over the span of the sequence. Very large page counts can result in memory overflows or Java heap space errors.
