Python, LXML, and setting xml:lang

Having trouble figuring out how to script the @xml:lang attribute?

For a DITA document that contains a single language, the highest level element (i.e. map, concept, task, etc.) that contains content should set the @xml:lang attribute to the language that applies to the document.

The question: How do I set the @xml:lang attribute using lxml? Everyone seems confused on the forums. Continue reading

The Limits of Minimalism

At my previous company, I championed the principles of minimalism in documentation. While minimalism is not specifically DITA-related, content development in DITA benefits from applying the principles, and DITA certainly works well with some of the principles. And recently there was discussion on the dita-users list about how different types of information architectures may be expressed in DITA.

I don’t have to champion the principles of minimalism any more, because my one colleague and I are in alignment. But I have been finding that minimalism has limits to its applicability. Continue reading

QR Codes in DITA Ouput

Inspired by a thread started by Sean Healy, and building on the instructions posted by Kevin Brown, I added the ability to generate and insert QR Codes into PDF output to the mypdf plugin.

I ignore QR Codes in marketing, but I think they could be a great way to link to resources, such as videos, from printed technical documents. Readers can simply zap the codes with their phones to pull up the content.

Continue reading

Example Constraints Plugin

One of the most important features, in my opinion, of DITA 1.2 is the constraints mechanism. In short, constraints let you reduce the elements and attributes available to your authors. You can also specify when elements/attributes are required, and which tag structures are legal (and, therefore, which are illegal). Eliot Kimber wrote a great tutorial on how to set up constraints, but if you’d like an example plugin, you can download the one I’ve created off sourceforge.

Continue reading

FrameMaker is a real DITA editor…a very poor one

Last month, a pair of blog posts dueled over using FrameMaker for authoring XML.

Since the bullets were flying, I thought I would let off some shots of my own. I can’t speak to other XML use cases or schemas, but I do have a comment about using FrameMaker for DITA. Starting in November of 2011, I had to use FrameMaker 10 as a DITA editor for about six weeks until I had time to reconfigure the publishing process for another tool (and pretty up PDF output with mypdf). I’ve had a good deal of experience with writing and producing DITA content with XMetaL, and I agree with the criteria that Mr. Aldous sets out. So I can say that, yes, FrameMaker is a real XML editor.

It’s a really really lousy one.

Continue reading

Automagically Check Tagging, Terminology, and More

If you have more than one writer on your team (and perhaps if you have exactly one), enforcing terminology, tagging, and other standards can be challenging. We wanted an easy way to catch simple issues, like lists nested inside paragraphs and the use of out-of-date console names. We also wanted to verify, across a large document set, that certain DITA attributes were used correctly in order to make our output as reliable as possible. We started with a PowerShell script written by Ben Colborn, which included a large number of xpath-based quality assurance checks. We’ve since ported those checks into an open toolkit plugin, and we are happy to say we can now share it here on sourceforge.

Continue reading

Improving readability of DOT build log

I ran across a post on the Yahoo DITA Users’ group today about improving the readability of the toolkit’s error log. It is surprisingly easy to do – in fact, I’m not sure why this isn’t the default behavior. At any rate, if you run the toolkit from the command line via ant, you can specify that the log be created in XML instead of plain text output to the command line window. Then, you can style is with XSL. I’ve created a stylesheet that makes the log much easier for a novice to read.

Continue reading