Mallard Glossaries

2011-07-07

Mallard has been successful as a software help format in large part because it doesn’t include every feature under the sun. It provides a strong core language for dynamic, topic-oriented documents, and that’s what most people need most of the time. Sometimes you need some extra bells and whistles, though. So Mallard was designed to be extended, allowing you to add features without bloating the core language.

I’ve been working on a few extensions over the last few months. The one that seems to be in the most demand is the Mallard Glossaries extension. Right now, the story for glossaries is that you should use a term list on a dedicated page. And that really is enough for a simple, static list of terms. But there are disadvantages:

  • Term lists are static, and that’s not a very Mallard thing to do.
  • Term lists are manually sorted, which is a pain to begin with, but an even bigger pain for translations.
  • You can’t link to individual terms. The payload of a page is basically opaque to the linking system.
  • There’s no potential for more dynamic presentation, such as showing a short definition when you hover over a term on a topic page.

With the Glossaries extension, any page can declare a term and provide a definition in its info element. So to provide a definition for “Notifications”:

<gloss:term>
  <title>Notifications</title>
  <p><em>Notifications</em> are messages that pop up at the bottom of
  the screen, telling you that something just happened. For example,
  when someone chatting with you sends a message, a message will pop
  up to tell you. If you don't want to deal with a message right now,
  it is hidden in your messaging tray. Move your mouse to the
  bottom-right corner to see your messaging tray.</p>
</gloss:term>

This gets put in shell-notifications.page, which is the page that talks about notifications. The glossary page then collects terms from different pages and shows them, together with a link to the pages that defined them.

Since this automatically provides links to defining pages, it also serves as a sort of index. (Professional indexers might get upset with me right now. Relax, I said “sort of index”.) Pages can even declare glossary terms without providing definitions. Just don’t include any block content other than the title. Then the entry on the glossary page will link back to the right pages.

Multiple pages can even provide full definitions. The glossary page will then show all definitions, collating the links to keep them next to their definitions. Here’s a very contrived example:

Note that the first definition doesn’t have an associated link. That’s because I defined the term on the glossary page itself. There’s little point in having the glossary link to itself.

This is very basic right now. Plans and goals include:

  • Linking to individual terms from anywhere in any page
  • Showing short definitions of terms when hovering over those links
  • A tag-based selection system, so you could have glossary pages that only display a subset of the terms (e.g. symbols that were new in 3.0)
This is potent stuff, and it removes a lot of the headaches of maintaining glossaries and (sort-of) indexes in topic-oriented documents. Mallard is so far proving to be a very solid design to base extensions off of.

Mallard Training

2011-06-21

Mallard makes it easy to create dynamic, topic-oriented help documents, but even the simplest technologies have some learning curve, best practices, and advanced topics. To help developers and technical writers make the most of Mallard, I’m offering professional Mallard training services.

Mallard training starts with the basics: outlining a document, creating topics, and writing pages. You’ll explore Mallard’s unique linking and navigation system and learn how to create navigational structures that reflect what your readers are looking for. You’ll learn best practices on writing topics culled from years of in-the-trenches experience with Mallard and other documentation formats. All of this is done hands-on, creating actual documents from start to finish.

Training can be customized to your needs. You can also learn about topics such as using and developing Mallard extensions, integrating status tracking into your workflow, and working collaboratively with multiple contributors.

If you’re interested in Mallard, contact Syllogist for more information.

We’ve talked about doing run-time conditional processing in our help for a very long time, nearly as long as I’ve been around. When you have applications that can run in multiple environments, you sometimes need to write different help text for difference cases.

For example, take an instant messaging application like Empathy. In GNOME 3, the Telepathy integration means that users can chat directly from the tray. Hackers know it’s not actually Empathy, but users don’t care. It’s chat. In GNOME 2, you usually interact with Empathy through the notification tray. In Unity, it integrates with the messaging menu. These are all things we should write about in the help.

But it’s hard to write about things when you don’t know where your help is read. The only way to deal with this is to patch the help for different environments. My experience is that that rarely happens. Plus, you don’t always create different packages for different environments. The exact same Empathy package in Fedora is used in GNOME Shell, GNOME fallback, and XFCE.

Other XML formats have conditional processing, but their design isn’t suitable for our needs. They usually work by having a set of attributes that take some tags. The behavior isn’t usually specified, because it’s assumed that they’ll be handled by a vendor-specific build tool that strips things out before creating a deliverable. Our source format is our deliverable format, and we want to adapt it at run-time.

So I’ve just landed some changes in Yelp to support a Mallard extension format for run-time conditional processing. Any block element can have the if:test conditional attribute added. This is evaluated as an XPath expression with extension functions that can tell you things about the environment. This is much more flexible than a set of tagging attributes, because you can combine multiple tests with “and” and “or“.

<p if:test="if:env('gnome-shell')">This is only shown in GNOME Shell</p>
<p if:test="if:env('gnome-shell') or if:env('gnome-panel')">
  This is shown under GNOME Shell or GNOME Panel
</p>

The if:test attribute is a convenient short-hand syntax. There are also conditional processing elements that allow you to do basic branching and fallback.

<if:choose>
  <if:if test="if:env('unity')">
    <p>You're using Unity</p>
  </if>
  <if:if test="if:env('xfce')">
    <p>You're using XFCE</p>
  </if:if>
  <if:else>
    <p>You're using something else</p>
  </if:else>
</if:choose>

