HELP

Introduction
Documentation is probably, invariable, the ”weakest link” in the software production chain. Last minute releases do not leave a lot of time left for documenting the code, and excuses such as ”the code is self-explanatory” are more than common. Except that it is not. Probably you will not understand ”why” you were using that typedef with a multimap inside a multimap, two months later; and so nobody will.
But I’ll probably leave this topic for another article (which is really worth it!) and just assume for now, that your code is thoroughly commented all the way, and that you even adopted an automated documentation generator (like Doxygen [1]) and formatted your comments accordingly. So my article is not going to be about you, or the other programmers using your application, but about the users. Yes, that’s right, that class of ”living beings” that potentially possess no technical knowledge, and can be the ”source” of all sorts of problems. ”Unfortunately”, these may be the ultimate target of your program, and they don’t care so much about the ”beauty” of templates, one-line conditional return expressions, or initializations on the constructor, as they care about being able to understand and actually use the program. And this is why they need ”help”.

Image

Background
For a long time, help was not really part of any API, and when implemented it was in some sort of proprietary format, done from scratch in the application (Basic, Java, Fortran and other structured languages). With the advent of object oriented languages (OOL), a format for help arose in Windows, and it was supported until Windows Vista: WinHelp format [2]. After that, fortunately Microsoft start pushing towards an HTML-based help, which is much more standard since it can be implemented across platforms; this is the only help format supported in the latest versions of Visual Studio. Normally help is not implemented by the same programmers that wrote the code, but by a different set of people, which probably explains the existence of a lot of third-party tools for writing help files (helpStudio Lite [3] is an example).
As a C++ programmer, producing cross-platform applications, I am an enthusiastic
adopter of the QT libraries [4]. Qt, also pronounced ”Cute” provides an extensive framework for diverse things including (but not limited to): UI, multi-threading, STL, XML, and Help. Finding the Qt Help Framework [5] was a good surprise; due to its potentialities, neat integration, ease to use, and mostly due to its ability to involve non C++ programmers in the process of creation of Help. I was personally involved in the process of creating a Help for an application with a non-programmer person, and apart from some small misunderstandings, I can say that the whole process was quite smooth.
Thus I decided to share this tool with the the readers of this blog.

 Anatomy of the Cute ”Help”
We can view a help project as a help manual, and a help collection as a set of manuals that may have cross references between them (for instance an application suite). All these project files are registered using Qt tools, and ultimately they generate a compressed file, which is read by Qt Assistant.
The ”Help project” basically consists in a set of one or more HTML files describing many
aspects of the application, and a project file that organises them (.qhp). The project file
has information on ”how-to” use these files, organising the table of contents, the filter
and the keywords. This is basically an XML file, such as the one bellow.

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>mycompany.com.myapplication.1_0</namespace>
<virtualFolder>doc</virtualFolder>
<customFilter name="My Application 1.0">
<filterAttribute>myapp</filterAttribute> <filterAttribute>1.0
</filterAttribute>
</customFilter>
<filterSection>
<filterAttribute>myapp</filterAttribute> <filterAttribute>
1.0</filterAttribute> <toc>
<section title="My Application Manual" ref="index.html">
<section title="Chapter 1" ref="doc.html#chapter1"/>
<section title="Chapter 2" ref="doc.html#chapter2"/>
<section title="Chapter 3" ref="doc.html#chapter3"/> </section>
</toc>
<keywords>
<keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
<keyword name="bar" ref="doc.html#bar"/>
<keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
</keywords>
<files>
<file>classic.css</file>
<file>*.html</file>
</files>
</filterSection>
</QtHelpProject>

In this file, you may notice important content definitions such as: ”filters”, ”table of contents” and ”keywords”.
As both XML and HTML are well-known and text-based formats, we can create these files using any tool we like, ranging from text editors (Kate, Vi, Emacs) to XML or HTML editors, in case you are more ”visual” (normally non-programmers, such as the
people who write manuals, are!).
Because we store help as compressed files, rather than raw files, the next step is to transform the qhp file into its compressed format (qch). Fortunately, the Qt suite comes with a CLI for that: the qhelpgenerator. This is an example of the syntax:

qhelpgenerator doc.qhp −o doc.qch

A ”Help collection” is composed of a set of help projects and a collection file (.qhcp).
The top-level project that puts together one, or many, help projects is called a Help collection; the collection is organised by a collection file (.qhcp), which is again, another XML file. In the current example, we have one help collection with our single project:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
<docFiles>
<register>
<file>doc.qch</file>
</register>
</docFiles>
</QHelpCollectionProject>

And to generate the compressed collection file (qhc), we use another CLI: the qcollectiongenerator. This is an example of the syntax:

