mmHelp Programmer's Reference

Contents

  1. Overview
  2. mmHelp Display Capabilities
  3. Help Files and URLs
  4. Writing and Testing Your Help Files
  5. Calling mmHelp

Overview

mmHelp provides a standard way for OOMMF application programmers to provide help to the users of their applications. mmHelp displays pages of help information written in either plain text or hypertext. This reference describes how to create help pages to be displayed by mmHelp and how to call mmHelp from within your OOMMF application.

Help Browser Display Capabilities

mmHelp displays two types of pages, plain text and hypertext. Each page displayed by mmHelp is stored as a file. mmHelp uses the file extension to determine what type of page is stored in that file. Files with the extensions .html, .htm, or .htl are displayed as hypertext pages. Files with the extensions .txt, .text, .c, .cc, .c++, .cpp, .h, .hh, .java, .l, .pl, .sty, .y, and with no extension are displayed as plain text pages. Files with the extension .gif contain GIF images which may be embedded within hypertext pages. Files with other extensions are not displayable by mmHelp. The mapping of file extensions to content type within mmHelp is not case-sensitive.

Plain Text Page Display

When mmHelp determines the contents of a file to be plain text, based on the file's extension, it displays the contents of that file as text in the display window using a fixed-width font. Of course if the file does not actually contain text, the display may be nothing but garbage. Take care to only view files which actually contain text with mmHelp.

Hypertext Page Display

When mmHelp determines the contents of a file to be hypertext, based on the file's extension, it interprets the contents of that file as a simplified subset of HyperText Markup Language (HTML). The HTML elements supported by mmHelp are demonstrated in a sample page available both as hypertext and as plain text. When confronted with unsupported elements, mmHelp makes an attempt to display something reasonable, but pages written for mmHelp should try to stick to the supported elements.

When rendering an image element, denoted by the <IMG> tag, mmHelp is only able to display images in the GIF format. Images in other formats will not be displayed. The alternate text supplied by the ALT attribute of the <IMG> tag, if any, will be displayed instead.

Help Files and URLs

Each page of help information is stored as a separate file. Files are identified by filenames. Within HTML, sources of data are more generally called resources and are identified by Uniform Resource Locators (URLs). URLs are used to indicate the destination of a hyperlink (the HREF attribute of an <A> tag) and the source of an image (the SRC attribute of an <IMG> tag).

The specification of URL syntax is found in RFC 1738 and RFC 1808. The first part of a URL, up to the first colon, is called the scheme. For example, in the URL http://math.nist.gov/oommf/, the scheme is http. The current version of mmHelp supports only URLs with the scheme file. Such URLs are used to access files on the local disk. Future versions of mmHelp may add support for other URL schemes so that help files may be retrieved over a network.

Filenames have two forms, absolute and relative. For example, a file with the absolute filename C:\TCL\BIN\TCLSH76.EXE is also known by the relative filename TCLSH76.EXE when the current directory is C:\TCL\BIN. Likewise, URLs have absolute and relative forms. The absolute form includes all parts of the URL, beginning with the scheme. Relative URLs are expressed relative to the current URL, which is the URL of the document which contains the relative URL. For more details, see RFC 1808.

Within help files, only relative URLs should be used in <A> and <IMG> elements. Then as the help files are moved from directory to directory as part of the usual software installation process, navigation from one help page to another will continue to work. Absolute URLs should only be required for one purpose, the identification of the home page when mmHelp is first called. For more information, see the section on calling mmHelp.

Writing and Testing Your Help Files

The creation of text files containing plain text and hypertext help pages may be accomplished with any text editor. HTML markup is not difficult. There are many sources of documentation on HTML available. You may wish to use a special-purpose editor which generates HTML markup. If so, be sure that the editor is able to output HTML restricted to the limited set of elements recognized by mmHelp.

While editing help files, it is useful to frequently test that they can be viewed with mmHelp. See the section on calling mmHelp for instructions.

When testing help files, it is recommended that documentation authors check the Strict option under mmHelp's Options menu. The default behavior of mmHelp is to silently recover from invalid markup as best it can. When testing with the Strict option enabled, mmHelp responds to invalid markup by displaying an error message which should help the author correct the markup. (Note: This option disabled on 1-Oct-1998, because documention is being generated through LaTeX2HTML, which does not follow the "Strict" rules.)

Calling mmHelp

mmHelp is a separate application launched with the Exec subcommand of the Oc_Application class.

Oc_Application Exec mmHelp $url

where url contains the absolute URL of the table of contents page to be displayed first in the display window.

The usual method to generate the absolute URL for a particular file is to use the subcommands and methods of the Oc_Url class to convert an absolute filename to an equivalent absolute URL.

set url [[Oc_Url FromFilename $filename] ToString]