Webhelp for DITA

Simon Bate / DITA, Tools4 Comments

A few weeks ago my esteemed colleague, David Kelly, published a blog post about his DITA Open Toolkit (OT) plugin that simplifies the customization of PDF output. In the post, David mentioned that I would soon be writing about a plugin to provide HTML-based web help. I found a bit of time to write about Scriptorium Help, so here is that post.

When talking to clients about moving to DITA the two most common output requirements we hear are PDF and webhelp. Satisfying the request for PDF is relatively easy; customizing the output is now much easier with the Scriptorium PDF plugin. However, webhelp is a different matter.

The DITA Open Toolkit (OT) provides a number of output formats, including several HTML-based formats (XHTML, Eclipse Help, Microsoft HTML Help), but none of these provide the webhelp that our clients request. XHTML by itself is part of a solution, but it provides minimal navigation (a table of contents). Eclipse Help (the Eclipse Infocenter) is useful, but it requires a good deal of overhead; if the system you’re documenting doesn’t use Java already, Eclipse Help is not particularly useful. Microsoft HTML Help was relevant a few years ago, but Microsoft has not updated the tools to work with Unicode, so it does very poorly in non-Western localizations (additionally, the monolithic CHM files do not lend themselves well to web access).

Over the years we have been building and refining a set of templates and scripts that allow us to build an HTML-based webhelp system from DITA sources. As clients have requested features, we have incorporated the features into the help system. Now we are making this Help system available for purchase as “Scriptorium Help.”

Scriptorium Help is generated from DITA sources by a DITA OT plugin. It provides provides a traditional “tripane” interface that allows users to navigate to the content they need. Some of the features in Scriptorium Help include:

  • Table of contents (TOC) with expanding and collapsing sections
    The TOC is also synchronized with the currently select page. If you use search to navigate to a topic, then turn back to the TOC, the TOC is expanded to display the current topic. The current topic is always highlighted in the TOC.  (This is shown in the images below.)
  • Index
  • Search
    • In Western languages, you can search for multiple words and phrases (enclosed in quotation marks); each word or phrase is separated by one or more spaces. For an example, see the images below.
    • In non-Western languages (Chinese, Japanese, Korean, and so on), you can search for one or more sequences of characters (each sequence is delimited by one or more spaces).  This is also shown in the images.
    • If the search terms exist in the currently displayed topic, the terms are highlighted. Highlighting can be turned off.
  • Browse sequences
    Move to the next or previous topic in the help.
  • Breadcrumbs
    Shows your current position in the TOC hierarchy and allow you to quickly navigate to parent or ancestor topics.
  • Context sensitivity
    Another program can open Scriptorium Help in a web browser. If the program passes the ID of a topic to Scriptorium Help, it will display that topic on opening.
  • Resizable control area
    You can move the border that separates the control area from the content, allowing you to view the contents more easily.
  • Fully localizable
    Scriptorium Help uses standard DITA OT practices for maintaining the strings used in the help (button labels, search instructions, error messages, and so on).
  • Browser-independent
    We test Scriptorium Help with all major browsers (Chrome, Firefox, IE, Opera, Safari). All output files include “the mark of the web”, which prevents IE from complaining about active content.
  • Attractive output that can be customized to your needs
    The formatting of the HTML is controlled by CSS, which can be customized as needed. The CSS can be applied in two layers, so that you can define a basic corporate look and feel, then add group or product specific formatting for differentiation.
  • Print current page

Most of the features in Scriptorium Help are configurable, so if your Help does not require some features, it’s easy to turn them off.

You can read more about the Scriptorium Help plugin and the Scriptorium PDF plugin at http://www.scriptorium.com/services/dita-plugins/.  If you need more information, please contact us at info@scriptorium.com or call (toll free) 866-605-9677 or 919-481-2701.

Here are a few images of the Scriptorium Help.  Keep in mind that the overall appearance is governed by the CSS and the logo I choose to use.  Layout, colors, background colors, fonts, indention, icons and many other aspects of appearance can be changed as needed.

Scriptorium Help showing TOC and breadcrumbs

Western language search and search highlighting

Non-western language search (Japanese)

Non-western language search (Japanese)

About the Author

Simon Bate


Involved in TechComm all my working life (since the time of vacuum tubes, core memory, punch cards, and bone implements). I've worked as a writer, a manager, and—for the past score of years—building software tools for TechComm. My motto is "Let the computer do the work." Outside of work, I balance the calories I create and consume in the kitchen with weight-training sessions at the gym. I also sing Tenor in various choirs and choruses.

4 Comments on “Webhelp for DITA”

  1. Pingback: Tweets that mention Webhelp for DITA | Scriptorium Publishing -- Topsy.com

  2. Pingback: Tweets that mention Webhelp for DITA | Scriptorium Publishing -- Topsy.com

  3. Pingback: Tweets that mention Webhelp for DITA | Scriptorium Publishing -- Topsy.com

Leave a Reply

Your email address will not be published. Required fields are marked *