Documentation for the AscToRTF conversion utility

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


Prev | Next | Contents


6 Using Document Policy files

This chapter has been largely superceded by the Policy manual

Document policy files are ordinary text files that list the "policies" that AscToRTF should implement when converting your document. The file can have added comment lines (starting with a "!" or "#" character) and headings for clarity.

A summary of the recognised policy lines is given in the Policy manual.

In most cases recognised policy lines are identical to those listed in the generated policy file (see 4.1). This is usually a good place to start when making your own policy.

Only those lines that are recognised policies will be acted upon.

To use a policy file, simply list it on the command line after the name of the file being converted (see 4.2.2.1).

Document policies have two main uses :

  1. To correct any failure of analysis that AscToRTF makes. Hopefully this won't be needed too much as the core analysis engine improves.

Examples include page width, whether or not underlined section headings are expected etc.

  1. To tell the program how to produce better RTF in ways that couldn't possibly be inferred from the original text.

Examples include adding titles to the page and getting a contents list created.

The document sections in this chapter that described the policies in detail have been moved to a standalone document called the "Policy manual". That document describes the scope, effect, location and default values for all policies recognised by the program.


6.1 An example conversion

The RTF version of this document has itself been converted using AscToRTF. The files used were

This policy file "includes" the link dictionary A2RLINKS.DAT.

These files are included in the distribution kit as an example set of documentation.

You can, of course, use AscToRTF to convert this doco into whatever font etc. that you wish, although the number of "output policies" is fairly limited in the initial release.


6.2 Analysis policies

The policy descriptions previously in this section have been moved to the Policy manual

6.2.1 Overview ("look for") policies

The following analysis policies help give you an overview of what the program is looking for, and to enable/disable what is being looked for.

"Attempt TABLE generation"
"Look for MAIL and USENET headers"
"Look for bullets"
"Look for hanging paragraphs"
"Look for horizontal rulers"
"Minimum ruler length"
"Look for indentation"
"Look for preformatted text"
"Look for quoted text"
"Look for short lines"
"Look for white space"
"Search for definitions"


6.2.2 General Layout policies

The following analysis policies help control general layout parameters:-

"Search for Definitions"
"Definition Char"
"Treat each line as a paragraph"
"Expect blank lines between paras"
"Hanging paragraph position(s)"
"Expect code samples"
"Indent position(s)"
"Keep it simple"
"Min chapter size"
"New Paragraph Offset"
"Page width"
"Short line length"
"TAB size"
"Text Justification"


6.2.3 Bullet policies

AscToRTF has the following bullet point policies that will normally be correctly calculated on the analysis pass :-

"Bullet char"
"Expect alphabetic bullets"
"Expect numbered bullets"
"Expect roman numeral bullets"

"Recognise '-' as a bullet"
"Recognise 'o' as a bullet"

AscToRTF tries hard not to get confused by the "1", "a" and "I" that happen to end up at the start of lines by random. These could get mistaken for bullet points.


6.2.4 Headings

AscToRTF has the following section heading policies that will normally be correctly calculated on the analysis pass :-

"First Section Number"
"Expect Numbered Headings"
"Expect Underlined Headings"
"Expect Capitalised Headings"
"Expect Second Word Headings"
"Smallest possible section number"
"Largest possible section number"

"Preserve underlining of headings"

Section headers are far and away the most complex things the analysis pass has to detect, and the most likely area for errors to occur.

AscToRTF will also document to a policy file the headings it finds. This is still to be finalised, but currently has the format

      We have 4 recognised headings
          Heading level 0 = "" N at indent 0
          Heading level 1 = "" N.N at indent 0
          Contents level 0 = "" N at indent 0
          Contents level 1 = "" N.N at indent 2

AscToRTF will read in such lines from a policy text file, but does not yet fully supported editing these via the Windows interface.

The syntax is explained below, but this will probably change in future releases. You can edit these lines in your policy file, and through the policy options in Windows.

The lines are currently structured as follows

Line component
Value
xxxx

Either "Heading" or "Contents" according
to the part of the policy being described
Level n

Level number, starting at 0 for chapters
1 for level 1 headings etc.
"Some_word"


Any text that may be expected to occur before
the heading number. E.g. "Chapter" or "Section"
or "[". The case is unimportant.
N.Nx


The style of the heading number. This will
ultimately (in later versions) be read
as a series of number/separator pairs.





