RSI's 5-minute-series: Learn DITA in 5 minutes

Posted by Christopher Hill on Oct 24, 2013 8:59:00 AM

5-minute-series; Learn Dita in 5 MinutesLately I’ve found myself doing more discussion of DITA, so it is time for another in the 5-minute-series. If you are new to XML it might be helpful to start with the previous two posts on XML and Schemas before continuing.

In the previous posts I discussed how XML isn’t a specific language, but is instead a set of rules governing the syntax of languages that may be invented. The invention of XML came out of a need to be able to describe content. Word processors and desktop publishers mostly focused on the formatting of content. When you create new content in these tools you do so as a part of the layout and formatting process. With XML, you instead try to describe what the content you are entering is, for example a paragraph, a chapter, a book, an article, a caption or whatever. 

XML provides a common syntax for creating languages to describe your content, but does not specify the actual grammar. As described in detail in the previous post in this series, XML Schemas or DTDs are used to specify the exact labels and grammar of a particular type of XML.

While you can invent your own labels and grammar based upon XML, doing so means that unless others adopt your format, you will have to customize editing tools to understand your particular vocabulary.

Instead of always creating a vocabulary from scratch, many users of XML instead adopt a shared standard. Standards exist to represent most any data you can think of, whether it be recipes, musical scores, articles, chapters, books or anything else. These standards can be shared, and tools can be created to create, edit, manage and format based on the standard. If a community exists around my particular flavor of XML, we can share tools and techniques that can mean reduced effort required to deploy content solutions.

DITA, an acronym for Darwin Information Typing Architecture, is an XML language that is extensible and can be adapted to a range of uses. DITA is based on the concept of topics. A topic is a unit of information that typically can be read in isolation or inserted into a larger document. In order to stream together topics, DITA uses the concept of a map file. A map file is simply an XML file that acts as a sort of table of contents stringing together a series of topic files.

The term “topic” is generic. DITA allows, however, the generic topic to be adapted to represent more specific structures. The basic DITA specification includes Concept, Task and Reference. These content units are more specific versions of the generic topic. They can be handled with special rules if you want. But if you don’t haven special rules, they can be also treated more generically as topics.

Benefits of a common vocabulary 

Having a common vocabulary means that users of the vocabulary can share information with each other and share tools and code used to handle the content. For example, if you use a DITA-based format, there are a number of editing tools that can be used to edit your content. Tools used to process the content can also be shared. For example, DITA includes the code and stylesheets needed to create PDF, HTML and other output formats, and the community is constantly evolving. New formats may appear and other DITA-based solutions can take advantage of the tools to support the new format without needing to modify their existing processes.

For DITA, the community provides the DITA Open Toolkit. This toolkit includes a variety of transformations that can take DITA content and render it in HTML, PDF, and other formats. It also provides an extensible architecture. If you have a customized version of DITA, you can create a plug-in that can enable DITA solutions to handle the specific requirements of your customizations. Toolkit plugins can be used to configure editing tools, extend the rules of DITA, or modify the included stylesheets used to render content so that they can account for a most specific vocabulary adapted from the base DITA stylesheets. Any DITA tool can process content even if it is based on proprietary extensions because all of those proprietary extensions are mapped to more generic DITA structures. So if I use a DITA-based vocabulary that defines a “chapter,” systems that do no understand “chapter” can always treat the encoded content as a more generic “topic.” 

So while XML is a set of rules for creating a particular language to encode your content, DITA is a particular language that was designed to be able to be extended to more specific uses that still share a common grammar. DITA provides a base set of stylesheets for rendering your content in a variety of specific formats. Many XML tools exist to process any DITA-based document, and most provide extension points so that you can adapt the tool to a more specific DITA-based language without having to start from scratch. 

Tools to edit DITA documents can edit any vocabulary derived from DITA without modification, and can be extended to support more specific vocabulary structures if desired. At RSI Content Solutions we have content management systems with support for DITA that provides a range of features that make it much quicker to deploy a DITA solution without starting from scratch. Our solutions allow editing, transformation, as well as the ability to reuse content in different contexts if needed. So while XML is a set of rules governing the structure of an infinite variety of languages, DITA is a topic-based XML language used for representing content. Although you can use DITA without any modifications, many organizations wish to encode content in less generic manner. DITA has the advantage of allowing more specific content structures to be derived from the existing generic structures if needed. This means that if you need to create an XML vocabulary you aren’t starting from scratch and you are providing a fallback mechanism for systems not aware of the specifics of your particular vocabulary.

0 Comments Click here to read/write comments

Topics: DITA, XML, 5-minute-series

Learn XML Schemas and DTDs in 5 minutes

Posted by Christopher Hill on Mar 22, 2011 12:56:00 PM

