Documentation for the AscToRTF conversion utility : Getting the most from AscToRTF

Documentation for the AscToRTF conversion utility

The latest version of these files is available online at http://www.jafsoft.com/doco/docindex.html

Getting the most from AscToRTF

Contents of this section

Making your first attempt

Starting to use the console version
Starting to use the Windows version

Refining your results

Using policy files to improve the conversion
Using link dictionary files
Using multiple policy files
Use the pre-processor and in-line tags

Processing several files at once

Using wildcards
Using script files

Generating log files

Making your first attempt

Starting to use the console version

To run the console version A2RCONS simply type

c:> A2RCONS Input_file.name

at the command line. This will create a file :-

input_file.rtf

An output file which will have the same file name with a .rtf extension

The program may display a number of status messages which are largely informational, and can be ignored if the conversion worked okay. If it didn't, these messages may give a clue as to where the analysis went wrong.

Starting to use the Windows version

Enter the name of the file to be converted in the File(s) to convert text field. You can type in wildcards into this field. If you wish, use the browse button to search for the file to be converted.

Alternatively simply drop the file icon from an Explorer window onto the program.

Once you've chosen the file(s), the output filename and output directory are calculated for you from the filename. If you wish, you may change these values.

Press the Convert File(s) button. The Status Display window will appear briefly showing progress messages. You can dismiss this display (or tick the option that it does so automatically on completion). If you wish to view these messages later, you can selected the Show Messages option on the View menu.

To view the last file converted, press the View results button. This should launch your default application for the file types (.rtf) just created. This will usually be your default word processor package.

Refining your results

If all goes well the resultant RTF file will be satisfactory.

If there are problems, or if you wish to add to the created file, you can tailor the conversion by changing policies.

Note:: Unlike AscToHTM, AscToRTF has relatively few output policies, as it is expected that users will "tidy up" the created file using their preferred Word processing application.

In the Windows version, this is done by editing policies via the Conversion Options menu, which is fully described in the context-sensitive Windows Help file (press F1 at any point).

The conversions options are also known as "policies", and these can be saved to a text policy file. Policy files are just text files with one option per line. If you're careful, they can be edited by hand in a text editor. It is the format of policies in a policy file that is shown and discussed in this document.

Policy files created in the Windows version can also be used by the console version.

Using policy files to improve the conversion

If your initial results are a little strange, then review the policies calculated by the program, and create a "policy file" to tell the program how to do the conversion differently.

You can do this as follows :-

By creating a "sample" policy file

You can create a sample .pol policy file that documents the policies used. Do this either by using the command line

c:> A2RCONS Input_file.name /policy

or by ticking

"Generate a sample policy file"

on the Conversion Options->File Generation tabbed dialogue

When this is done then the next time you convert the file, in addition to the .rtf file generated, you will now have an output policy file "input_file.POL" which describes the document policy file calculated by AscToRTF and used by it during the conversion.

This file will contain one line each for all the program policies, most of which should be correct.

Review the contents of this file, deleting all lines that look correct, and editing all lines that appear to be wrong. You want to delete "correct" lines, because that leaves the program free to re-calculate these options on a file-by-file basis. If you leave the "correct" value in the file, you fix the option, which may not be "correct" for later files that you choose to convert.

Save the modified .POL file which should only contain lines for those policies you think are wrong or want to override.

You'll may need to review the Policy manual in order to understand the policies to do this fully.

By re-analysing the file

Under Windows a slightly easier option is to select Conversion Options -> Re-analyse the file. This will analyse the file and change all the policy values currently on display to be the values calculated by the program. You can then review and change these values using the tabbed dialogues.

Once you're happy with your changes, select "Save policies to file" from the menu, saving only the changed policies. You can review this file in a normal text editor.

Once you've produced your new input policy file, re-run the conversion using the new policy file. The program will now override aspects of the calculated document policy with the input policy you've supplied.

Each document policy file consists of a number of lines of data. Each line has the form

        Keywords     :    Data value(s)

For clarity a number of section headers are added like this :

        [Analysis]

Such headings are ignored, as are any lines whose keywords are not recognised or not yet supported. The order of policies in the file, and their location within "sections" is totally unimportant.

The order of policies within the file is usually unimportant, and the placement relative to the "headings" is ignored. The Headings are simply there to make the file easier to read in a text editor.

A sample fragment from a calculate policy file looks like this

        [Hyperlinks]
        ------------
        Create hyperlinks:        Yes
        Create mailto links:      Yes
        Create NEWS links:        Yes

