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.
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.
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.
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>.
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.
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.
The OOMMF Help Browser is written entirely in the Tcl language using standard Tcl commands, commands supplied by the Tk library, and a few other commands supplied by other Tcl packages distributed with the Helpbrowser. Any application which embeds Tcl/Tk should be capable of calling on the OOMMF Help Browser. For testing purposes, the standard wish application may be used.
The OOMMF Help Browser is launched with a single Tcl command, OMFHB_Browser which takes a single argument, the absolute URL of the table of contents page to be displayed first in the browser window. To make the command OMFHB_Browser available to the Tcl interpreter, the Tcl package HelpBrowser must be loaded. A sequence of Tcl commands suitable for calling the OOMMF Help Browser from Tcl version 7.6 and later is summarized below.
% lappend auto_path <directory containing the directory helpbrowser0.0>
% package require HelpBrowser 0
% OMFHB_Browser <absolute URL of table of contents page>
In Tcl 7.5 a different algorithm is used for searching the library path, so all subdirectories of the directory appended to the auto_path variable above also need to be appended to auto_path.
An absolute URL is required as the argument to OMFHB_HelpBrowser. A useful Tcl command for generating the absolute URL for a particular file is OMFURL_FileToUrl. It is part of the Tcl package Url, which gets loaded as part of loading the HelpBrowser package. The command OMFURL_FileToUrl takes a single argument, the name of the file for which the absolute URL is needed. The absolute URL is returned. This leads to the usage
% OMFHB_Browser [OMFURL_FileToUrl <table of contents filename>]
OOMMF applications should bind the call to OMFHB_Browser to a menu item under a Help Menu.