In my previous blog post I introduced XML in 5 minutes. As a follow up, here's another 5 minute lesson to understand what an XML Schema or DTD is and what it might mean to end users of XML-based systems.
In the previous post we created an XML document to describe a book. Recall that it used tags around the actual content to describe the content.
<book>
     <title>Alice's Adventures In Wonderland</title>
     <author>Lewis Carroll</author>
     <summary>This book tells the story of an English girl, Alice, who drops down a rabbit hole and meets a colorful cast of characters in a fantastical world called Wonderland.</summary>
</book>

We also learned how representing content in this way allows us to dramatically reduce the effort required to support multichannel publishing. It also helps a great deal with automation and moving content between systems or organizations as it eliminates some of the issues of file formatting.
What would happen to our stylesheet if someone decided to use different tags to label their content?
<book>
     <title>Alice's Adventures in Wonderland</title>
     <writer>Lewis Carroll</writer>
     <summary>This book tells the story of an English girl, Alice, who drops down a rabbit hole and meets a colorful cast of characters in a fantastical world called Wonderland.</summary>
</book>

What we called author in one document we called writer in another. This inconsistency might be small now, but if we didn't restrict what people named things in our XML we would have to support a potentially endless list of tags. In the previous article we wrote rules for how to make our books look good on a page. If we can't predict what tags (labels) people are going to use - such as author - then it becomes nearly impossible to reliably write rules.
So even though XML helps us get a consistent base format for content, we need more help to get predictability and consistency.
Enter the concept of a DTD or Schema. DTDs and Schemas are ways that systems can impose rules on the XML itself. You can describe what tags can be used, where they can be used, and put restrictions on the content of those tags. There are two different standards for describing these restrictions: Document Type Definition (DTD) and XML Schemas. We won't get into the syntax or pros and cons of the two approaches. For our 5 minute lesson we can just assume they both are ways to enforce consistent labeling of our tags in our XML documents.
Here in English is how we might communicate the requirements for our flavor of XML:
  1. Put everything inside a book tag. You can only have one of these.
  2. The first thing you put in a book is a title tag containing the title text. You cannot leave this out.
  3. The second thing you put in a book is an author tag containing the author name. You must have at least one author. If there are more, you can repeatedly add more tagged authors.
  4. After all the tagged authors, you can add a summary tag. This is optional - leave it out if you want. But you can have at most 1 summary.
This is essentially what a DTD or XML Schema does, although they do this in a language friendlier to computers.
DTDs/XML Schemas allow you to specify the rules for the structure of your XML documents
You can think of XML Schemas or DTDs as a means to create a template that all valid documents must follow

These rules can now be applied to the two examples above. The first example follows the rules, so we would say that the first XML document is valid. That means it conforms to the rules. The second document, when tested with the above rules, would be invalid. The presence of tagged content labeled "writer" is not allowed by the rules. 
In the XML world, XML Schemas or DTDs are used in a lot of scenarios, including:
  • XML editors know what is allowed by the rules and prevent writers from making mistakes
  • XML programs test incoming content and indicate when the rules are being broken, preventing formatting errors
  • XML stylesheets can be much more easily written as they only process valid content and don't have to worry about rulebreakers
  • If I want to merge my book content with yours, we can look at the rules and decide what adjustments will need to be made to bring our rules together
  • Industries can agree on the rules for types of content. So we might create a set of rules to represent newspaper articles, adopt it as an industry standard, enabling anyone to easily exchange newspaper articles without having to modify the content.
So when you hear someone rambling on about an XML Schema or DTD, they are really just talking about the rules governing how the particular XML document is to be structured.
That's XML Schemas and DTDs in 5 minutes. In the coming weeks watch the blog for more quick lessons on XML-related technologies.
1 Comment Click here to read/write comments

Topics: publishing, XML, XML Schema, DTD, 5-minute-series

Learn XML in 5 Minutes!

Posted by Christopher Hill on Mar 15, 2011 8:24:00 PM

As product manager for an XML-based CMS, often I find myself answering the question "What is XML?" Not necessarily a simple thing to answer in passing - entire books and courses are dedicated to the subject - but in about 5 minutes most content creators can at least understand at a basic level what XML is all about. Here is my 5 minute XML class to give a first pass at answering this question. At the end most people should have a rough idea of what XML is and can start thinking about its potential.
   
Take a look at the following text:
      
Alice's Adventures In Wonderland
by Lewis Carroll
This book tells the story of an English girl, Alice, who drops down a rabbit hole and meets a colorful cast of characters in a fantastical world called Wonderland.
      
Reading it, you probably can infer that the underlined text is a book title. The italicized text appears to be the author of the book (if you dropped the word "by"). Then there is additional text. If you are familiar with the book, you can tell that the text is not part of the book itself, but appears to be a short summary. We know all of this because of certain conventions we have been taught as well as contextual clues provided by the words themselves.
      
