| Back to Contents List |
|
Document policies have two main uses; to correct any failure of analysis that AscToHTM makes, and to tell the program how to produce better HTML in ways that couldn't possibly be inferred from the original text.
Examples of the former may include specifying a nominal page width, and stating whether or not underlined section headings are expected etc.
Examples of the latter include adding colour and titles to the page, as well as requesting that a large document is split into several pages.
AscToHTM has a large number of options available to influence the analysis of your text files, and the output to HTML. These options are called "policies" as they govern how the source file should be interpreted and converted.
Policies may be saved in text files, known as policy files. These files have a ".pol" extension by default. The policy files are usually updated by changing the policies and saving the changes in a new file. Because they are text files you can also edit them directly, in a text editor. The files have the format of one policy per line of
Text in the form
PolicyText : <policy value>
The use of policy files allow a given set of options to be saved and reused for other conversions, or later conversions of the same file.
This section discusses the following
Each policy has a name, which also acts as a short description. This description is used in the policy files, and must be matched exactly in the policy file if the policy is to be recognised. This means that if the policy text is misspelt, then you must normally match the misspelling.
However there is an exception to this rule see British and American spellings of Colour
Although the program is developed by a British Author, as far as possible I've tried to support use of British and American English in the policy names.
So, for example, the word "colour" may usually be spelt "color" in policies such as :-
Each policy has a data value. The type of values a policy can take will vary from policy to policy.
For most policies the special value "(none)" will be accepted, meaning that this policy should be ignored and/or assigned a suitable default value.
The commonest type of data value is simple a "Yes/No" value. That is the value is either "Yes" or "no". In practice only the first letter is required.
For backwards compatibility the values "true" and "false" may also be used.
Many policy values require numeric values. Sometimes the value will be constrained, e.g. must be positive, or it must lie within a certain range. Values that lie outside the accepted range will be reported in error, and the policy will be ignored.
Many policies are simple text strings, e.g. the Title of the HTML pages being produced. In such cases the whole value will be used, but any spaces before or after the value will be ignored.
Some policies accept colour values. These values should be HTML colours which - for example - may be placed in the various attributes of the <BODY> tag.
You can enter any value acceptable to HTML. Normally a value is expressed as a 6-digit hexadecimal value in the range 000000 (black) to FFFFFF (white), but certain colours such as "white", "blue", "red" etc may also be recognised by HTML. The program simply transcribes your value into the output file.
A value of "none" signals the defaults are to be used. By default AscToHTM changes the background colour to be white (the true HTML default is a light gray whose value is "C0C0C0").
Some policies require section or heading level values. The program numbers heading levels as follows :-
Heading level Type of heading 1 Chapter headings 2 Major sections 3 sub-sections 4 sub-sub-sections
In a document with numbered sections "1" would be a chapter, "1.2" a major section, "1.2.3" a sub-section and "1.2.3.4" a sub-sub-section etc.
In documents with underlined sections the heading level is determined by the underlining character.
Chapters '*' Major sections '+','=' or'/' Sub-sections '-','_' or '~' Sub-sub-sections '.'
A few policies require a list of named values. In such cases the values are either :-
- space-separated. Each value should contain no white-space characters, but may contain underscores etc.
- Comma-separated. Each value should be separated by a comma. The values may contain white-space. If they also include a comma then place the value in double quotes.
Each policy has its own scope. Policies are scoped in two different ways:-
- Analysis or Output. Policies may apply to the analysis of the input text or the generation of the output files.
- Fixed or Dynamic. A Fixed policy may not be varied during the conversion of the file, that is it is applied equally to all parts of the file being converted. A Dynamic policy may be changed a number of times during the conversion (by embedding changes of values in the source document itself). This can be used to alter the conversion process locally in different parts of the file.
Dynamic policies can be made to have different values at different points in the document by using the CHANGE_POLICY pre-processor command.
Dynamic analysis policies are policies that affect the analysis of the file, that may be varied during the processing of the file. This is achieved by embedding new values in the file itself (see 3.4)
For example adding the line(s)
$_$_CHANGE_POLICY Look for short lines : no
...
$_$_CHANGE_POLICY Look for short lines : yes
uses the policy look for short lines to prevent the software looking for short lines for the enclosed part of the document.
Dynamic output policies are policies that affect the generation of the output file(s) that may be varied during the processing of the file. This is achieved by embedding new values in the file itself (see 3.4)
For example adding the lines
uk.railways
$_$_CHANGE_POLICY Recognised USENET groups : uk
uk.railways
$_$_CHANGE_POLICY Recognised USENET groups : (none)
to your source uses the policy Recognised USENET groups to switch on the recognition of "uk.railways" as a newsgroup for a few lines, where this is normally disabled by default.
Fixed analysis policies are policies that affect the analysis of the file, and that may not be varied during the processing of the file, usually because what they describe should apply to the whole file.
For example the indentation pattern used in the file is usually fixed in this way.
Fixed output policies are policies that affect the generation of the output file, and that may not be varied during the processing of the file, usually because they must be consistent, or because they're output near the top of the document.
For example the Active Link Colour is put in the <HEAD> portion of the HTML file, and cannot be varied throughout the file.
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 partial policy files or full policy files.
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.
These are recommended, because the it leaves AscToHTM free to adjust all the other policies not set in the file, 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
A "full" policy file contains a value for almost every possible policy.
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.
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 /POLICY[=filename] Output policy file /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 Using the pre-processor 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.
All policies can be changed by editing the policy file directly, and a few policies can only be changed in this manner, as they are not supported by the user interface (see Policies that need to be added manually).
Policy file are plain text files with one policy per line in the form
<policy_name> : <policy_value>
Comments and blank lines are permitted in the policy file, and if the file was created by AscToHTM then "[Section Names]" are shown as well. These section names are only there for your convenience, and have no effect on the parsing of the policy file. Policy lines may be placed in the file in any order, and for the most part shouldn't be repeated.
When editing a policy line, you must use the exact name as listed in the Alphabetical list of policies available in AscToHTMin order for the policy to be correctly recognised. Any policy name that doesn't match will lead to an error message being displayed in the Status Window when the policy file is loaded.
Once you have edited the policy file, you should save your changes and then re-run AscToHTM and tell it the name of the policy file to use.
Here's an example policy file
[File generation]
Split level : 1
Add navigation bar : Yes
[Style]
Document Style Sheet : manual.css
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
Alternatively, you can set the Output policy file policy which will generate a full policy file resulting from the analysis of the converted document.
Once a file is generated you can either edit them 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.
Whenever the Output policy file policy is set 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.
 |
Converted from
a single text file by
AscToHTM © 1997-2004 John A Fotheringham |  |