OOMMF Help Browser Programmer's Reference

Contents

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

Overview

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

Help Browser Display Capabilities

The OOMMF Help Browser displays two types of pages, plain text and hypertext. Each page displayed by the OOMMF Help Browser is stored as a file. The OOMMF Help Browser 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 the OOMMF Help Browser. The mapping of file extensions to content type within the OOMMF Help Browser is not case-sensitive.

Plain Text Page Display

When the OOMMF Help Browser 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 browser 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 the OOMMF Help Browser.

Hypertext Page Display

When the OOMMF Help Browser 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 version of HyperText Markup Language (HTML). Specifically, it interprets the contents of the file (nearly*) according to the Strict HTML Level 1 Document Type Definition (DTD). The Strict HTML Level 1 DTD is part of RFC 1866, available from several sources on the World Wide Web. Briefly, Strict HTML Level 1 is a simple form of HTML, the language used to write hypertext pages for the World Wide Web. It includes markup for title, headings, paragraphs, lists (ordered, unordered, and definition), anchors (hyperlinks), images, and other basic hypertext elements. It does not include markup tags used to generate forms, tables, frames, applets or other advanced hypertext features supported by World Wide Web browsers. When confronted with unsupported markup tags, the OOMMF Help Browser makes an attempt to display something reasonable, but pages written for this browser should try to stick to legal Strict HTML Level 1.

When rendering an image element, denoted by the <IMG> tag, the OOMMF Help Browser 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.

Rather than reproduce the detailed rules of syntax for Strict HTML Level 1 which are already available in the DTD, an example page is provided, both as hypertext and as plain text, which contains example usage of all the markup tags supported by the OOMMF Help Browser.

*There are two rarely-used tags which are part of Strict HTML Level 1 which are not supported by the OOMMF Help Browser: <DIR> and <MENU>.

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 the OOMMF Help Browser supports only URLs with the scheme file. Such URLs are used to access files on the local disk. Future versions of the OOMMF Help Browser 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 table of contents page when the OOMMF Help Browser is first called. For more information, see the section on calling the OOMMF Help Browser.

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 the restricted form of HTML recognized by the OOMMF Help Browser, Strict HTML Level 1.

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

When testing help files, it is recommended that documentation authors check the Strict HTML Level 1 option under the OOMMF Help Browser's Options Menu. The default behavior of the browser is to silently recover from invalid markup as best it can. When testing with the Strict HTML Level 1 option enabled, the OOMMF Help Browser responds to invalid markup by displaying an error message which should help the author correct the markup.

Calling the OOMMF Help Browser

The OOMMF Help Browser 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 browser 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]