The File menu contains commands for creating, opening, closing, and saving files edited with HoTMetaL PRO, previewing the current document with a browser, and modifying URLs.

New...

When you invoke this command a new, empty HoTMetaL PRO document is displayed in a document window.

Open...

Opens a previously saved file.

HoTMetaL PRO presents you with a dialog box allowing you to open a file. The dialog box is called a file selection dialog; a similar dialog box appears when you select the Save As... command. For the Open... command, the file selection dialog box looks like this:


The structure and function of the file selection dialog box for the Open... command is explained here.

The dialog box has several parts:

• A drop-down list box labeled List Files of Type. This list box lets you choose whether to display files with the default file extension (.htm) or display all files in the current directory.
• a text box labeled File Name

  This text box can contain a relative or absolute path name, which terminates in a file name or directory name, and can optionally start with a drive name. A file name (which may contain an extension) can contain the following "wildcard" (special) characters:

  • * (asterisk): matches any sequence of characters in a file name
  • ? (question mark): matches any single character in a file name
  Such a pattern containing wildcard characters is used to filter the file names displayed in the list box directly below. You can type a pattern in the box directly or choose it from the List Files of Type list.

  If the File Name box contains a path name that ends in a file name without wildcard characters, clicking on [OK] will cause that file to be opened.

• an information field labeled Directories

  The current directory (including the drive name) appears underneath the label. The default directory is the one specified first by the import_path configuration variable.

• a list box underneath the File Name text box

  This list contains the files in the current directory that match the pattern in the File Name box. The list of files is updated whenever a new directory is chosen, and when you click on the [OK] button.

  Clicking once on a file in this list causes the name to go in the File Name box. Double-clicking causes the file to be opened. This has the same effect as clicking once on the file name and then clicking on the [OK] button.

• a list box, on the right side of the dialog, underneath the Directories information field

  This box allows you to navigate in the directory structure of a drive by double-clicking on the directories shown in the list. The top level "directory" displayed is the current drive; if you double-click on this directory, its subdirectories are displayed, slightly indented to indicate the nesting relationship. If you click on one of these directories, its subdirectories will be displayed, and so forth. At any particular time the list will display the sequence of directories that you have navigated along, ending with the subdirectories of the last directory you selected.

• A drop-down list box labeled Drives. This allows you to choose which drive to navigate.

By pressing KEY:Tab or KEY:Shift-Tab you can make the File Name box, the list of directories, the list of files, or either of the buttons the active item in the dialog box. When either of the lists is active, you can select a list item by pressing repeatedly on the first letter of the item until it is selected. When the File Name box is active, you can enter text in it.

In summary: you may select a directory from which a file may be opened by using the list of directories, or by typing the path name in the File Name text box. You may choose a file by doing one of the following:

• double-clicking in the list of files
• selecting a file in the list of files and then clicking on [OK]
• entering the file name in the File Name text box and clicking on [OK]

Error checking

As the file is being opened, HoTMetaL PRO checks for fatal SGML errors. Fatal errors include start-tags without matching end-tags, invalid element names, and many other SGML errors. In such cases, HoTMetaL PRO displays a message describing the problem. It then gives you the following choices:

1. Invoke the Import Through Filter... command, which allows you to run the file through a filter that may correct the errors. See the section on this command for more information.
2. Open the file as a text file so that you can correct the errors manually. When you've done this, you can run the Interpret Document command, which performs the equivalent of Open.. on the text document.
3. Cancel the operation and correct the error(s) through other means.

If no errors are found, the file is formatted, checked once more for errors as if the Turn Rules Checking On command in the Special menu had been selected for the new file. At this stage, non-fatal errors may be detected. Examples of these are incorrectly placed elements, and text at a point where no text is permitted. Errors of this kind do not prevent the file from being opened.

Finally the file is validated: this stage of error checking ensures that the HTML markup is correct and complete. The following example illustrates the difference between rules checking and validation: if you open a file that has an HTML element that does not contain a FRONT element, rules checking will not complain, because you have not yet violated the rules file. Validation, however, will alert you to the fact that the required FRONT element is missing.

DOCTYPE declarations

There will sometimes be a document type declaration (DOCTYPE) at the top of an SGML file, specifying which rules file to use. This declaration is ignored with files being opened with HoTMetaL PRO, because all HTML files use the HTML rules file.

Open Template...

This command allows you to work with templates, which are pre-defined structures for documents. Templates are used as forms or document outlines that you can enter text into without having to insert any of the markup yourself.