The proposed format is
"N" = number
"i" / "I" = lower/upper case roman numeral
with an 'x' at the end signalling that trailing
letters may be expected (e.g. 5.6a, 5.6b)
at indent n


The indentation that this heading is expected
at. This is important in helping to eliminate
false candidates.

6.2.5 Pre-formatted text

AscToRTF has the following section heading policies that will normally be correctly calculated on the analysis pass :-

"Minimum automatic <PRE> size"

And for tables :-

"Attempt TABLE generation"
"Expect sparse tables"
"Minimum TABLE column separation"


6.2.6 Contents List policies

There is only one analysis contents policy:-

"Expect contents list"

This is described together with all the output contents list policies in 6.3.4. For more information on content list generation see 5.6.2.


6.3 Output policies

The policy descriptions previously in this section have been moved to the Policy manual


6.3.1 Added RTF details

AscToRTF has the following policies that will only ever take effect if supplied in a user policy file :-

Document properties

"Document title"
"Document keywords"
"Document description"
"Use first heading as title"
"Use first line as title"

"Language (for proofing)"

Paper sizing

"Use Landscape mode"

"Top margin (in cm)"
"Bottom margin (in cm)"
"Left margin (in cm)"
"Right margin (in cm)"

Font sizing

"Font stretch factor (in percent)"

These "polices" allow you to start "adding value" to the RTF generated. That is, they allow to specify things that cannot be inferred from the original text.


6.3.2 Hyperlinks

AscToRTF has the following hyperlink policies set as defaults :-

"Create hyperlinks"
"Create mailto links"
"Create NEWS links"
"Cross-refs at level"
"Only use known groups"
"Recognised USENET groups"

Hyperlinks can also be added by using a link dictionary (see 4.3.2.2 and 4.4.2).


6.3.3 File generation

AscToRTF has the following "output" policies that will only ever take effect if supplied in a user policy file or set manually :-

"Error reporting level"
"Generate diagnostics files"

"Input directory"
"Output directory"
"Output policy file"
"Output policy filename"


6.3.4 Contents

AscToRTF has the following policies that influence the detection and generation of contents lists :-

"Add contents list"
"Expect Contents List"

See also the discussion in 5.6.2


6.3.5 Preprocessor policies

AscToRTF has the following policies that can be used to influence the preprocessor (see Using the preprocessor), and hence the RTF output :-

"Include document section(s)"
"Use Preprocessor"


6.3.6 Text Styling

AscToRTF has the following "styling" that can be used to influence the output :-

"Allow automatic centring"
"Automatic centring tolerance"

"Allow definitions inside PRE"
"Highlight Definition Text"

"Ignore multiple blank lines"
"Search for emphasis"


6.3.7 Table Generation

AscToRTF has the following policies that can be used to influence whether or not AscToRTF will attempt to detect and generate tables, and the attributes of any tables generated.

Tables may be tailored individually by adding pre-processor commands to your source text (see 7.4)

"Attempt TABLE generation"
"Convert TABLE X-refs to links"
"Default TABLE header rows"
"Default TABLE header cols"
"Default TABLE cell alignment"


6.3.8 Link Dictionary

Link definitions appear as follows :-

[Link Dictionary]
Link definition : "a2rdoco.txt" = "Source text" + "http://www.jafsoft.com/doco/a2rdoco.txt"

That is, the text to be matched, the text to be used in its placed as the highlighted text, and the URL this link is to point to (in this case a relative URL).

See the discussions in 4.3.2.2 and 4.4.2.


6.4 Saving and loading policy files

This section has been copied into the Policy manual section on placing policies in a file

6.4.1 Overview

AscToRTF 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 first ":" character), as this needs to be matched exactly by AscToRTF (including any strange spellings :-).

For best results, it is advisable to put in your policy file only those policies you want to fix. This leaves AscToRTF 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.

6.4.2 Generating 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 6.4.2.1 and 6.4.2.2).

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.

6.4.2.1 Partial policy files

Partial policy files are files which have values for some, not all, policies.

These are recommended, because the unstated policies can be set by AscToRTF, 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 AscToRTF. Normally it is best to omit this policy, and allow AscToRTF to work it out itself.

When you save a policy file from inside AscToRTF, a partial policy file will contain

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


6.4.3 Naming policy files

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.




Prev | Next | Contents


Valid HTML 4.0! Converted from a single text file by AscToHTM
© 1997-2000 JafSoft Limited
Converted by AscToHTM