Let's look at the same text again:
     
Lewis Carroll
Alice's Adventures In Wonderland
This book tells the story of an English girl, Alice, who drops down a rabbit hole and meets a colorful cast of characters in a fantastical world called Wonderland.

Even though the text looks quite different, we probably could still successfully interpret the author's intent. Now, imagine you have to train a robot to understand these two cases. What rules might you create to "teach" the robot how to decide how to successfully parse these two text examples and understand what parts of the text are titles, author names, and summaries? Even for these two limited cases, the list of rules is going to be quite involved, and will include rules based on formatting, language, and convention. And a robot will have to know that somewhere in the text are the three pieces of content, otherwise it probably has little chance of determining the nature of what it is looking at (Darwin the Jeopardy-playing supercomputer excluded).

Even if all that was true, errors are likely to creep in. Do your rules allow the robot to understand that "by" is really a formatting cue indicating the following text is an author name? What about the meaning of an underline? Bold? Italics? Each example uses the same formatting cues but in different ways. 

When you write a document in a word processor or a desktop publishing program you mostly focus on how that text looks. Imagine after all that careful work making the text look right for your printer, you decide your content should appear on a Web site. Suddenly all that formatting needs to be re-worked to take advantage of the conventions of the Web. Now if you want to deliver to an electronic reader or a mobile phone your formatting may again need to be revisited. 

This is an expensive proposition when you start imagining all of the possible delivery channels that may require formatting changes. For many channels, all that formatting work needs to be scrapped and done again. 

The answer to this is XML: the extensible markup language. A short way to summarize the promise of XML is that it allows authors to indicate what the content is rather than how the content looks. XML does this using tags, essentially text-based labels that indicate what a particular piece of data might be. Here is the same example as XML. Even though you may not know anything about XML, you can make sense of this content.

<book>
<title>Alice's Adventures In Wonderland</title>
<author>Lewis Carroll</author>
<summary>This book tells the story of an English girl, Alice, who drops down a rabbit hole and meets a colorful cast of characters in a fantastical world called Wonderland.</summary>
</book>

Yes, angle brackets seem a little cold, but notice how they are labels making the meaning of the various pieces of text completely unambiguous. Notice how each tag (i.e. <book>) has a match (i.e. </book>). These pairs create a container. Everything appearing between matching tags is considered contained by them.

Now, imagine you want to deliver the content to a printed page, web site or mobile device. It is much easier now to write a set of rules that indicate how each should be formatted.

Rule for <book>:
start a new page
Rule for <title>:
one the first line, output the text as underlined,16 point Helvetica
Rule for <author>:  
start a new line, output the text in italic, 12 point Helvetica
Rule for <summary>: 
double-space, start a new line, output the text in 12 point Helvetica

These rules could be called a stylesheet. In reality, stylesheets are written in a more machine-friendly format that are beyond the scope of a 5 minute XML course, but this example should suffice to give you an idea of what a stylesheet's role in creating presentable XML content is. 

If I had hundreds, thousands or millions of book content items I could use this single stylesheet to output them all and be guaranteed consistency. 

If I decide I want to switch to a new look for my content, maybe using Garamond instead of Helvetica, then I just need to modify the stylesheet. Notice how the original book content exists completely independently of the formatting. And notice that changing the look of something doesn't require any editing of the original content.

Suppose I want to deliver my content to multiple channels. Each channel has its own conventions, limitations, and capabilities. People expect different formatting on a mobile phone than on their desktop computer. A web site typically looks different than the printed page. We used to underline book titles in print - but underline means something else on the web so often a different format is used. Helvetica may not even be an available font for many channels. 

Fortunately, XML makes supporting each unique channel straightforward. Instead of endlessly modifying my content, I simply develop new rules (a new stylesheet, or a variation of an existing stylesheet) for a new channel. The authoring process is unaffected. Existing content does not need to be re-edited to support the new channel. Instead, the new rules are applied to the content generating channel-appropriate output. And as the number of channels expand, XML serves as a content anchor point so that you can adapt content rapidly and in an automated way to the unique requirements of each channel.
XML as an anchor for multichannel publishing

If all of your content were clearly labeled by what it is, it is not nearly as daunting to support new output formats for new opportunities. Instead to a massive conversion of all your formatted content from one format to another, you just have to develop a new set of rules and you are ready to go.

That's XML in 5 minutes. At least as it impacts content creation and delivery. In the coming weeks I'll be posting additional quick lessons on XML-related technologies.
8 Comments Click here to read/write comments

Topics: ebooks, publishing, XML, 5-minute-series

All posts

Comment below