Opening a template

To open a template, click on the Open Template... command. This brings up a file selection dialog box labeled Open Template. If you have a templates directory (see below) the dialog box will display the all files from that directory. Each file corresponds to a template: to open a template, just open it as you would any other file. The document name in the title bar will be the same as the template name, but with a number added to the first part of the filename: for example, the first time you open a template called fax.htm, the new document will be called fax1.htm, the second time the document will be called fax2.htm, and so forth.

When the template file is opened you can enter text or elements into it, and later save the file. When you save the file, you will have use the Save As... command and choose a new file name--the name in the title bar is not automatically adopted. If you save this file in the templates directory, make sure you do not overwrite the original template file by mistake.

Creating your own templates

A number of templates are shipped with HoTMetaL PRO, but it is expected that you will normally be working with templates that were created at your own site.

Templates directory

In order to work with templates successfully, a directory must be designated as the templates directory. This is a central location containing all of your template files, and it is the directory whose files are displayed when the Open Templates... dialog box comes up. By default, this is the directory called tmplts in the directory where HoTMetaL PRO is installed.

If you want to use another directory for this purpose, you will have to name that directory using the templates_path configuration variable. For example:
templates_path=c:\susan\tmplts

If the default templates directory does not exist (perhaps someone has removed it), and no alternative directory is specified with the templates_path variable, the current directory will be used as the templates directory.

Creating templates

To create a template file with HoTMetaL PRO, you should do the following:

1. Create a document as you normally would.
2. Invoke the Save As... command in the File menu.
3. Choose a directory and filename. You can save the file directly in the templates directory, or move it there later.
4. Click on the [Save As] button.

Installing a template

When the template file has been created, it should be saved in the templates directory (or you can save it elsewhere and move it later) so that it will be easily accessible from the Open Template dialog box.

Import Through Filter...

This command lets you pass an existing document through a filter before opening it with HoTMetaL PRO. You can supply filters for a variety of purposes, but one of the most frequent uses of this command is to "massage" a document which may not be properly marked up in the HTML format, and therefore not able to be opened by HoTMetaL PRO. For this purpose, a filter called tidy is supplied with HoTMetaL PRO. Another use for this command is when opening a document that is not yet in HTML format at all: you can pass it through a filter to convert it to HTML before opening it.

The Import Through Filter dialog box contains controls for choosing the filter and the file that is to be passed through it.

You can enter a command line for the filter in the text box labeled Filter. Alternatively, you can choose a filter from the drop-down list box to the right of the text box. This contains a predefined list of filter commands. The commands in this list come from a file named by the filter_list configuration variable. For more information, see the chapter The configuration mechanism. (If you have purchased the HTML filters from Avalanche, this file would be a convenient place to list them.)

If the filter command contains the text `$FILE', the filename you chose will be substituted for this when the command is run. Otherwise, the command will use the file as its standard input (equivalent to prepending `< $FILE' to the command line).

You can specify the file that you wish to pass through the filter by entering the name in the text box labeled File. You can also choose a file name by clicking on the [Choose File...] button and choosing the file from the file selection dialog box that appears. The filename you choose will then appear in the File text box.

When you've made your choices, click on the [Import] button. The file will be passed through the filter, and the resulting output sent to a temporary file. HoTMetaL PRO will then attempt to open this temporary file.

The `tidy' filter

One of the choices in the list of filters described above is a program called tidy. Our experience has indicated that this filter is able to convert approximately 90% of invalid documents into a form that can be opened by HoTMetaL PRO.

Save

This command saves the current file (that is, the file that is opened in the active document window) to disk.

HoTMetaL PRO saves the document in the file name shown in the title bar at the top of the window.

Save options

There are several save options that you may set if you need to do so. All of these options are set using configuration variables:

• You may choose to save a document type declaration (DOCTYPE), at the top of the file. The default may be set using the export_doc_type_dec configuration variable.

• You may choose to save an SGML declaration at the top of the file. The default may be set using the export_sgml_dec configuration variable.

  Note:Normally you should use this feature only if your file will be used by some other SGML system. Some browsers may not be able to read an SGML declaration. Mosaic can read the declaration but will display a comment field from the declaration at the top of the browser window.

• If your file contains special characters (those outside the ASCII range 0-127), you may choose to have these converted to SGML character references when the file is saved. This situation arises only if your file was edited with another editor. Special characters that are entered in the document when it is being edited with HoTMetaL PRO will be converted immediately to character entity icons. Character references are represented in a HoTMetaL PRO document as a small, rectangular icon, similar to a character entity icon, labelled `#nnn', where the n's are numbers. For example: {#200}. Mosaic will display a character reference as the character itself. The default setting for this option (ON or OFF) may be set with the export_convert_special_chars configuration variable.

