Prev Next running

Running The OMhelp program

Syntax
omhelp root_file [ -debug ] [ -xml ] [ -printable ] [ -noframe ] [ -nowarn ] [ -image_link image_link ] [ -image_file image_file ] [ -favicon favicon ] [ -site name ] [ -omhelp dir ]

Purpose
The omhelp command starts OMhelp from a DOS or Unix prompt. This creates a web site from the OMhelp input files are described in this manual.

It is suggested that you run OMhelp in an empty directory so that the only files in that directory will be those generated by OMhelp. This suggestion is made because OMhelp will create a large number of output files that correspond to the web site.

Output File Names
OMhelp outputs files in the current directory. The file name
     tag.ext
corresponds to the section which has tag as its cross reference tag . Here ext is htm, unless the xml command line option is specified in which case it is xml. The file
     index.htm
is special to browsers because it is loaded when the corresponding directory, but not a specific file, is specified. OMhelp automatically generates a file with this name that loads the section corresponding to the argument root_file.

Exit Status
If OMhelp executes with out detecting any errors, it exit status is zero. Otherwise, its exit status is non-zero.

root_file
The command line argument root_file specifies the file that contains the root section for the web site; i.e., the section at the root of the table of contents. This file can contain only one begin command because the tree can have only one section at its root. Other input files can be included using the contents, childtable, and children commands.

It is recommended that you run OMhelp in a different directory than the location of the starting input file (see Program Execution above). If you insist on running OMhelp in the directory containing the file specified by root_file, place ./ or .\ at the beginning of root_file.

debug
If the command line argument -debug is present, extra output that aids in the debugging OMhelp input files is generated. This includes the following:

Input Files
The name of the OMhelp input file corresponding to each section is included at the bottom of each section.

External Links
A list of all the external internet references; i.e., references created using the href command, is output as a separate section; for example, see external references for this manual . This aids in checking the validity of external references.

Spelling Errors
A file called error.wrd containing an alphabetic list of all the misspelled words is generated. In some cases, you may decide that some or all of there words should be added to local.wrd. In this case, see the dictionary instructions for installing under Unix or Windows .

xml
If the command line argument -xml is present, an XHTML version of the web site is built (otherwise an HTML version is built). In this case the output files have the .xml extension (otherwise they have the .htm extension). This enables the support of latex commands in OMhelp input files using XHTML and MathML (see Chapter 7 of MathML ).

printable
If the command line argument -printable is present, a printable version of the web site is output as just one file The name of the file is _printable.htm (_printable.xml if the -xml is present). In the printable file, each section title and heading is labeled with an identifier so that it can be located by its position in the output file. These position identifies are included in the linking text for each cross reference so that the target of the reference can be located by its position in the output file.

The printable output file does not contain the OMhelp search section because printed output is not interactive. Thus, if you are using the printable option, the cross reference tag _search will not be defined. You can see the printable version of the OMhelp documentation by selecting _printable.htm () .

The -printable command overrides the normal behavior of the fend command.

noframe
By default, OMhelp puts the automatically generated navigation links in a frame to the left of the user generated information. In addition, the user can divide the right side into separate frames. If the command line option -noframe is present, all of the information for a section is displayed in one frame. This overrides the normal behavior of the fend command.

nowarn
OMhelp warnings are printed as messages on standard out . For example, spelling errors and undefined cross references are displayed as warnings but do not terminate processing. You can suppress the display of these warning messages using the -nowarn command line option.

image_link
If the command line argument -image_link is present, the argument image_link must follow it. In this case, the image is placed at the top of the links for each section ( -image_file image_file can be used to specify your own image, which should be about the same size as the default image). If image_link is equal to the empty string (""), the image does not link to anything. Otherwise, image_link specifies a world wide web address (URL) that is linked to when the image is selected.

image_file
A default image file (_image.gif) is distributed with OMhelp. If the command line argument -image_file is present, the argument image_file must follow. In this case, the default image is replaced by image_file, which should be about the same size as the default image. The text image_file can either a complete path specification or relative to the directory containing the file specified by root_file. Note that the directories specified by the path commands are not searched for the file specified by image_file.

favicon
If the command line argument -favicon is present, the argument favicon must follow. In this case, favicon should be a 16 by 16 pixel icon and the file extension .png (you can use the Microsoft Paint program to create and store such an icon). The text favicon can either a complete path specification or relative to the directory containing the file specified by root_file. Note that the directories specified by the path commands are not searched for the file specified by favicon.

The -favicon command line option was used when building the OMhelp web documentation. If you view this documentaiton , you should see the icon at the left of the address bar in your browser. (This icon corresponds to the file omh/image/help_icon.png in the OMhelp distribution.) This works well in Firefox, but there currently seem to be some problems with Internet Explorer .

site
If the command line argument -site is present, the argument name must follow. In this case name specifies the name of the web site being built. This name is currently used in the title for the web site search utility. It may have other uses in the future.

omhelp_dir
If the command line argument -omhelp_dir is present, the argument dir must follow. In this case dir specifies the directory where the OMhelp data is stored; for example, the files english.wrd and local.wrd. This is intended for testing during installation and should not be necessary during normal use.

Example
See the Getting Started example in the Unix or Windows installation instructions.
Input File: running.omh