These are all default values used by AscToRTF. If, for example you want to add a title to your page and prevent email addresses being turned into hyperlinks, simply create a policy file containing the lines

        [Hyperlinks]
        ------------
        Create mailto links:      No

(Remember the insertion of section headings is optional, as is the ordering of policies within the file).

By refining the input policy file, you can greatly influence the output that AscToRTF generates

Using link dictionary files

NOTE: This feature is a legacy from AscToHTM. The generation of hyperlinks in RTF documents - though possible - is less likely to be of interest.

In addition to adding hyperlinks for all URLs, email addresses, section references and contents list entries, AscToRTF allows users to specify key phrases that should be turned into hyperlinks.

This is achieved by adding lines to the input policy of the form

        [Link Dictionary]
        -----------------
        Link definition    :   "[Google]" = "Google search engine" + "www.google.com"

The syntax used here is

        Link definition    :   "match phrase" = "replacement phrase" + "link"

In this case the string "[google]" is replaced by a link to a web page "www.google.com" with the text "Google search engine" being highlighted.

NOTE:: Unlike AscToHTM, only external hyperlinks are accepted. Relative links will be ignored since they won't work from inside an RTF document.

Using multiple policy files

If you wish to use AscToRTF to support several text files e.g. for a set of Intranet documentation, it may be useful to share some common document policies, e.g. colour, headers and footers and particularly the link dictionary.

To support this AscToRTF allows two special types of line in the policy file.

Include files

        include file      :   Link_Dictionary.dat

If a line of this type is encountered, the contents of the file Link_dictionary.dat are included in the current policy file. This is the best way of sharing data across many converted files.

"daisy-chain" files

        switch to file    :   Other_policy_file.dat

If a line of this type is encountered, the processing of the current file terminates, and continues in the named file.

This is a way of "daisy-chaining" policy files together which may be useful if you wish to group files together at different levels.

Use the pre-processor and in-line tags

AscToRTF has a built-in pre-processor. This allows you to add special codes to your source file that tell the program what you'd like it to do.

Examples include delimiting tables, or adding a timestamp to the file being converted. Again, much of this functionality was developed for AscToHTM and may be less useful for RTF generation.

See Using the pre-processor and pre-processor in-line tags for more details.

Processing several files at once

The program is capable of processing more than one file in a single run. There are a number of ways in which you can tell the program which files you want.

You can use wildcards to specify the filenames The wildcard will be expanded to a set of filenames, and each file will be processed in turn.

(From the command line only) You can use a script file That is you can pass the name of a file which lists the files you want converted.

(From the command line only) You can pass in multiple file specifications, each of which can be a wildcard. For details see running as a command line program

Using wildcards

You can convert multiple files at one time by specifying a wildcard describing the files to be converted. The wildcard has to be meaningful to the operating system you are using, and will be expanded in alphabetical order. Under Windows this ordering may be case-sensitive.

At present we recommend that wildcards are only used on the contents of a single directory. Indeed wildcards spanning directories are probably not supported (let's just say it's untested :-)

Note, the same policies will apply to all files being converted. If you wish different policies to apply, use a script (see 4.3.3.2)

Note:: In the shareware version, wildcard conversions are limited to only 5 files

Using script files

From the command line you can convert several files at the same time in the order and manner of your choosing. To do this use the command

c:> A2RCONS @List.file [rest of command line]

Where the file "list.file" is a steering file which contains a list of AscToRTF command, and the "@" in front indicates it is a list file, rather than a file to be converted.

An example list file might look like

        ! this is the main document
        DOCO.TXT        IN_DOCO.POL
        #
        # These are the other chapters
        CHAPTER2.TXT
        CHAPTER3.TXT    /SIMPLE

Note the use of "!" or "#" at the start of a line signifies it's a comment line to be ignored.

Any qualifiers used on the original A2RCONS line will be used as defaults for each conversion, but will be overridden by any listed in the list file. In this way it would be possible to specify a default policy file for a bunch of similar conversions.

Note:: In the shareware version, batch conversions are limited to only 5 files

Generating log files

If you want a log of what has been done, you can create a log file. This can be done in a number of ways :-

From the command line

On the command line you can use to launch the program, add the /LOG=<filespec> qualifier (see command line qualifiers: /LOG).

From the policy file

Use the Generate diagnostics files policy. You will need to manually edit this into your .pol file, as it can't be set via the user interface.

From the Status Dialog

In the Windows version, the Status Dialog now contains a "Save to file" option to save the displayed messages.

Back to Contents List