The full syntax has another advantage. What happens if you hand a document with conditional processing to a Mallard processor that doesn’t support it? It turns out that Mallard has very well-defined rules for how unknown extensions are handled. In the first case, you just have an external attribute on a known element. The attribute is ignored and the p element is processed as normal.

In the second case, you have an external element in a block context. A Mallard implementation that doesn’t do conditional processing will visit the children in restricted block context. In restricted block context, unknown external elements are ignored.

Yelp 3.0 doesn’t have the conditional processing support. The following two snippets will do what they say in Yelp 3.0, but they will be exactly equivalent to Yelp 3.2 with conditional processing support.

<p if:test="if:env('foo')">
  This will be displayed in Yelp 3.0
</p>
<if:choose>
  <if:if test="if:env('foo')">
    <p>This will not be displayed in Yelp 3.0</p>
  </if:test>
</if:choose>

Details are all subject to change, of course. This does basically follow a proposal I made to the Mallard mailing list last August. But for now, it’s in an experimental namespace. I just need to iron out the kinks and write up a specification on projectmallard.org.

Open Help Conference

GNOME 3

2011-04-07

I’ve never been more excited to be a GNOME developer. After years of hard work and planning, GNOME 3 was released yesterday. Check out the Introduction to GNOME from our brand-new help to learn all about it.

GNOME 3 shows the innovation that open source communities can bring. Hundreds of developers, designers, writers, testers, and translators worked hard to deliver an amazing new user experience. Among them are the fantastic people who helped create an all-new help system that rivals anything I’ve seen elsewhere. My release notes list Phil Bull, Jim Campbell, Tiffany Antapolski, Natalia Ruz Leiva, Shaun McCance, Paul Frields, Mike Hill, Aline Bessa, Marina Zhurakhinskaya, and Kelly Sinnott. If I missed anyone, I’m really sorry. It’s hard to keep track of so much awesome.

We tossed out the old manual (who reads those?) and started fresh with topic-oriented help, building on the dynamic Mallard language. The results are amazing. The initial release has 214 pages, carefully organized and cross-linked to help you find the information you need quickly and get back to your life. What is a workspace? Select files by pattern. Enter special characters.

Frederic Peters did amazing work on library.gnome.org so all the new help is available online. But remember that all of this is available from the Help application on your GNOME 3 desktop. The help viewer was completely rewritten for GNOME 3, and I think you’ll really like what we’ve done.

By the way, if you want to meet up and learn about GNOME’s fresh approach to help, you should come to the Open Help Conference this June. At least Phil, Jim, and I will be there, and we’ll be joined by documentation teams from other great open source projects.

We’re not done yet.

Help needs to constantly improve and evolve as we learn more about what our users need. The GNOME documentation team is already hard at work on more pages and revisions to existing pages. We’ll be pushing updates to the help weekly. If you want to get involved, subscribe to our mailing list and send an email to gnome-doc-list@gnome.org.

We also welcome drive-by contributions. One of the really nice things about topic-oriented documents with Mallard is that it’s easy to just write up a page about something without worrying about making revisions to an entire book. If you love using GNOME, a great way to contribute is by writing a short page about an awesome time-saving trick. We’ll put these under Tips & Tricks, and users worldwide will learn something cool because of you.

I am GNOME

Phil mentioned the future of Desktop Help, but he was sparse on details. Let me fill in the blanks. With Mallard, we worry mostly about structure and content, and we leave the rendering details to Yelp. Sometimes we want to influence the style, and for that we use Mallard’s style hints. But sometimes, just sometimes, for very special pages, we want to inject some pizzazz.

We can do that too. Watch:

This is using some custom style hints and a very small Mallard extension, which falls back gracefully thanks to Mallard’s well-defined rules for extensions and fallback.

This is still a work in progress. And with work continuing into the night at the help hackfest in Toronto, it’s very much in progress.

I blogged earlier this year about doing faceted navigation with Mallard. The idea sat dormant for a while, but with the new GNOME developer demos, I had a really fun use case.

Here’s the basic idea: Topic pages declare values for facets. These are basically just categorized tags. So my Message Board tutorial has some simple markup that says it’s written in C and it’s teaching you WebKit. You then have a page that collects all the topics and provides selectors to narrow what you’re looking at.

So as I browse the demos, I can say that I’m only interested in C. And perhaps I’m looking at GTK+ and Clutter to see which one is a better fit for a project I’m starting. I can uncheck everything else. Then I’m looking at only demos in C that teach either GTK+ or Clutter. Screencast:

All of the scripting is handled by Yelp. Document authors only need to write some simple declarative markup in a Mallard extension format.

(Aside: When I try to upload an ogv file to WordPress, it tells me the file type doesn’t meet security guidelines. If I rename it to ogg, I can upload it, but WordPress inserts it as audio. I have to write the HTML for the video by hand. Could somebody please make it easier to use Ogg Theora on blogs.gnome.org?)

Open Help Conference

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):

GIO docs in Mallard in Yelp

GIO docs in Mallard in Yelp

This is the GIO API reference, generated by gtk-doc, converted to Mallard, and displayed in Yelp 3. Yelp is a surprisingly nice API documentation viewer.

Update: If you use Devhelp a lot, you probably use the Search tab to get to symbols quickly. We’ve got that covered. The quick search feature in Yelp lets you search as you type on page titles and descriptions.

If you type multiple words separated by spaces, Yelp ANDs them. This is really handy for narrowing the results without having to type a perfectly matched string.