Making your first attempt

Starting to use the console version

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.

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.

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.

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 :-