qcollectiongenerator mycollection.qhcp −o mycollection.qhc

The Help collection file is the output that is going to be called by the application. If we want to generate it in one-pass (skipping the qhelpgenerator step), we just have to modify slightly the collection file, like bellow:


...
<docFiles>
<generate>
<file>
<input>doc.qhp</input>
<output>doc.qch</output>
</file>
</generate>
<register>
<file>doc.qch</file>
</register>
</docFiles>
...

Writing the Manuals
The Help manual can be written in one or many html pages. There is no need to create
a table of contents (toc), since the help will generate one on the navigation tree, on the
left panel of Qt Assistant. However, its a good practise to have a face page, with a presentation of the manual and a table of contents. In this sample project, we have two files: index.htm, the face page that is displayed in the opening of the help and test.htm, with the actual help contents. To be able to refer sections of the html file in the toc of the project file, and to be able to recall keywords, we need to create ”anchors” to certain parts of the document. We can do that, by enclosing some words with the < a > tag. For instance: if we want to create an anchor for the keyword ”logbooks” in the file “test.htm”, we would write:
<a name=”logbooks”>logbooks</a>
and later recall this location with the url:
test.htm#logbooks

Writing the project file
In the project file we define the following attributes of the help project:

  • Namespace: a unique identifier for the documentation set.
  • Virtual folder: root directory of all files referenced in a compressed help file. In this way we can have relative paths shared between help collections.
  • Custom filters: a list of attributes that allow us to display documentation only for them.
  • filters: this section assigns contents to the defined custom filters.

Inside the ”filter” section we have the most important part of the help file: the toc, the keywords and files. The toc defines the table of contents of the help, that is going to be displayed on the left panel of the QT assistant. In terms of syntax, we have a nested list of titles that allows us to define the hierarchical structure of the manual. For instance in the section bellow of the project file:

<toc>
<section title="Myprog Manual" ref="index.htm">
<section title="Chapter 1: Introduction" ref="test.htm#chapter1">
<section title="Nature of the Information Supported by Myprog"
ref="test.htm#nature_information"/>
<section title="The Sampling Process" ref="test.htm#sampling_process"/>
<section title="Rational of Data Hierarchy" ref="test.htm#rational"/>
</section>
<section title="Chapter 2: Store Aliens Data" ref="test.htm#chapter2">
<section title="Creating the Sampling frame"
ref="test.htm#create_sampling_frame">
<section title="Create a new frame from scratch"
ref="test.htm#frame_from_scratch"/>
<section title="Create a new frame by choosing an existing one"
ref="test.htm#frame_from_existing"/>
<section title="Characterise Sampling Technique"
ref="test.htm#sampling_technique"/>
</section>
<section title="Define Minor Strata" ref="test.htm#minor_strata"/>
</section>
</section>
</toc>

We recreate a structure like this:

* Introduction
** Nature of the Information Supported by Myprog
** The Sampling Process
** Rational of Data Hierarchy
* Store Aliens Data
** Creating the Sampling frame
*** Create a new frame from scratch
**** Create a new frame by choosing an existing one
*** Characterize Sampling Technique
* Define Minor Strata

Note that the name of the section is associated with a piece of an html document,
by referring to an anchor that we defined in the html file. For instance in this example:
<section title=”Chapter 2: Store Aliens Data” ref=”test.htm#chapter2″>
We associate the section ”Chapter 2: Store Aliens data” to the anchor ”chapter2” that was defined in test.htm.
The section ”keywords” is where we define the keywords that we can use to search for contents in the help index. For instance in the following line we associate the keyword ”logbooks” with a section of the file test.htm where we defined an anchor. The id, is an identifier that lets us refer this in the code (for instance creating a context sensitive help).
<keyword name=”logbooks” id=” Myprog::logbooks” ref=”test.htm#logbooks”/>
Finally, in the ”files” section we register all the files that we want to include in the
help project (in this case only two html files).

Viewing the Help
During production stage, the Help team may not have access to a running application to view the Help. That is not a problem, since we can view the help files using the standalone Help viewer from Qt: the Qt Assistant. Assuming you do not have it already, you just have to install the Qt Sdk from Digia and call the Qt Assistant (on Windows go to the ”Start Menu”, and choose ”QT SDKx− > T ools− > QtAssistant”). To register the manual go to ”Edit− > pref erences− > documentation” and add the path to the qhc file. If everything goes well, the index file and the table of contents should be displayed on the left panel; the contents will be displayed on the right panel.
Image

