The "Policy Manual" for the JafSoft text conversion utilities

The most recent version of this document can always be found online


Previous page Back to Contents List Next page

3 Ways of specifying policy values

You can specify policies in a number of different ways used separately or in combination.


3.1 Placing policies in a "policy file"

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.


3.1.1 Saving and loading policy files

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.

Note:
Avoid using "full" policy file for your conversions. Such files prevent the program from adjusting to each source file, often leading to unwanted results.

3.1.2 policy files for your document

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.


3.1.3 Partial policy files

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

3.1.4 Full policy files

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.


3.1.5 Naming policy files

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.


3.2 Changing policies via the user interface

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.


3.3 Changing policies by using command line options

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


3.4 Changing policies by using preprocessor directives

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...".


Directive keyword(s) Related policies
"TABLE_ALIGN" Default TABLE alignment
"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_COLO(U)R_ROWS" Colour data rows
"TABLE_CONVERT_XREFS" Convert TABLE X-refs to links
"TABLE_EVEN_ROW_COLO(U)R" Default TABLE even row colour
"TABLE_HEADER_COLS" Default TABLE header rows
"TABLE_HEADER_ROWS" Default TABLE header cols
"TABLE_IGNORE_HEADER" Ignore table header during analysis
"TABLE_LAYOUT" Default TABLE layout
"TABLE_MAY_BE_SPARSE" Expect sparse tables
"TABLE_MIN_COLUMN_SEPARATION" Minimum TABLE column separation
"TABLE_ODD_ROW_COLO(U)R" Default TABLE odd row colour
"TABLE_WIDTH" Default TABLE width


3.5 Changing policies by using the Settings menu

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


3.6 Changing policies by editing a Policy file

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




Previous page Back to Contents List Next page

Valid HTML 4.0! Converted from a single text file by AscToHTM
© 1997-2004 John A. Fotheringham
Converted by AscToHTM