Writing the Online Help

The online help (including this) and printed manual for our programs are written using Texinfo. However due to the usage of pictures (which aren't supported by Texinfo) we've made several modifications to the documentation system. We have modified makeinfo and texi2html scripts too. Consequently the system we use for documentation is not ready for public usage.

However the final files needed for online usage by the applications can be produce by any system capable of creating HTML files and our own `.index' and `.topic' files.

The principle method of bringing up help from a package is to use the show_help command. For the composition widget we used the following.

show_help %composition Composition

The %composition indicates that the show_help command should read the `composition.topic' and `composition.index' files. These are normally read from the `$STADENROOT/manual/' directory, but by preceeding the name with a percent sign we can direct the show_help command to search for these files in the composition package directory.

The last argument of show_help is the topic to display. In this case it is Composition. If the topic includes spaces then remember to use the Tcl quoting mechanism. The topic file is then scanned to find and line with this topic as the first 'word'. The second 'word' contains the index name. The index name is then looked up in the index file (as the first word) to find the URL (the second word). This two stage lookup is designed to protect against renaming section headings in the documentation. The index file can be easily created by parsing the html files to generate a mapping of heading names to URLs. However if the documentation changes we do not wish to need to change the Tcl calls to show_help.

composition.topic file:

    {Composition} {Composition}

composition.index file:

    {Composition} composition.html

For the composition package we have very simple topic and index files. The index and topic names are identical, so the topic file is trivial. The index file contains a single line mapping the Composition index entry to the composition.html file. If a named tag within the html file is needed then the URL would be composition.html#tagname. The html file itself is held within the same directory as the topic and index files.