Some (Very Important) Things to Keep in Mind when Writing the Help
This section highlights some ”mistakes” that the help team I was working with, faced.
I learn that even some things that seem obvious to programmers, may *not* be obvious at all, to people who are not used to deal with technical constraints (e.g.: syntax); this is not a problem, as long as we are aware of them and describe everything properly.

 Startup Page
It is advisable to have a startup page, to work as a ”face” of the help collection. In our example, this page (index.htm) is located in this url:
qthelp: myprog.app.11b/doc/index.htm
In this file, we display a small introduction and the toc. On the table of contents of the project file, the section that contains the face page, should be the outer section: i.e., the one that contains all the other ones!
<sectiontitle=”Myprog 1.1b Manual” ref=”index.htm”>.... </ section>

 Consistency of Titles Across Project
The titles of the different sections should be consistent across the project, i.e.: make sure to double check the titles on:

  • table of contents (in our example in ”index.htm”)
  • along the html document
  • in the definition of the index of the qhp file.

In this example I opted for removing the words ”Chapter” from everywhere, except the structure on the qhp file. When using chapter numbers, choose a numbering system and remember to keep using it consistently, i.e., romans, literals, etc.

Consistency of Structure Across Project
The same thing applies to the structure of the help: make sure to keep the same nested
structure across table of contents, help html file and help definition file.

Creating the Name Tags
The name tags should enclose the section, since they contain the contents that we went to reference. For instance this is correct:
<a c l a s s=”mozTocH3” name=” mozTocId527307 ”>
Createa new frame by copy a pre−existent one</a>

and this is not correct! (although it works, we are referencing an empty content before the section title)
<a class=”mozTocH3” name=” mozTocId527307 ”>
</a>Create a new frame by copy a pre−existent one

It is advisable to use human-friendly tags, to easily assimilate the references through code and avoid mistakes. For instance to reference ”Create a new frame by copy a pre-existent one”, we may use name=”pre-existent” instead of name=”mozTocH3”!

Keywords
The section Keywords in the qhp file is very important, as it allows us to use the search
function on index, and also to create a context sensitive help in the UI. Please allow
some time to define a few important keywords in the content.

Paths on the qhp File (IMPORTANT!)
The paths on the qhp file, are the reference that allows the user to navigate through the
help contents; therefore it is very important for the help project, that they are correct!
On the path:
”userguide30122011.html#logbooks”
We have two parts.
”userguide30122011.html”
is the name of the html file: make sure this file exists and the name is spell correctly
(including extension)!
”logbooks”
is the part after the # and it references a tag, which means somewhere in the html
file we must have something like this:
<a name=”logbooks”>logbooks</a>
You need to ensure this exists. Take some time to make sure each one of the entries
on section < toc > qhp file is valid!

<section title="Introduction"
ref="user_guide_30_12_2011.html#mozTocId386761"/>
<section title="Chapter 1: Overview of Myprog 1.1"
ref="user_guide_30_12_2011.html#mozTocId42934">
....

The same applies to section “keywords” of this file: make sure all the keyword
references exist and are valid; the same applies to the toc on file ”index.html”

Registering html files
On the end of the qhp file, make sure all the html files contained in this project are
correctly listed, in order to be registered by the compiler. In this project:

<files>
<file>index.htm</file>
<file>user_guide_30_12_2011.html</file>
</files>

All the files used in the help project, must be included with the < f ile > tag: this includes all the image files (jpg, png, etc)!

Conclusions
Overall I think the Qt Help framework presents a an easy solution, that makes the creation of help a less ”tedious” task. The ”separation” between the help and the application, makes it possible:

  • to develop and test the help, without having the source code of the application.
  • to implement the help without having any knowledge of programming (although

a basic knowledge of markups, such as XML and HTML would be nice!).
However we do not want the help to be completely ”separated” from the application. In
fact, there is a ”part” of the help that is linked closely to the application: what we call
context sensitive help. This part requires implementing calls to the help engine on the
code, and I though I would leave it to another article.
Finally, as a ”goodie” for using Qt, the help is also completely portable across OS.

References
[1] Doxygen. Doxygen,http://www.stack.nl/~dimitri/doxygen/
[2] wikipedia. winhelp,https://en.wikipedia.org/wiki/WinHelp
[3] Innovasys. HelpStudio Lite,http://www.innovasys.com/product/hsli/overview.aspx?cpid=vssdk
[4] Digia. Qt,http://qt.digia.com/
[5] Digia. Qt Help,http://doc.qt.digia.com/4.6-snapshot/qthelp-framework.html

Advertisements

4 thoughts on “HELP

  1. What is actually causing the sections to be nested in the table of contents? It just looks like a list of tags with nothing to indicate nesting level. When I try this, it just creates a list of topics all at the same level.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s