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
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
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
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.
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
The QA Plugin
is awesome. No, really! But that may be hard to believe until you’ve seen one of the reports
(displays best in FireFox). After the “more” is a breakdown of the report, which now includes the word counts and an element count pie chart, in addition to the terminology and markup checks.
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.
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
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.