Creating a Help Content Pack

Original doc: https://www.mozilla.org/projects/help.../content_packs I hesitate to call it "original", tho, because I've basically rewritten the entire thing so that it's easier and faster to use to create Help content. The previous document had a lot of places where ideas were simply introduced without explanation, and I've tried to go through things a bit more slowly with better descriptions. This is still very much a work in progress, tho, and I need to complete the rest of it soon (where "complete" means "use what's there that's good, build on the stuff that's not as good, and add other useful information as necessary".

This document describes how to integrate HTML help documentation into your application using the Mozilla Help Viewer. Documentation contained in the Help Viewer can be accessed using any XUL application or program that embeds Mozilla.

What is a Content Pack?

A Content Pack is a packaged set of files that describe Help content. Content Packs include help documents written in XHTML, a content pack descriptor file written in RDF, and a table of contents, index, and glossary (also written in RDF). You can create a content packs which inherit from existing Mozilla Help content packs.

The Contents of a Content Pack

Content Packs consist of a general pack description file, table of contents, index, search, glossary, and help documents. The help documents are written in XHTML, and the rest are written in RDF. The content pack descriptor file outlines the framework of the contents of the pack by pointing to the files describing the table of contents, index, and glossary RDF files. The table of contents and index files are simple tree-based outlines written in RDF. The glossary file is written in RDF and consists of a simple list of terms with corresponding URLs to the term definition.

Creating a Content Pack

The Content Pack Descriptor File

As mentioned earlier, the content pack descriptor file is written using RDF. If you don't know RDF, that's okay - for our purposes, you won't need to learn very much. If you understand the basics of HTML or (preferably) XML, you'll understand the very basics of the syntax - elements, attributes, and element contents. Understanding the syntax is important because small syntax errors can mean that a whole file won't be loaded correctly. However, while it may seem like this is a disadvantage, it's actually an advantage - if you make an error you'll know immediately, and you should be able to easily figure out what the problem is by directly loading the file in Firefox. Later, when we get to actually writing content, you'll need to know XHTML, but for now knowledge of the syntax should be enough.

Open up your favorite text editor and create the file content-pack.rdf. Insert into it the following text:

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:nc="https://home.netscape.com/NC-rdf#">

</rdf:RDF>

If you're familiar with HTML or XML, you might recognize this as the container element for the whole document. It serves as a wrapper around the entire contents of the file, marking it as RDF.

Next, you'll need to insert a rdf:Description element into the file, inside the rdf:RDF element just created:

    <rdf:Description rdf:about="urn:root"
                     nc:title=""
                     nc:defaulttopic=""
                     nc:base="">
    </rdf:Description>

Fill in the attributes as follows:

• rdf:about must be urn:root or your pack won't work. This attribute marks the start point in the RDF graph described by the file, and the Help Viewer searches for this element in order to query for further information (stored in child elements) about the content pack being parsed.
• nc:title is where you specify the title (e.g., "Mozilla Firefox Help") for the Help Window. This attribute is required.
• nc:defaulttopic will hold the rdf:ID of the topic you want displayed when the viewer first loads if none has been specified. This attribute also specifies what topic is loaded when the user hits the Home button in the viewer. We'll get to exactly how to fill in this attribute later. This attribute is optional, with fallback to the value welcome.
• nc:base contains the base URL relative to which the Help content referenced in the descriptor file is located. For example, if your glossary, index, and table of contents RDF files are all located at chrome://myapp/locale/help/*, then you could put chrome://myapp/locale/help/ here and use only the actual file names without path when needed later. You don't actually need this attribute if you don't want it, but it's a useful shorthand to save typing.

