Working with files

This chapter discusses the HoTMetaL PRO commands for creating, opening, closing, and saving files, previewing the current document with a browser, and checking document correctness.

Creating a new file

There are two ways to create a new file:

Using templates

Templates are pre-defined structures for documents. They are used as forms or document outlines that you can enter text into without necessarily having to insert any of the markup yourself.

Opening a template

To open a template, choose the New... command from the File menu. This brings up a dialog box that displays several template groups. (These groups correspond to directories in the templates directory.)

TEMPLATE

To open a template:

When the template file is opened you can enter text or elements into it, and later save the file.

Creating your own templates

A number of templates are shipped with HoTMetaL PRO, but you can create your own templates, too.

To create a template file with HoTMetaL PRO:

To create a new template group, just create a new directory in the templates directory.

You can choose the default directory for opening templates in the Extensions/Paths section of the Options dialog box.

Opening a file

Choose Open... from the File menu (or click on the OPENICON toolbar button) to open an existing file. The default file extension in the Open dialog box is .html.

You can choose the default directory and file extension for the Open dialog box using the Extensions/Paths section of the Options dialog. Choose an extension and path in the Document line.

When you open a file, HoTMetaL PRO converts the `raw HTML' into a graphical format in which the tags are replaced by tag icons, and HoTMetaL PRO's graphical editing features are available. You cannot open a file that's already open.

The names of the last four files that you opened with HoTMetaL PRO are added to the File menu. You can open a file (or make it the current file, if it's already open) by choosing it from this menu.

Choosing the Documents... command in the File menu gives you a dialog box that contains a list of the open files. To make a particular file the current file, click once on the filename. Leaving this dialog box open on the screen also provides quick access to the New and Open... commands. To choose one of these commands, click on the appropriate button.

Conversion from other formats

The Open... command has several built-in filters that let you open files in other word-processing formats, as well as plain text. These files are converted into HTML. In any case, the conversion program determines the file format automatically.

HoTMetaL PRO supports the following common word-processor formats:

In addition, the following formats are supported:

You will get an error message if the file is not in one of the supported formats.

If a file is in an unsupported format, you may be able to open it and save it in a supported format with another application.

If a document contains a graphic in one of the supported graphics formats, it will be converted to GIF format and saved in a separate file. An IMG element whose URL contains the full path to the GIF will be placed in the converted document. HoTMetaL PRO will convert graphics in BMP, GIF, JPEG (JFIF), MacPaint, PCX, and TIFF format. In addition, HoTMetaL PRO can convert the raster, or bitmap-oriented, portions of the following complex graphic types: EPS, PICT, RTF, SDW (AMI Draw), WMF, and WPG (WordPerfect Graphics). HoTMetaL PRO will not convert vector, or outline-oriented, graphics in these formats, such as embedded pie-charts or equations.

Graphics that are inserted in word-processor files by means of links (rather than inserted directly in the file) will not be converted.

When HoTMetaL PRO converts a word-processor file, paragraphs are converted to P elements, quoted paragraphs to BLOCKQUOTE, headings to H1-H6, numbered lists to OL, bulleted lists to UL, bold text to B, italic text to I, graphics to IMG, and tables to HTML tables.

The conversion program uses various guidelines to decide how to perform the conversions; because word-processor files tend to be less structured than HTML, you will probably need to do some refinement of the markup using HoTMetaL PRO's markup tools. Also, the conversion doesn't employ the full HTML element set so you may wish to use `richer' markup. In any case, you should always review the converted file before putting it on the Web.

You can configure how HoTMetaL PRO converts paragraphs, blockquotes, and headings by editing a configuration file. See Appendix 2: File conversion for more information.

Error checking

If an HTML file contains markup errors, HoTMetaL PRO will try to rearrange the markup so that the file can be opened and displayed in graphical format. In those situations, HoTMetaL PRO will usually succeed in creating a valid file, although you may have to adjust some of the markup manually. If HoTMetaL PRO cannot turn on rules checking it will give a warning message informing you of the problem, and the insertion point will move to the location of the error.

In some cases rules checking can be turned on but the file will not validate. This normally means that some element is missing a required sub-element or a required attribute: for example, an OL might not have any LI elements in it, or an INPUT element may be missing a value for the NAME attribute. HoTMetaL PRO does not inform you automatically if the file will not validate: you can check if the file validates by choosing Validate Document from the Special menu.

If HoTMetaL PRO encounters an HTML error that is so serious that the file cannot be opened in graphical format (for example, if the file contains a non-HTML element), it will open the file as a text file. This gives you the opportunity to correct the error manually. After you've done so, choose Interpret Document from the Special menu. If the document contains no more errors, this performs the equivalent of Open... on the text document. Otherwise, you will get a message indicating the next error.