• You can choose the character(s) that HoTMetaL PRO uses to mark the end of a line in the saved file. You may choose one of the values MAC, UNIX, and MSDOS, which will cause the end-of-line character to be carriage return, line feed, or carriage return and line feed, respectively The default end-of-line marker can be set with the export_eol configuration variable. If you don't provide a value for this variable, the default will be UNIX.

• For elements that are formatted in fill mode (see the documentation on the Characters... menu item) you can set the length of lines in the saved file by telling HoTMetaL PRO to insert end-of-line characters after a specified number of characters. This option can be turned on or off by default with the export_add_line_breaks configuration variable..The number of characters in a line can be set with the export_max_line_len configuration variable. HoTMetaL PRO will not cause a line break in the saved file to occur between an element and adjoining text.

If you have rules checking turned on, the file will be validated, and you will be warned if there are errors and asked if you still want to save. If you do, the file will be invalid and HoTMetaL PRO may have trouble opening it in the future.

Save As...

This command lets you choose a new name for the current document. When you save a file with this command, HoTMetaL PRO creates a new file whose content is the same as the current file, and closes the current file, leaving the new file open.

The document that was closed will look the same as it did the last time it was saved: any changes that were made since the last save will be saved in the newly created file.

HoTMetaL PRO gives you the file selection dialog box with which to specify the name of the new file.

You should follow the same instructions for selecting a file or directory as were described in the section on the Open... command.

The save options that were specified for Save will also apply to the Save As... command. Save As... will validate the file if rules checking is turned on, just as Save does.

Close File

This command closes the current file. If the file has had changes made to it since it was last saved, you will be prompted to save the changes before closing it.

Preview

When you invoke this command it will launch a browser to display the file. If the file hasn't been saved since changes were last made to it, HoTMetaL PRO will prompt you to save the file. You then have the choice of saving the file or proceeding with the previewing operation without saving (in which case the document is saved to a temporary file automatically). The command line for the browser that is launched by this command is specified using the html_browser configuration variable. The default value for this variable (and therefore the default browser) is c:\mosaic\mosaic.exe.

Publish...

Before a completed HTML document is moved to a WWW server, all URLs should refer to documents that are available on some WWW server. (While the document is being created, they may refer to documents on your local system.) The Publish... command gives you the opportunity to edit all the URLs, modifying them if necessary.

For example, when you are creating a document the URLs may consist of local filenames such as:
file:///c|/rodney/orwell/homage.htm
When the document is placed on your server, you must substitute URLs that refer to documents that are available on your server or some other server. For example:
http://sqrex.sq.com/sqmosaic/orwell/homage.htm

When you invoke Publish... you will get a dialog box containing two text boxes.

The first box (labeled Change URLs From) contains a part of the URL that you want to change; the second box (labeled To) contains the string that you want to change it to. The default values in these two boxes are specified by two configuration variables: publish_change_from specifies the part of the URL that should be changed; publish_change_to specifies the new value for this part of the URL.

If there were a large number of URLs for which you needed to change a local directory such as file:///c|/rodneyto a directory on the server, such as http://sqrex.sq.com/sqmosaic, you could set your configuration variables as follows:
publish_change_from=file:///c|/rodney publish_change_to=http://sqrex.sq.com/sqmosaic

This would cause the Change URLs From text box to contain "file:///c|/rodney" and the To text box to contain "http://sqrex.sq.com/sqmosaic".

Finding and Replacing URLs

When you click on the [Find Next] button, HoTMetaL PRO finds the next element that has an attribute representing a URL (often the HREF attribute of the element A and the SRC attribute of the element IMG). The search starts at the insertion point (or selection).

When an element with a URL is found, the insertion point is placed inside that element, and the document scrolls to its location.

If the URL contains the text in the Change URLs From box, clicking on the [Replace] button will change it to the text in the To box.

Clicking on the [Replace All] button will make this change for all URLs in the document that contain the Change URLs From text. This also causes the dialog box to be dismissed.

You can edit the Change URLs From and To text if you want to perform substitutions other than the default one.

The searching performed by this command does not wrap around from the bottom to the top of the file.

Exit

Quits HoTMetaL PRO. If an open file has been changed since the last time it was saved, you will be prompted to save the file before exiting.