>25 3 : Ways of specifying policy values  A 
F

The "Policy Manual" for the JafSoft text conversion utilities

DThis documentation can be downloaded as part of the Ldocumentation set in .zip format



\ Previous page $F Back to Contents List#X Next page 


 +

3 Ways of specifying policy values

L

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


 0

3.1 Placing policies in a "policy file"

R

One of the more useful ways to use policies is to save them to a "policy file",Gwhich you can then later reload. In this way your customizations for aDparticular document or type of document can be saved and reused.


 .

3.1.1 Saving and loading policy files

H

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.

D

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 easier6that using all the dialogs in the Windows version.

F

When editing policies, it is important not to change the key phraseG(the bit before the ":" character), as this needs to be matched exactlyby the program.

D

For best results, it is advisable to put in your policy file onlyEthose policies you want to fix. This leaves the program to calculateFdocument-by-document policies that suit the files being converted.

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

3.1.2 policy files for your document

H

The normal way to create a policy file is by setting options and themEsaving them using the "save policy file" dialog. This will offer youBthe choice of creating a partial policy file or a full policy fileT(see 3.1.3 and 3.1.4).

z

Alternatively, you can set the Output policy file policy orJthe /POLICY=<file> command line qualifier which will generate a fullFpolicy file resulting from the analysis of the converted document.

E

Once a file is generated you can either edit it in a text editor -Gdeleting policies that are of little interest to you, and editing thoseEthat are - or reload them into the program, change them and save them again.


 #

3.1.3 Partial policy files

P

Partial policy files are files which have values for some, not all, policies.KTypically only those policies that have been changed will be saved into the file.

E

These are recommended, because the unstated policies can be set byFthe program, allowing it to adapt to the details of the document beingconcerned.

W

For example, you should only set the indentation policy if you knowGwhat indents you are using, or if you want to override those calculatedCby the program. Normally it is best to omit this policy, and allow&the program to work it out itself.

M

When you save a policy file from inside the program, a partial policy filewill contain




3.1.4 Full policy files

C

A "full" policy file contains a value for every possible policy.ASuch files are usually only useful for documentation and analysisDreasons, and should almost never be expected to be reloaded as inputHinto a conversion, as this would totally fix the conversion details.


 "

3.1.5 Naming policy files

F

Whenever the "Output policy file" policy is set (see 6.3.3.11), the2generated "full" policy file is usually called



<filename>.pol

K

where <filename> is the name of the file being created. When this?happens any existing file of that name will be overwritten.

X

For this reason we strongly advise you adopt a naming convention of the form

9

in_<filename>.pol or i<filename>.pol

H

or place your input policies in a different directory and ensure theyare backed up.


 5

3.2 Changing policies via the user interface

i

In the Windows version of the program many (but not all - see 3.6) policies<can have their values changed via options available from theO"Conversion Options" menu. This menu divides policies into "analysis"Tand "output" policies, and further sub-divides the policies into related groups.


 <

3.3 Changing policies by using command line options

R

A small number of policies can be set from the command line. These include

/, * /    W    W    e   " Q   ! i   W   U   # _    U    Q  
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
/SILENT
Display messages
/SIMPLE
Keep it simple
6

 ?

3.4 Changing policies by using preprocessor directives

R

A number of policies have equivalent preprocessor directives. These directivesKare special keywords and values placed in your source text at some point toHinfluence the conversion at that point, or from that point onwards. See,the main documentation for full details.

N

Directives all begin with the text "$_$_" followed by the keyword placed atMthe 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.

K

In addition to individual directives, the CHANGE_POLICY directive can beHused to embed policy changes into your document to apply from that pointIonwards. The effect of attempting to the change the same policy multipleFtimes via repeated CHANGE_POLICY directives will depend on whether thenpolicy is "dynamic" or "Fixed" (see Policy Scope). This can beEa useful alternative to using policy files, as it places the relevant"policies into the file itself.

F

Here is a list of the more general policy-related directives :-

/, 2 .    W   $ [   , ]   " s        W   % [    ]    W    k    ]    Q 
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
HTML fragments file
DESCRIPTION
Document Description
KEYWORDS
Document keywords
SECTION
Include document section(s)
STYLE_SHEET
Document Style Sheet
TITLE
Document Title
6




JA special case are table directives. Table directives if added to the topJof the file will apply to all subsequent detected tables. However, if youJwant to control an individual table, place $_$_BEGIN_TABLE...$_$_END_TABLEMcommands around the table text, and place the $_$_TABLE_xxx directive betweenJthe BEGIN_TABLE...END_TABLE directive. Usually just after the BEGIN_TABLE command.

O

This approach is often more flexible that setting the equivalent policy in aJpolicy file, as that would apply to all tables in the conversion. This isOwhy many of these policies have descriptions that begin "Default TABLE...".


1@
 2 .   K c   O ]   M g   W k   O _   W i   W i   U m   [ U   [ o   c o   W g   W g >  [ l{ n n M t] f : [ a] - r k s  - a Nm C N K ;[ - t
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
):

 9

3.5 Changing policies by using the Settings menu

TQ

A few policies are made available via the program's Settings Menu, rather thanrOthe Conversion Options menu. These are typically policies that control messageigeneration


 n7

3.6 Changing policies by editing a Policy file

oY

Some policies can only be changed by editing the policy file. These o are:-

f
p

Add mail headers to contents list
Q Contents style code
m Column boundaries have zero width
_U Default TABLE caption
IS Default TABLE layout
t] Default TABLE header cols
0K Display messages
Oo First line indentation (in blocks)
nk Font stretch factor (in percent)
Ha HTML version to be targeted
g Lines to ignore at end of file
k Lines to ignore at start of file
W Monitor tag generation
ow Number of words to include in filename
sQ Output log filename
>_ Scope COLOUR tags globally
l[ Suppress all font markup
es Tables could be blank line separated
k Use <CODE>..</CODE> markup
oo Use <EM> and <STRONG> markup

x
m 2

D
\ Previous page $F Back to Contents List#X Next page 


B>> 
Valid HTML 4.0!Converted from a single text file by HREF="http://www.jafsoft.com/asctohtm/">AscToHTM
K© 1997-2000 John A. Fotheringhamo
ds