The Electropubs Blog

Sections and Articles

nparker — Mon, 03 Oct 2011 12:38:23 +0000

I’ve been wondering how best to map DITA elements to HTML5′s new semantic tags.

and

These two tags are straightforward. I’ll wrap them around the contents of any custom HTML specified with the arg.hdr and arg.ftr DITA parameters.

The HTML5 specification describes an article as being “a self-contained composition in a document, page, application, or site that is, in principle, independently distributable or reusable”. That seems to closely match the DITA concept of a topic. So there are two possibilities:

Don’t use
at all in the generated HTML5, except if topics are being chunked together in a single physical file.
Start the body of each topic with
, for example:

...

In HTML5, a section is used to logically subdivide a document or article:

This clearly corresponds to a DITA section, which “represents an organizational division in a topic”.

The HTML5 spec says that nav is “a section of a page that links to other pages or to parts within the page”. The purpose of introducing such tags to HTML5 is to indicate to search engines that they don’t need to index the content in them, so speeding up searches. Although it doesn’t quite match because the links are not internal, I think this is a good match for the related links section of a DITA topic.

This new HTML element represents “a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content”. It’s plainly important that content in the aside is distinctly styled: for example, as a right-aligned sidebar in printed material, or as a floating box with a distinctive background color or border in a web page. So perhaps the best match in DITA terms is the abstract element.

This element is supposed to group consecutive headers together, for example:



Main Title


Secondary Title

Stacked headings with no intervening text are considered bad practise in technical document, and DITA’s DTDs reinforce that by not allowing them. The only time it could happen in DITA is when the titlealt element is used to provide an alternative header (for example, one that appears in search results or in a table of contents). But only one of the titles appears in the document at any one time. So I’m inclined not to use hgroup at all.

A step back: getting mathML and SVG working in DITA

nparker — Fri, 23 Sep 2011 13:12:46 +0000

One interesting feature of HTML5 is its ability to render inline SVG and mathML markup to display 2D graphics, syntax diagrams, and equations. For example:



My first SVG

This sort of markup works in most modern browsers. It’s called inline SVG because the SVG tags are embedded directly within the HTML code, in contrast to external SVG in which an SVG file is referenced in exactly the same way as you would a GIF or JPEG:

My plan for the DITA to HTML5 plugin is to pass inline SVG or mathML markup directly through from DITA topics to HTML5.

Unfortunately, getting inline SVG and mathML to work in DITA is not straightforward. In fact, I’ve just spent the last two days doing some specialization, the mysterious science of customizing the set of tags that authors can use in DITA, in order to get it to work. The reason that native SVG and mathML support has never been included in the DITA Open Toolkit seems to be that there simply hasn’t been much demand for it (and it was difficult to display in older browsers). SVG is still the only vectorial graphics format supported by DITA and hopefully one day it’ll be fully integrated into the open toolkit.

My main sources of information about specialization have been Eliot Kimber’s excellent DITA Configuration and Specialization tutorial and Introduction to DITA by Jennifer Linton and Kylene Bruski.

Specialization can be used to modify DITA’s original set of elements and attributes in several ways:

If you don’t need a particular domain (a related set of tags, for example, the User Interface domain), removing it completely so that authors no longer see any of the domain’s tags in the list of available elements.
Modifying the properties of particular tags, for example, so that
must contain plain text only and none of the inline formatting tags like or that are normally available.

Creating new attributes for existing tags.

Adding new custom domains.

In DITA parlance, these techniques are called respectively ”Document Type Shell”, “Topic Constraint”, “Attribute Specialization”, and “Element Domain Specialization”. Conclusion: you don’t have to be a geek to specialize, but it helps. We’re going to be doing element domain specialization.

To be honest, though, following Eliot’s tutorial was a lot easier than I anticipated. Using oXygenXML, DITA1.5.3 and a few articles I found on Google, I got inline SVG and mathML working without too much trouble. I suspect I’ll have more problems packaging it as a plugin so that others can use it, but that’s for later. And there are still a lot of things I don’t understand. For now, I’m going to switch to technical author mode to describe how to implement the specializations.

Preparing a Test Environment

Copy the entire {dita-ot-root}/dtd/technicalContent folder (where {dita-ot-root} is the root folder of your DITA-Open Toolkit installation) to a temporary folder.

Create a new DITA concept topic and change the DOCTYPE line to point to the concept.dtd in your temporary folder, for example:

Note: If your editor adds a PUBLIC identifier as well as or instead of a SYSTEM identifier when it creates a new topic, I would recommend removing it, as a PUBLIC identifier takes precedence over the SYSTEM one and your topic will validate even if the SYSTEM identifier is wrong or a problem occurs in the specialization files.

