You can specify policies in a number of different ways used separately or in combination.
One of the more useful ways to use policies is to save them to a "policy file", which you can then later reload. In this way your customisations for a particular document or type of document can be saved and reused.
AscToHTM allows you to save policies to file so that you can later reload them. This allows you to easily define different ways of doing conversions, either for different types of files, or to produce different types of output.
The policy files have a .pol extension by default, and are simple text files, with one policy on each line. You can, if you wish, edit these policies in a text editor... this is sometimes easier that using all the dialogs in the Windows version.
When editing policies, it is important not to change the key phrase (the bit before the ":" character), as this needs to be matched exactly by AscToHTM.
For best results, it is advisable to put in your policy file only those policies you want to fix. This leaves AscToHTM to calculate document-by-document policies that suit the files being converted.
The normal way to create a policy file is by setting options and them saving them using the "save policy file" dialog. This will offer you the choice of creating a partial policy file or a full policy file (see 3.1.3 and 3.1.4).
Alternatively, you can set the "Output policy file" policy or the /POLICY=<file> command line qualifier which will generate a full policy file resulting from the analysis of the converted document.
Once a file is generated you can either edit it in a text editor - deleting policies that are of little interest to you, and editing those that are - or reload them into the program, change them and save them again.
Partial policy files are files which have values for some, not all, policies. Typically only those policies that have been changed will be saved into the file.
These are recommended, because the unstated policies can be set by AscToHTM, allowing it to adapt to the details of the document being concerned.
For example, you should only set the indentation policy if you know what indents you are using, or if you want to override those calculated by AscToHTM. Normally it is best to omit this policy, and allow AscToHTM to work it out itself.
When you save a policy file from inside AscToHTM, a partial policy file
will contain
- all policies loaded from the current policy file (if any)
- all policies changed in AscToHTM during the current session (if any)
A "full" policy file contains a value for every possible policy. Such files are usually only useful for documentation and analysis reasons, and should almost never be expected to be reloaded as input into a conversion, as this would totally fix the conversion details.
Whenever the "Output policy file" policy is set (see 6.3.3.11), the
generated "full" policy file is usually called
<filename>.pol
where <filename> is the name of the file being created. When this happens any existing file of that name will be overwritten.
For this reason we strongly advise you adopt a naming convention of the form
in_<filename>.pol or i<filename>.pol
or place your input policies in a different directory and ensure they are backed up.
In the Windows version of the program many (but not all) policies can have their values changed via options available from the "Conversion Options" menu. This menu divides policies into "analysis" and "output" policies, and further sub-divides the policies into related groups.
A small number of policies can be set from the command line. These include
Command line |
Equivalent policy |
---|---|
/CONTENTS |
Add contents list |
/DOS |
Use DOS filenames |
/INDEX[=filename] |
Make Directory |
/LOG[=filename] |
Create a log file |
/LIST[=filename] |
Generate diagnostics files |
/POLICY[=filename] |
Output policy file |
/RULESET="name" |
Rule set to be used |
/SIMPLE |
Keep it simple |
A number of policies have equivalent preprocessor directives. These directives are special keywords and values placed in your source text at some point to influence the conversion at that point, or from that point onwards. See the main documentation for full details.
Directives all begin with the text "$_$_" followed by the keyword placed at the start of a line. The directive appears on a line by itself, and the rest of the line is interpreted as the directive's data value.
In addition to individual directives, the CHANGE_POLICY directive can be
used to embed policy changes into your document to apply from that point
onwards. The effect of attempting to the change the same policy multiple
times via repeated CHANGE_POLICY directives will depend on whether the
policy is "dynamic" or "static" (see "Policy Scope"). This can be
a useful alternative to using policy files, as it places the relevant
policies into the file itself.
Here is a list of the more general policy-related directives :-
Directive keyword(s) |
Related policies |
---|---|
BEGIN_CODE,END_CODE |
Expect code samples |
BEGIN_CONTENTS,END_CONTENTS |
Expect Contents List |
BEGIN_PRE,END_PRE |
Minimum automatic <PRE> size |
CHANGE_POLICY |
(any policy) |
CONTENTS_LIST |
Add contents list |
DESCRIPTION |
Document Description |
KEYWORDS |
Document keywords |
STYLE_SHEET |
Document Style Sheet |
TITLE |
Document Title |
A special case are table directives. Table directives if added to the top
of the file will apply to all subsequent detected tables. However, if you
want to control an individual table, place $_$_BEGIN_TABLE...$_$_END_TABLE
commands around the table text, and place the $_$_TABLE_xxx directive between
the BEGIN_TABLE...END_TABLE directive. Usually just after the BEGIN_TABLE
command.
This approach is often more flexible that setting the equivalent policy in a policy file, as that would apply to all tables in the conversion. This is why many of these policies have descriptions that begin "Default TABLE...".
Directive keyword(s) |
Related policies |
---|---|
TABLE_BGCOLOR |
Default TABLE colour |
TABLE_BORDER |
Default TABLE border size |
TABLE_BORDERCOLOR |
Default TABLE border colour |
TABLE_CAPTION |
Default TABLE caption |
TABLE_CELLPADDING |
Default TABLE cell padding |
TABLE_CELLSPACING |
Default TABLE cell spacing |
TABLE_CELL_ALIGN |
Default TABLE cell alignment |
TABLE_COLOUR_ROWS |
Colour data rows |
TABLE_CONVERT_XREFS |
Convert TABLE X-refs to links |
TABLE_EVEN_ROW_COLOUR |
Default TABLE even row colour |
TABLE_HEADER_COLS |
Default TABLE header rows |
TABLE_HEADER_ROWS |
Default TABLE header cols |
TABLE_MAY_BE_SPARSE |
Expect sparse tables |
TABLE_MIN_COLUMN_SEPARATION |
Minimum TABLE column separation |
TABLE_ODD_ROW_COLOUR |
Default TABLE odd row colour |
TABLE_WIDTH |
Default TABLE width |
A few policies are made available via the program's Settings Menu, rather than the Conversion Options menu. These are typically policies that control message generation
Converted from a single text file by AscToHTM © 1997-99 John A. Fotheringham | ![]() |