HoTMetaL PRO's configuration mechanism (sometimes called the sqconfig mechanism) lets you modify HoTMetaL PRO's behavior to suit your needs and those of your site.
There are two types of information in the configuration files. There are variables that control HoTMetaL PRO's behavior, and there are variables that give the location of files or directories.
There are many aspects of HoTMetaL PRO's behavior that you can configure to your personal needs or those of your site. For example, you can control default options in the Find and Replace dialog box, set options for the Save command, and specify the locations of various auxiliary files. Configuration is done using a mechanism called the sqconfig mechanism, or just the "configuration mechanism". You can run HoTMetaL PRO without any problems using the default configuration, but at some point you may prefer to customize. This will be particularly true if several people will be using HoTMetaL PRO on the same PC.
The default configuration files read by HoTMetaL PRO are the file sqhmpro.ini located in the directory where HoTMetaL PRO is installed and the file sqhmpro.ini in the Microsoft Windows directory (usually c:\windows). These files contain configuration parameters called configuration variables. Variables set in the file in the Windows directory take precedence.
You can specify that different files are read by the configuration mechanism, according to the following procedure:
To specify the files using the command line, you have to modify the HoTMetaL PRO command line using the Properties... command in the Windows File menu.
c:\hotmetal\sqhmpro.exe
-sqconfig c:\frances\sqhmpro.inic:\hotmetal\sqhmpro.exe
-sqconfig c:\frances\sqhmpro.ini;${SQDIR}\sqhmpro.ini(This example should be read as one line.) `${SQDIR}' means "replace this by the value of the SQDIR environment variable" (this variable, if it has a value, names the HoTMetaL PRO directory). This setting causes two files to be used: the file c:\frances\sqhmpro.ini, as before, and the file sqhmpro.ini located in the HoTMetaL PRO directory.
Note: the SQDIR (HoTMetaL PRO directory) may also be set on the command line. If so, the expression `${SQDIR}' will represent the value from the command line. See the section `Setting the HoTMetaL PRO directory' in the `A guide for the perplexed' chapter for full details.
If there is no -sqconfig option in the HoTMetaL PRO command line, but the DOS environment variable SQCONFIG names one or more files, then these will be used as configuration files. Here are examples of specifying configuration files using this method.
set SQCONFIG=c:\frances\sqhmpro.iniset SQCONFIG=c:\frances\sqhmpro.ini;${SQDIR}\sqhmpro.iniThe format for the value of the SQCONFIG variable is the same as for the value that can come after the -sqconfig command line option, as described above.
Environment variables can be set at the DOS prompt, or if you want them to be set every time the PC is booted, you can put the same settings in the autoexec.bat file.
If a number of configuration files are specified using the environment variable or the command line, HoTMetaL PRO reads the list of files from right to left, that is, in the reverse of the order in which they are listed. If a particular variable (parameter) has a setting in more than one file, the value in the file that is read last will take precedence. If a variable is defined more than once in the same file, the value which appears last in that file will take precedence over values that appear earlier in the file.
If a variable is not set in any configuration file, but is set in the environment, then the setting from the environment is used. If there is no setting in the configuration files or in the environment, then the built-in default value (if there is one) is used. If there is no default value, the variable is undefined.
In summary, the value of an sqconfig variable is taken from the following sources, in the order given below:
Configuration files (and configuration variables in the environment) are read by HoTMetaL PRO on start-up, so the changes you make will take effect the next time you run HoTMetaL PRO--they will have no effect on a currently-running HoTMetaL PRO. If you need them to take effect immediately, you will have to exit HoTMetaL PRO and restart it.
The following arrangement is one suggestion about how you can use configuration files. It involves using two files: a base file for variables that don't change very often, and a personal file for variables that change more frequently, are experimental, or are employed by a single user.
The base file should be used as a system configuration file. It should contain the settings that you want to be used as defaults. A parameter should be changed in this file only if you decide that its default value should change for everyone using HoTMetaL PRO on a specific PC. The file sqhmpro.ini in the HoTMetaL PRO directory should be used for this purpose.
The personal configuration file should be used if you need to override some of the settings in the base file without modifying the base file. For example, you may want to make temporary changes to some of the parameters, or to specify parameter values that are used only by you (or another individual user), rather than by everyone who uses HoTMetaL PRO on the computer. If your PC has only a single user, you may choose not to use the personal file at all. Or, you could use it only for making temporary changes to the configuration. The file sqhmpro.ini in the Windows directory should be used for this purpose.
You do not need to change any configuration variables unless you wish to customize the HoTMetaL PRO configuration.
A variable is just a name that is assigned some value. You can change these variables by simply editing the configuration files, as appropriate, and making the desired changes.
Variables
are assigned values by putting lines of the following form in the
configuration files: variable = value
For
example:undo_limit=50
undo_limit is a configuration variable that specifies the number of successive commands that can be undone or reversed with HoTMetaL PRO's Undo command. The default built in to HoTMetaL PRO is 10: to raise this to 50, you would set the variable as in the example.
You may put spaces or tabs on
either side of the equal sign for readability. Also, if you prefer, you
may substitute a colon (:) for the equal sign: undo_limit:50
The effect is the same.
You should not have any "white space" (spaces or tabs) at the end of the line.
If you don't want to set a particular variable, then you can do this by omitting or deleting any settings of that variable in the configuration files. Alternatively, you can "comment out" settings in these files by inserting the `#' character as the first character on all lines containing such settings: HoTMetaL PRO will ignore such lines.
For
example:#undo_limit=50
You should not try
to give variables a "null" value, e.g., undo_limit=
Or: tag_font_name=""
You should take care to use legal values for all the configuration variables. Otherwise, HoTMetaL PRO may behave in unexpected ways.
You can use the value of one
configuration variable when assigning the value of another variable. For
example:my_name_is=rodney
templates_path= d:\${my_name_is}\tmplts
The expression: ${my_name_is}
is equal to the current value of the
configuration variable (my_name_is) between the `{' and `}'. So
this expression is equal to `rodney'. When HoTMetaL PRO evaluates templates_path
in the last example, it substitutes `rodney' for `${my_name_is}', so
that the value of
templates_path becomes `d:\rodney\tmplts'. HoTMetaL PRO
performs this substitution when it uses the variable, not when
it reads the configuration files at start-up.
You can use the
same notation to cause HoTMetaL PRO to read a DOS environment variable.
For example, you could set an environment variable (at the DOS
prompt or in the autoexec.bat file):set MY_NAME=rodney
A configuration file could have the following setting:templates_path= d:\${MY_NAME}\tmplts
When templates_path is evaluated, `rodney' is substituted
for `${MY_NAME}', so that the value of templates_path becomes
`d:\rodney\tmplts'. As before, this substitution occurs when the
variable is used by HoTMetaL PRO, not at start-up.
The `$' symbol is used as a special character in configuration variables, so if you want to put a `$' in the value of an variable, you have to represent it with `$$'.
If
a configuration variable has already been assigned a value, you may wish
to append or prepend some characters to it. For example:
templates_path=c:\hotmetal\tmplts;
templates_path += d:\jennifer\tmplts;styles_path=c:\hotmetal\styles;
styles_path =+ d:\jennifer\styles;
In the first
example, the variable templates_path is first given the value
`c:\hotmetal\tmplts;'. The `+=' in the expression templates_path += d:\jennifer\tmplts;
causes `d:\jennifer\tmplts;' to be prepended to the current
value of
templates_path. The value of templates_path becomes
`d:\jennifer\templates;c:\hotmetal\templates;'.
In the second
example, the variable styles_path is first given the value
`c:\hotmetal\styles;'. The `=+' in the expression styles_path =+ d:\jennifer\styles;
causes `d:\jennifer\styles;' to be appended to the current
value of
styles_path. The value of styles_path becomes
`c:\hotmetal\styles;d:\jennifer\styles;'.
(In these examples, the semi-colon, `;', between the file names, is not inserted automatically by HoTMetaL PRO.)
If a variable does not already
have a value, then assigning it a value using `=+' or `+=' has the
same effect as just assigning a value using `='. For example, if templates_path
does not currently have a value, then templates_path+=c:\tmplts;
has the same effect astemplates_path=c:\tmplts;
These variables control various aspects of HoTMetaL PRO's behavior: save options, find and replace options, etc. Many of these variables take values of YES or NO; please note that YES, true, and 1 (one) are synonymous here, as are NO, false, and 0 (zero).
The following variables allow you to choose default save options for the Save and Save As... commands.
By default, HoTMetaL PRO will save the document type declaration (DOCTYPE) when it saves a file. If this variable is set to NO, then HoTMetaL PRO will not include the DOCTYPE with an exported file. If it is set to YES, or if it is not set at all, then the DOCTYPE will be saved with the file.
By default, HoTMetaL PRO will not export the SGML declaration when it exports a file. If this variable is set to YES, then the SGML declaration will be exported. If it is set to NO or omitted, then the SGML declaration is not exported.
By default, HoTMetaL PRO will not impose any limit on the length of a line in an saved file, i.e., it will not add any explicit line breaks. If this variable is set to YES, HoTMetaL PRO will add line breaks after the number of characters specified with the export_max_line_len variable (see below). If export_add_line_breaks is set to NO or omitted, no line breaks will be added.
If export_add_line_breaks is set to YES, lines will be
broken after a certain number of characters. You can set this number
with the variable export_max_line_len or in the dialog box,
e.g., export_max_line_len=60
If this variable is
not set, the default is 80 characters.
If this variable is set to YES, then HoTMetaL PRO will convert any special characters inserted directly in your document to SGML character references. (Special characters are those outside the ASCII range 0-127). This will apply only to special characters that were inserted if the file was modified or created by another editing package: special characters that are inserted using HoTMetaL PRO are immediately converted into character entity icons. Character references are supported by browsers such as Mosaic. If the variable is omitted or set to NO, then special characters are not converted.
This variable lets you choose the end-of-line marker that will be generated in your saved file. There are three choices: UNIX, which causes the end-of-line marker to be a line feed, MSDOS, which causes it to be a carriage return followed by a line feed, and MAC, which sets the marker to be a carriage return. The default value for this variable is MSDOS.
The next group of variables allow you to control the behavior of the commands in HoTMetaL PRO's Find menu. You may override all these settings from the dialog box that accompanies the Find and Replace... command.
By default, the Whole Words option is turned off in the Find & Replace dialog box. If this variable is set to YES, this option is turned on; if it is set to NO or undefined, Whole Words is turned off in the dialog box.
By default, the Case Sensitive option is turned off in the Find & Replace dialog box. If this variable is set to YES this option is turned on; if it is set to NO, or undefined, Case Sensitive is turned off in the dialog box.
By default, the Backwards Search option is turned off in the Find & Replace dialog box. If this variable is set to YES, this option is turned on; if it is set to NO, or undefined, Backwards Search is turned off in the dialog box.
By default, the Wrap option, which causes searches to encompass the entire file, starting at the current position, is turned on in the Find & Replace dialog box. If this variable is set to NO, Wrap will be turned off. If the variable is set to YES or not defined, wrapping will be turned on.
By default, the Find Patterns option is turned off in the Find & Replace dialog box. If this variable is set to YES, Find Patterns is turned on. If it is set to NO, or not defined, the Find Patterns option is turned off.
These variables govern aspects of the markup process.
This variable controls whether the Include Required Elements option is turned on for the Insert Element... command. If this variable is set to NO, the option will be turned off. If the variable is set to YES or undefined, the option will be on. For more information, see the section on Insert Element... in the Markup menu chapter.
This variable controls whether the Edit Attributes and Links dialog box will be displayed each time an element with attributes is inserted in the document. If it is set to NO, or undefined, then users will be prompted with this dialog only if the element being inserted has required attributes. If the variable is set to YES, then the user will be prompted every time an element with attributes is inserted.
The variables in this section pertain to HoTMetaL PRO's screen display: invisible characters, fonts for icons, and colors.
This variable lets you
choose the default font family for all documents opened with HoTMetaL
PRO. The value of this variable should be a font name, exactly as it
appears in the Font Family drop-down list box. For
example:
default_font_name=Times New Roman
The default
font family is Helvetica.
This
variable lets you choose the default font size for all documents opened
with HoTMetaL PRO. The value of this variable should be a positive
number. For example:default_font_size=14
The
default font size is 12 points.
This variable lets you choose the font used to display the element names in the tag icons in an HoTMetaL PRO document. The list of available fonts is dependent on your system and on the font source file that you are using. The best way to find out which fonts you can use is to invoke HoTMetaL PRO's Character... command and click on the arrow next to the drop-down list box labeled Font Family. The menu that appears contains the names of the available fonts. The value assigned to the tag_font_name variable should be the font name, not surrounded by quotes, exactly as it appears in the Font Family menu. The default font is Helvetica.
This variable lets you choose the font size used to display the element names in the tag icons in an HoTMetaL PRO document. The list of available font sizes is dependent on your system and on the font source file that you are using. The best way to find out which font sizes you can use is to invoke HoTMetaL PRO's Character... command and click on the arrow next to the drop-down list box labeled Font Size. The menu that appears contains the available font sizes. The value assigned to the tag_font_size variable should be the font size in points, not surrounded by quotes. The default is 12 points.
This variable lets you choose the font used to display the entity names in the character entity icons in an HoTMetaL PRO document. This variable has the same possible values, default, and is set in the same way as, tag_font_name, described above.
This variable lets you choose the font size used to display the character entity names in the entity icons in an HoTMetaL PRO document. This variable has the same possible values, default, and is set in the same way as, tag_font_size, described above.
This variable gives a command line for an HTML browser that is invoked by HoTMetaL PRO's Preview command. The default value is c:\mosaic\mosaic.exe.
This variable specifies the text that appears in the Change From text entry box in the Publish... command's dialog box. The default value is `file://'.
This variable specifies the text that appears in the Change To text entry box in the Publish... command's dialog box. The default value is `http://'.
This variable lets you set the default language used in spell checking, i.e., it determines which system dictionary is used. The languages normally available are American English and British English. The possible values for this variable are AMERICAN and BRITISH. These settings are not case sensitive. The default value is AMERICAN.
If this variable is set to TRUE, then any GIF images referred to by URLs in IMG or LINK elements will be displayed inline (in the HoTMetaL PRO document window) when a file is opened. Otherwise (if the variable is set to FALSE or not set) such images are hidden. You can override the show_inline_images setting using the Show/Hide Inline Images command. This command toggles to Hide Inline Images by default if the variable is set to TRUE, and to Show Inline Images otherwise.
This variable sets the maximum number of commands that can be undone with the Undo command. By default, this value is 10. The maximum value is 65535. The minimum value is one; if you set it to a value less than one, it will be set to one anyway.
This variable specifies a program that the Show Image command will invoke to display a file whose name ends with the .gif file extension (normally this file would be expected to be in GIF format).
You can add variables of your choice of the form view_extension, where extension is the file extension of the file you want to display: for example, you could have view_tif, view_jpg, etc., variables.
The variables described below give the locations of directories or files that are used by HoTMetaL PRO, and specify default file extensions.
Paths are lists of directories that HoTMetaL PRO searches to find files it needs to read, or uses to store files. The value of a variable that describes a path consists of a number of directory names, or paths, separated by semi-colons `;'. As well as giving specific directory names, it is possible to specify HoTMetaL PRO's working directory by putting a period, `.', in the path.
Note: The working directory is set with the `Properties...' command in the Microsoft Windows `File' menu.When giving a directory name (other than the working directory), you need to give the full DOS path. This may be fully or partly represented by a reference to another configuration or environment variable, as explained earlier in this chapter.
The following example shows how to set a path variable,
in this case, export_path:
export_path=${SQDIR}\samples:.:c:\donald\samples
This setting is interpreted as follows:
The default value for all path variables, with the exception of templates_path, is ".".
This variable gives a default directory for storing and loading styles files in text form. When you invoke the Save Styles... or Load Styles... command in the View menu, the file selection dialog box that appears has a list labeled Directories. This list displays, by default, the directory that is named first with the ascii_styles_path variable.
This variable names the default directory for saving files. When you invoke the Save command, the default directory that appears in the Directories list box is the first directory that is listed on the export_path variable.
This variable gives a default directory for opening files. In the file selection dialog box that appears when you invoke the Open... command, the Directories list box displays, by default, the directory that is listed first with the import_path variable.
This variable describes the styles path, a list of directories where styles files are located. These are files used by HoTMetaL PRO to describe the formatting for a document when it is displayed on the screen. HoTMetaL PRO will create a styles file for a rules file the first time that rules file is used. It places the styles file in the first directory listed by the styles_path variable. On subsequent uses of the rules file, HoTMetaL PRO will look for the styles file in the directories named by the variable. If the rules file has been changed since the styles file was created, HoTMetaL PRO will ask you if you want to create a new styles file.
The format of this variable is the same as for export_path, above.
This variable gives a list of directories that HoTMetaL PRO will search through when it needs to find a supplementary dictionary file for use with the Check Spelling... command. The order in which the directories appear is significant: when looking for a supplementary dictionary file, HoTMetaL PRO searches the directories in the order in which they appear on the supp_dict_path variable. It stops looking as soon as it finds a file with the right name. The supplementary dictionary files are listed with the supp_dict variable.
This variable gives a list of directories that HoTMetaL PRO will search through when it needs to find a system dictionary file for use with the Check Spelling... command. The order in which the directories appear is significant: when looking for a dictionary file, HoTMetaL PRO searches the directories in the order in which they appear on the system_dict_path variable. It stops looking as soon as it finds a file with the right name. The choice of system dictionary depends on the spell checking language that you have chosen with the spell_checking_language variable.
This variable gives the directory for storing files that can be used as document templates with the Open Template... command.
This variable gives a list of directories that HoTMetaL PRO will search through when it needs to find a user dictionary file for use with the Check Spelling... command. The order in which the directories appear is significant: when looking for a user dictionary file, HoTMetaL PRO searches the directories in the order in which they appear on the user_dict_path variable. It stops looking as soon as it finds a file with the right name. The user dictionary file is named with the user_dict variable.
These variables give the names of specific files that HoTMetaL PRO uses.
Except as noted, when giving a file name you need to give the full DOS path. This may be fully or partly represented by a reference to another configuration or environment variable, as explained above.
This variable names a file that contains a list of commands (separated by newlines) that are available by default to the Import Through Filter... command.
This variable names the color map file, a file that associates color names with the red-green-blue values required to tell HoTMetaL PRO how to produce the colors. The value of this variable should be a file name. If an absolute path is prepended to the file name, then that file is used; if the file name has a relative path, or no path, prepended to it, then HoTMetaL PRO looks for a file relative to the SQDIR directory. The default value is ${SQDIR}\rgb.txt.
This variable gives the names of the supplementary dictionary file(s)
used with the Check Spelling...
and Check Spelling in Selection...
commands. See the documentation on these two commands for more
information on supplementary dictionaries. The variable can name up to
24 such files. The value of this variable is a list of file names
(without paths) separated by colons, e.g.:supp_dict=med.dct:law.dct:bridge.dct:birds.dct
This variable names a file that contains a list of protocols (and their associated templates) for URLs, used by the Edit URL... command. Each line in this file can contain a protocol and a template, separated by a colon. The protocol is a string of characters, e.g., `gopher'. The template consists of literal characters, intermixed with any of the strings `<name>' (representing a filename or user name), `<host>' (representing a server name or mail domain name), and `<port>' (representing a port).
For example: http://<host>/<name>
`http' is the protocol name, and `//<host>/<name>' is the template.
This variable gives the name of the user dictionary file, which is used with the Check Spelling... command. See the documentation on this command for more information on the user dictionary.
These configuration variables determine the default
file extensions that appear in the file selection dialog boxes
for different kinds of files. The file extensions appear in the
Filename text box. The file extension consists of a dot
followed by a sequence of characters (usually three). When you set a
file extension, you must include the dot in the corresponding
variable's value. E.g., dictionary_ext=.dct
This variable sets the default extension for styles files in text format. The default extension is .asf. The text box labeled File Name in the Save Styles and Load Styles dialog boxes will, by default, contain the *.asf pattern, causing the Files list in the dialog box to contain all files having that extension in the currently selected directory.
This variable sets the default extension for user dictionary files. The default extension is .dct. The text box labeled File Name in the Load Dictionary dialog box will, by default, contain the *.dct pattern, causing the Files list in the dialog box to contain all files having that extension in the currently selected directory.
This variable sets the default extension for macro dictionary files. The default extension is .mcr. The text box labeled File Name in the Load Macros dialog box will, by default, contain the *.mcr pattern, causing the Files list in the dialog box to contain all files having that extension in the currently selected directory.
This variable sets the default extension for binary styles files. When you create or open an HoTMetaL PRO file, HoTMetaL PRO will look in the styles path for a styles file that has the same name as the rules file's compiled-in system identifier, but with the file extension replaced by the styles extension. The default styles extension is .stl.
HoTMetaL PRO allows you to trace exactly how the configuration settings are used. When tracing is turned on, you will be presented with a warning box when HoTMetaL PRO reads the configuration files, or accesses any of the variables. Tracing is controlled by the SQTRACE environment variable. The possible values are ON (which is the same as true and 1), OFF (which is the same as false and 0) and FULL. The variable must be set before starting up HoTMetaL PRO.
If SQTRACE has the value ON, you are notified whenever any of the following things happen:
If SQTRACE has the value OFF, or is not set, tracing will not be invoked.