| Back to Contents List |
|
The most recent version of this document can always be found online
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 customizations for a particular document or type of document can be saved and reused.
The program 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 the program.
For best results, it is advisable to put in your policy file only those policies you want to fix. This leaves the program 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 the program, 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 the program. Normally it is best to omit this policy, and allow the program to work it out itself.
When you save a policy file from inside the program, a partial policy file will contain
- all policies loaded from the current policy file (if any)
- all policies changed in the program 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 - see 3.6) 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 |
| /FRAMES | Place document in frames |
| /INDEX[=filename] | Make Directory |
| /LIST[=filename] | Generate diagnostics files |
| /LOG[=filename] | Create a log file |
| /OUT=[filespec] | Output directory |
| /POLICY[=filename] | Output policy file |
| /RULESET="name" | Rule set to be used |
| /SILENT | Display messages |
| /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 "Fixed" (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 BASEHREF Document Base URL 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 DEFINE_HTML_FRAGMENT Fragments file DESCRIPTION Document Description KEYWORDS Document keywords SECTION Include document section(s) 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...".
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
Some policies can only be changed by editing the policy file. These are:-
Add mail headers to contents list
Contents style code
Column boundaries have zero width
Default TABLE caption
Default TABLE layout
Default TABLE header cols
Display messages
First line indentation (in blocks)
Font stretch factor (in percent)
HTML version to be targeted
Lines to ignore at end of file
Lines to ignore at start of file
Monitor tag generation
Number of words to include in filename
Output log filename
Could be blank line separated
Use <CODE>..</CODE> markup
Use <EM> and <STRONG> markup
 |
Converted from a single text file by AscToHTM © 1997-2004 John A. Fotheringham |  |