Documentation for the AscToRTF conversion utility
The latest version of these files is available online at http://www.jafsoft.com/doco/docindex.html
Contents of this section
Making your first attempt
Starting to use the console versionRefining your results
Starting to use the Windows version
Using policy files to improve the conversionProcessing several files at once
Using link dictionary files
Using multiple policy files
Use the pre-processor and in-line tags
Using wildcardsGenerating log files
Using script files
To run the console version A2RCONS simply type
c:> A2RCONS Input_file.name
at the command line. This will create a file :-
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.
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.
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.
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.
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 :-
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.
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 :
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
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.
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
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.
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.
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.
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
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 220.127.116.11)
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.
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 :-
On the command line you can use to launch the program, add the /LOG=<filespec> qualifier (see command line qualifiers: /LOG).
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.
In the Windows version, the Status Dialog now contains a "Save to file" option to save the displayed messages.
a single text file by
© 1997-2004 John A Fotheringham