Validate the topic to check that the DTDs in your working folder are being used.

Save the topic with a .dita or .xml extension.

Adding Inline mathML support to DITA

Domain specialization requires you to create two files, a .mod (module) and a .ent (entity), then to update the DTD. This example only shows the concept DTD, but you’d need to do it to the other topic types’ DTDs too (there must be a way of doing it to the base DTD, ditabase.dtd, so that it works for all topic types, but I couldn’t figure that out).

Copy and paste this .mod file (which I’ve taken from a specialization article I found) and save it in your temporary technicalContent/dtd folder as mathmlDomain2.mod.

Copy and paste this .ent file and save it in the technicalContent/dtd folder as mathmlDomain2.ent.

Edit the concept.dtd file in your temporary folder and make the following changes:

Add these lines to the bottom of the DOMAIN ENTITY DECLARATIONS section:
%math-d-dec;

In the DOMAIN EXTENSIONS section, add the lines:

In the DOMAINS ATTRIBUTE OVERRIDE section, add the line:
&math-d-att;

In the DOMAIN ELEMENT INTEGRATION section, add the following lines:
%math-d-def;

Save the changes and validate your concept topic to check that you haven’t messed things up.

That’s it! Position the cursor within a
element in your concept topic and you should now see new elements like and in the list of available elements. To test it on something meaningful, you can use the following sample code:
$a = F m = q [E + v X B] m$

Adding Inline SVG support

SVG integration follows the same basic procedure: create two files; a .mod (module) and a .ent (entity) then update the DTD file.

Copy and paste this .mod file and save it in the technicalContent/dtd folder as svgDomain.mod.

Copy and paste this .ent file and save it in the technicalContent/dtd folder as svgDomain.ent.

If you don’t already have it, do a Google search for the svg11.dtd file and copy it into the technicalContent/dtd folder.

Edit the concept.dtd file in your temporary folder and make the following changes:

In the DOMAIN ENTITY DECLARATIONS section, add the lines:
%svg-d-dec;

In the DOMAIN EXTENSIONS section, modify the line that you previously edited for mathML to:
| %svg-d-foreign;">

In the DOMAINS ATTRIBUTE OVERRIDE section, add the line:
&svg-d-att;

In the DOMAIN ELEMENT INTEGRATION section, add the following lines:
%svg-d-def;

Save the changes and validate your concept topic again to check that everything works.

That’s it! Position the cursor within a
element in your concept topic and you should now see the new element in the list of available elements. To test it on something meaningful, you can use the following sample code:

Conclusions and Next Steps

Just to prove it does work, here’s a screenshot from oXygenXML showing a bit of inline SVG and mathML:

The next steps are:

To package this as a plugin so that anyone can add it to their DITA Open Toolkit

To update my DITA to HTML5 transformation so that the inline mathML and SVG appear in my HTML5 topics.

More on that at a later date…

An HTML5 plugin for DITA

nparker — Tue, 20 Sep 2011 10:03:22 +0000

Does anyone need to export content from DITA to HTML5? I’ve been somewhat surprised at the lack of any real discussion on this topic so far apart from a few posts on the DITA-USERS forum about video codec compatibility and a good article by Don Day.

The current explosive growth in the number of smart devices deployed will inevitably lead to a strong demand for technical documentation on mobile platforms. PDF- and HTML-based documents as well as eBooks can, of course, already be used on smart devices by means of native viewers, mobile browsers and eBook readers. The PDF and HTML user experience is generally poor, involving a lot of tapping, pinching, scrolling and rotating to get content to display correctly. Although the eBook user experience is much better, especially on tablets, eBook readers are proprietary native applications and mobile platform owners have imposed all sorts of restrictions on content.

HTML5 promises to offer a superior user experience for mobile users. Mobile browsers already do a good job of automatically resizing and reformatting HTML5-based content to match devices’ screen sizes and resolutions. HTML5 content can be rich, dynamic, and interactive so is well suited to eLearning applications, for example.

So I’ve decided to try and create an HTML5 plugin for DITA! I hope this plugin will provide support for:

HTML’s new semantic elements such as
,
, and

Inline SVG graphics

MathML equations

Offline storage

The latest generation of browsers, including Firefox, Chrome, Safari, and Webkit-based mobile browsers, already support all these features. Internet Explorer is lagging behind as usual, but Microsoft has promised that IE10 will fully support the HTML5 standard. HTML5 is still evolving, so it looks like definitive support for things like metadata and the many Javascript APIs will have to wait for a while yet. But the core functionality is remarkably stable and well-supported, so there’s already enough to be getting on with…