Next, we need to describe where to find the glossary, index, and table of contents. (We're still not actually to the point where we're describing the actual data in each of these, so we'll just use some filler data for now.) Add the following code inside the rdf:Description element you just created:

      <nc:panellist>
        <rdf:Seq>

        </rdf:Seq>
      </nc:panellist>

You'll create the relevant information descriptions within the rdf:Seq element.

The location of each of the glossary, index, and table of contents data sources is stored in one rdf:Description element contained within one rdf:li element, like so:

            <rdf:Seq>
                <rdf:li>
                    <rdf:Description nc:panelid="glossary"
                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/>
                </rdf:li>
                <rdf:li>
                    <rdf:Description nc:panelid="toc"
                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/>
                </rdf:li>
                <rdf:li>
                    <rdf:Description nc:panelid="index"
                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/>
                </rdf:li>
            </rdf:Seq>

The Help Viewer UI may or may not provide a panel for each of these data sources. In Firefox 1.0 each data source had a panel. Starting with Firefox 1.1 and the Mozilla 1.8 platform, only the table of contents data source will be displayed. The glossary and index data sources will be hidden - information found only in them will not be displayed unless the user conducts a search of the Help pack that would return glossary or index results.XXX this sentence is ugly - a little rewording help here would be nice

A data source description is pretty much the same no matter which type you're defining, and the syntax is pretty simple. Each panel is specified by one rdf:Description element with the following attributes:

• nc:panelid specifies the name of the panel, which may be any one of glossary, search, toc, or index. The data source specified by toc will always be displayed, while the other data sources may only be available by searching through the loaded content pack.
• nc:datasources is a space-separated list of RDF datasources used in construction of the structure of referenced topics. Generally, each item in the list will be a URI to an RDF file, but if you're more familiar with RDF you can also refer to a specific node within the RDF file using its rdf:ID attribute.
• nc:platform (added in Mozilla 1.8b2/Firefox 1.1) when present specifies the platforms to which the information stored in the referenced data sources applies. This attribute is useful when some of your help contents only apply to one specific platform. If this attribute is omitted, the information in the data sources applies to all platforms. The attribute is a space-separated list of platform strings. Strings recognized from 1.8 onward are win, mac, os2, and unix; more will be added as required. Unrecognized strings are ignored during parsing. An example of how to use this attribute follows:

                <!-- Assumptions:
                     win-toc.rdf contains Windows- and OS/2-specific info,
                     unix-toc.rdf contains Linux- and Mac-specific info. -->
                <rdf:li>
                    <rdf:Description nc:panelid="toc"
                                     nc:platform="win os2"
                                     nc:datasources="win-toc.rdf"/>
                </rdf:li>
                <rdf:li>
                    <rdf:Description nc:panelid="toc"
                                     nc:platform="unix mac"
                                     nc:datasources="unix-toc.rdf"/>
                </rdf:li>

There's one final element to add inside rdf:Seq to complete the content pack descriptor file: an element to describe the Help Viewer's search function. Search automatically goes through all of the elements in the table of contents, index, and glossary, but you might wish to have Search go through more sources of data. One possible source might be an online, dynamically-generated list of added content stored on your web site. To have the Help Viewer search through these additional data sources, define another rdf:li element like so:

                <rdf:li>
                    <rdf:Description nc:panelid="search"
                                     nc:datasources=""
                                     nc:emptysearchtext="[No matching items found.]"
                                     nc:emptysearchlink="chrome://foo/locale/bar.html"/>
                </rdf:li>

• nc:panelid should be set to search.
• nc:datasources should be set as with table of contents, index, and glossary definitions.
• nc:platform (added in Mozilla 1.8b2/Firefox 1.1) may be used on search data sources as it's used on table of contents, index, and glossary definitions.
• nc:emptysearchtext specifies the text that is shown when a search through Help returns no results.
• nc:emptysearchlink specifies what URI should be shown when the pseudo-result "no results found" is accessed. This attribute is required. The sample page chrome://help/locale/welcome.xhtml has a section on searching which may be a useful link to use here.

Note that you can use the nc:datasources attribute to inherit content from other content packs. One common use of this is to inherit the small Using the Help Window article provided with the viewer. For example, the following code uses a datasource outside the content pack you have created to include the article in a table of contents:

                <rdf:li>
                    <rdf:Description nc:panelid="toc"
                                     nc:datasources="chrome://help/locale/help-toc.rdf chrome://foo/locale/help/glossary.rdf"/>
                </rdf:li>

Each of the different data source types (toc, index, glossary, and search) may be used multiple times (and in the case of platform-specific information, must be used multiple times). However, it is recommended you use a space-separated list of URIs for nc:datasources instead of separate entries, as separate entries will require a slightly longer time to load.

The Glossary File

The glossary file has the simplest format of all the data sources you'll need because there's only one level of content. (The index, table of contents, and search data sources are more likely to be nested, complicating their formats.) Create a new RDF file (for now let's name it glossary.rdf), and add the following lines to it:

<?xml version="1.0"?>

<rdf:RDF xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:nc="https://home.netscape.com/NC-rdf#">

  <rdf:Description rdf:about="urn:root">
    <nc:subheadings>
      <rdf:Seq>


      </rdf:Seq>
    <nc:subheadings>
  </rdf:Description>

</rdf:RDF>

This forms the outer framework of a glossary description file. To add data to it, add one of the following per entry in your glossary within the rdf:Seq above:

        <rdf:li>
          <rdf:Description nc:name=""
                           nc:link=""/>
        </rdf:li>

The rdf:li element serves purely to contain each separate entry. The rdf:Description element describes the glossary entry. It has two required attributes: nc:name and nc:link. nc:name is the name for the entry - it's what's currently displayed in the glossary as the entry's title. nc:link contains a URI referencing what will be displayed in the viewer when the entry is accessed.

The Index File

The index data source structurally differs from the glossary in that it is more likely to have multiple levels. A single-level index may be accomplished in exactly the same way as a glossary file, but multiple levels can make it easier to navigate to specific information. Let's start with a brief sample RDF file with a single level:

<?xml version="1.0"?>

<rdf:RDF xmlns:rdf="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:nc="https://home.netscape.com/NC-rdf#">

  <rdf:Description rdf:about="urn:root">
    <nc:subheadings>
      <rdf:Seq>
        <rdf:li><rdf:Description nc:link="foo.html" nc:title="Foo"/></rdf:li>
        <rdf:li><rdf:Description nc:link="baz.html" nc:title="Baz"/></rdf:li>
      </rdf:Seq>
    <nc:subheadings>
  </rdf:Description>

</rdf:RDF>

There's not much here: a single level containing the two entries "Foo" and "Baz". Now, let's say you want to add an entry "bar" underneath "Foo". How would you do this? First, you need to add an attribute to the "Foo" entry so that you can precisely refer to it. The rdf:ID attribute serves this purpose. It should be unique both within file and within the data sources in your content pack to ensure clarity.

        <rdf:li><rdf:Description rdf:ID="foo" nc:link="foo.html" nc:title="Foo"/></rdf:li>

Next, add the following to your file just after the existing rdf:Description element:

  <rdf:Description rdf:about="#foo">
    <nc:subheadings>
      <rdf:Seq>
        <rdf:li><rdf:Description rdf:ID="bar" nc:link="bar.html" nc:title="bar"/></rdf:li>
      </rdf:Seq>
    </nc:subheadings>
  </rdf:Description>

Except for the different value for rdf:about, this looks exactly like a top-level entry definition. The difference is a result of how RDF works. In RDF data describes data. Top-level entries describe the root node, urn:root; nested entries describe other entries. You can refer to an entry by giving the entry a unique rdf:ID attribute. Then, to describe that entry, you set an rdf:about attribute to the value of the entry's rdf:ID, prefixed by a #.

Nesting as described above works exactly the same no matter how deeply or shallowly nested your entry is. Nesting theoretically can work to any number of levels, but for practical reasons nesting is limited to roughly 20 levels. If you're coming anywhere close to this limit, however, you probably should be considering exactly why you need so much nesting.

The Table of Contents File

The table of contents file is the most important data source you'll create. The help viewer will display the table of contents when you start the viewer. In some versions of the viewer, it will be the only data source ever directly displayed. It's the primary way to provide a structured view of the help you provide to users.

The table of contents also provides the list of topics from which the home page for the viewer will be chosen. Recall that in the content pack descriptor file you included an nc:defaulttopic attribute, which defaulted to "welcome". The value of that attribute is the rdf:ID of the topic you want displayed when the viewer is loaded.

The table of contents data source is exactly like an index data source, and if you have a working index data source you could use it as a table of contents with no changes whatsoever. See the instructions on creating glossary and index data sources to learn how to create a table of contents.

Additional Search Databases

Starting with Firefox 1.1, you can define additional information databases through which the help viewer will search. The data from these may never even be displayed to the user, but if he tries to search through Help, he will see results from these databases.

Defining a search database is exactly like defining a table of contents file (and therefore exactly like creating an index file), so follow the instructions there to create additional data sources as you need them.

Viewing your Content Pack in the Help Viewer

To launch the Help Viewer with your content pack, you need to have chrome://help/content/contextHelp.js loaded into the XUL file that provides the UI to open the help viewer:

  <script type="application/javascript"
          src="chrome://help/content/contextHelp.js"/>

This will allow you to access all of the viewer functions. To open the Help Viewer, run the openHelp() function. It's exactly the same as any JavaScript command, you you can insert it in command elements, oncommand attributes, and other such places. The parameters are described below:

openHelp(aTopic, aContentPackSpec);

• aTopic: the rdf:ID of the topic you want to load as the home page in the help viewer.
• aContentPackSpec: the path to the content pack you want to load.

Here is an example of how Firefox opens its help documentation:

openHelp('firefox-help', 'chrome://browser/locale/help/help.rdf');

Packing It All Up