Mark your calendars for June 3-5, 2011. The first-ever Open Help Conference will be held in Cincinnati, OH, USA. The Open Help Conference is a gathering of people interested in open-source and community-based help. It combines traditional conference presentations with discussion forums and a new open-participation writing session. Professionals and community volunteers will come together to learn, share, work, and have fun.

Does your team hold in-person documentation sprints? We can provide space for post-conference documentation sprints near the conference venue.

Space is limited, so register today.

Mallard+TTML+ITS

2010-11-08

I just blogged about Mallard+TTML. And earlier I blogged about XML translations with ITS.

One of the nice features of ITS Tool is that it can merge ITS definitions from multiple sources. So when you embed TTML into Mallard, you don’t need to have a specific Mallard+TTML mode. Instead, the Mallard ITS definitions get applied, and the TTML ITS definitions get applied on top of them. I just added this ITS file to itstool git:

<its:rules
    xmlns:its="http://www.w3.org/2005/11/its"
    xmlns:tt="http://www.w3.org/ns/ttml"
    its:version="1.0">
  <its:withinTextRule withinText="yes" selector="//tt:p//*"/>
</its:rules>

This ensures that inline markup like tt:span doesn’t get split off with a placeholder into a separate translation unit. This one file applies the ITS definitions whether your TTML is embedded in Mallard, DocBook, XHTML, or any other format, or even if you have a standalone TTML file.

I said, “Why not add some simple captions to Mallard?” Philip said “Why not embed an existing format, like TTML?” Philip was so right.

<media type="video" mime="application/ogg" src="figures/gnotravex-video.ogv">
  <p>Simple demonstration of a game</p>
  <tt:tt xmlns:tt="http://www.w3.org/ns/ttml">
    <tt:body>
      <tt:div begin="1s" end="7s">
        <tt:p>Drag pieces from the right to the left, making sure that
        adjacent edges have the same number<em><tt:span begin="1s"> and
        color</tt:span></em>.</tt:p>
      </tt:div>
      <tt:div begin="6.5s" end="14s">
        <tt:p>Press <keyseq><key>Ctrl</key>arrow keys</keyseq>
        to move all the placed pieces at once.</tt:p>
      </tt:div>
    </tt:body>
  </tt:tt>
</media>

A nice bonus feature is the tt:span element. One second after the first caption is displayed, some extra text appears inside it.

We should host a TTML profile for Mallard+TTML on projectmallard.org. Authors concerned with interchange would then be able to specify that profile using ttp:profile to prevent non-Mallard TTML processors from choking up on the inline Mallard syntax.

The documentation team has recently started creating short videos to supplement our text help. The first video we shipped was for Tetravex, showing basic piece movement. The nice thing about this video is that it doesn’t include any UI elements with translatable text, so translators don’t have to go through the truoble of retaking it. It also has no audio, so there’s nothing to retake there.

But parts of the video could be helped by some explanations. For that reason, I started working on a media subtitling system for Mallard. The subtitles are written directly in your Mallard document, where they’ll get translated along with the rest of the document. They’re then inserted into the HTML and dynamically shown and hidden as the video plays.

Sample XML:

<media type="video" mime="application/ogg" src="figures/gnotravex-video.ogv">
  <p>Simple demonstration of a game</p>
  <e:captions xmlns:e="http://projectmallard.org/experimental/">
    <e:caption start="1" end="7">Drag pieces from the right to the left, making                                              
    sure that adjacent edges have the same number and color.</e:caption>
    <e:caption start="7" end="14">Press <keyseq><key>Ctrl</key>arrow keys</keyseq>                                           
    to move all the placed pieces at once.</e:caption>
  </e:captions>
</media>

End result (very much a work in progress):