Common `Open' error messages

If HoTMetaL PRO encounters an element at a location that the HTML rules don't allow, it will try to move the element to the next valid location. If it is unable to do so, the file will be opened, but rules checking will not be turned on. The insertion point will be placed at the location of the invalid element, and you will get an error message such as the following: 

Rules checking cannot be turned on:
an invalid element "INPUT" was found.

This error message indicates that the element called INPUT was found at an invalid location. The solution is to move the element to a location where it is allowed (in this case, inside a FORM), and then turn rules checking back on by choosing Turn Rules Checking On from the Special menu.

There are a number of errors that will prevent HoTMetaL PRO from being able to open the file in graphical format. In this case, you will get an error message, the file will be opened in text format, and the insertion point will move to the location of the error. After you correct the error, you should choose Interpret Document from the Special menu to do the equivalent of Open... on the text document.

All of these error messages will give the location in the document where the error occurred. For example: 

Error at offset 211 of the input stream, on
line 6 of the document instance:

This means that HoTMetaL PRO detected the error on line 6 of the document, after reading 211 characters. You don't actually have to count the lines and characters to find the error, because HoTMetaL PRO will position the insertion point at the location of the error.

The remainder of the error message describes the specific error that occurred. Here are some common errors:

Unknown element

Unknown Element. The element "ENTER" is
not defined in the rules file.

This means that HoTMetaL PRO discovered an element that is not a valid HTML element. This can occur if the document contains a new proprietary extension element that is not currently supported by HoTMetaL PRO, or if a sequence of characters starts with the `<' character. In this example, HoTMetaL PRO detected an element called ENTER because the document contained the phrase `<Enter>'. The solution is to substitute the character entity `&ero;gt;' for the `<' character. That is, type the characters `&ero;gt;' instead of `<'; this expression will be displayed as `<' in HoTMetaL PRO and in the browser. If the problem is that a proprietary extension was used, you may wish to remove just the start- and end-tags of the non-HTML element, or remove the contents too.

Bad or missing name

Bad or missing attribute name.
Attribute "TYP" is not defined in the
attribute list.

This error will occur if an element has an invalid attribute name. This may be because the document is using a new proprietary extension attribute that is not supported by HoTMetaL PRO, or it may simply be the result of a typing error. For example:

<INPUT TYP="TEXT">

Here the attribute name should be TYPE, not TYP. Correct the attribute name and choose Interpret Document. If the document contains an unsupported extension, you will have to remove the attribute name and its assigned value.

End of file

End of file in literal string.

This error will occur if an attribute value in the document starts with a double quote, but doesn't end with one. For example: 

<INPUT TYPE="TEXT>

The value TEXT should have a double quote at the end. Insert the missing double quote and choose Interpret Document.

Bad start tag

Bad start tag.

This error can occur if you have some unusual invalid markup that causes HoTMetaL PRO to infer that one element has been closed, and another one should start. For example: 

<INPUT TYPE="TEXT" &ero;eacute;

The solution in this case is to properly terminate the INPUT element, i.e.: 

<INPUT TYPE="TEXT"> &ero;eacute;

Bad or missing attribute value

Bad or missing attribute value.
Attribute name "HELLO" is not in any name
group in the attribute list for this element.

This error can occur if a start tag is not terminated properly, so that some following text appears to be the value one of the element's attributes. For example: 

<P Hello

The solution is to properly terminate the INPUT element, i.e.: 

<P> Hello

Saving files

The Save command (or the SAVEICON toolbar button) saves the current file (that is, the file that is open in the HoTMetaL PRO document window) to the disk. Files are always saved in HTML format.

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

To save the file under a new name, choose Save As... from the File menu.

You can choose the default directory for the Save and Save As dialog boxes in the Extensions/Paths section of the Options dialog box.

Note: A `document type declaration' (DOCTYPE) will be saved at the top of the file. This declaration is ignored by most browsers, but is used if your document is read by an SGML system.

Save options

There are a couple of options for saving files that you can set in the Save section of the Options dialog box.

Backups

If you want HoTMetaL PRO to make a backup file each time it saves a file, turn on the check box labeled Make backup file when saving changes in the Save section of the Options dialog box. The backup file will be a copy of the previously saved version of the file. The name of the backup file will be the current filename, with the file extension changed to the backup file extension (by default this is .bak, but you can choose a different extension from the same section of the Options dialog).

Auto-saving

HoTMetaL PRO will save the current file automatically after a specified number of minutes or after a specified number of changes have been made to it. Enter the values you want to use in the appropriate text entry boxes in the Save section of the Options dialog box. The default values are 64000 changes and 1000 minutes. If you want HoTMetaL PRO to warn you each time it does an auto-save, turn on the Inform when automatically saving check box.

Printing

Choose the Print... command in the File menu to print one or more pages of the current document.

The following dialog box appears:

PRINT

The six text entry boxes in the lower part of the dialog box allow you to describe the page header and footer by specifying the text of their left, middle, and right components.

There are a number of special strings you can put in headers and footers:

The screen formatting options currently in use for the different elements (font, font size, line height, etc.) will appear in the printed output. If tag icons are currently displayed on the screen, they will be printed.

You can select a spooler, such as lpr, or another program to process the output, by choosing the Options... command in the Special menu and entering a Print Filter option in the General section of the dialog box.

Closing a file

The Close command in the File menu 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.

Exiting

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.