Documentation for the AscToRTF conversion utility

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


Previous page Back to Contents List Next page

Running the software

Contents of this section

Overviews
Other Information
Running as a Windows application
File menu
Conversion Options menu
Selecting the Link Dictionary File
Selecting the Style Definition File
Selecting the Table Definition File
Selecting the Text Command File
Settings menu
Language menu
View menu
Help menu
Status window
Running as a command line program
Command line qualifiers: /COMMA
Command line qualifiers: /CONSOLE
Command line qualifiers: /CONTENTS
Command line qualifiers: /DEBUG
Command line qualifiers: /DOS
Command line qualifiers: /HELP
Command line qualifiers: /LIST
Command line qualifiers: /LOG
Command line qualifiers: /OUTPUT
Command line qualifiers: /POLICY
Command line qualifiers: /SILENT
Command line qualifiers: /SIMPLE
Command line qualifiers: /TABBED
Command line qualifiers: /TABLE
Running from the 'SendTo' menu

Overviews

Other Information

Running as a Windows application

AscToRTF can be invoked as a normal Windows application. On start-up you will be presented with the main window. This consists of a menu bar across the top of the window, and some data entry fields in the main body of the window.

Menu Bar

  File menu File options
  Conversion Options menu Options that affect the conversion
  Settings menu Edit the program's settings
  Language menu Select the language you'd like the program's user
    interface to be in
  View menu View the created RTF files or the messages for the
    last conversion
  Help menu Various help files and on-line resources


Data entry fields

The data entry fields show

Normally you need simply select the input file(s) using the Browse button, and the rest of the fields will be set to default values.

If you want to use wildcards, type the file specification in the data entry box directly.

Once you have selected your files, press the Convert button. The Status Window will briefly appear whilst the conversion proceeds.


Policy files

AscToRTF has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the RTF it generates. Policy files are described more fully in Using policy files.

Options on this screen include :-

More options are available under the Conversion Options menu.


Search sub-folders

New in version 2.0

When this option is selected, the software will convert any files that match the supplied filename in either the directory specified or any of its sub-folders.

Conversion type

New in version 2.0

The Conversion Type specified how the input file should be regarded during the conversion. The options available include

plain text

 
The input file is a plain text file, and the
software should analyse it to determine how
it is structures
text table


 
The input file is a plain text file which
contains a single table. The program will treat
the whole file as a table, and use analysis to
calculate the table layout
comma-delimited table


 
The input file is a comma-delimited data file
(usually a .csv file). Each line in the file
will be treated as a row in the table, and commas
are used to separate the data for each column.
tab-delimited table
 
As above, but the TAB character is used as a
delimiter
other-delimited table
 
As above, but you need to specify the delimiter in
the field that appears when this option is selected.

In the delimited table types the delimiter character shouldn't appear in the data value itself. This usually means that tab-delimited files work better. In a comma-delimited file, any value that contains a comma must be placed in double quotes. Any double quotes in a quoted value should be doubled up inside the quote.

So the value

"Enter," she said

would need to be written as

"""Enter,"" she said"

in the data file.


File menu

The file menu offers the following options:-

  Convert This will prompt you for a file to convert and will then convert the selected file(s).
  Load policy file Load policies from a policy file
  Save policy file Save the current set of policies to a policy file
  Exit Exit the program.

Conversion Options menu

This menu allows you access to the conversion options - also known as policies - that give you a large amount of control over the conversion process. These policies can be saved to a policy file (with a .pol extension by default) for re-use in later conversions. Policies are explained more in Using policy files

The menu options include:-

  Analysis policies Edit those policies that affect the analysis of your
    source document
  Output policies Edit those policies that affect the type of RTF
    generated.
  Configuration File locations Specify the locations of various configuration files
  Load policy file Load policies from a policy file
  Reload policies from file Allows you to re-load the policy file, or to load
    a different file.
  Re-analysing the input file Re-analyse the input file to re-calculate the analysis
    policies
  Resetting policies to default values Reset policies to default values.

Analysis policies menu

The Analysis Policies menu allows you to change those policies that affect the analysis of the source document.

These are discussed fully in the Analysis Policies section of this document.

Output policies menu

The Output Policies menu allows you to change those policies that affect the output of the conversion process.

These are discussed fully in the Output Policies section of this document.

Config File locations menu

The Config File Location menu allows you to specify the location of various additional configuration files. The locations you select will be stored in your policy file, so in a sense these files act as extensions of the policy file, but by being stored in separate files the same configuration files can be shared by multiple policy files.

The options on this menu allow you to select do locate following :-

Selecting the Link Dictionary File

This option allows you to select the Link Dictionary. When selected it takes you to the Link Dictionary dialogue where you can select the Link Dictionary file you want, and also view and edit its contents (although this could also be done directly using a text editor)

If a file has been selected you can press the Edit button to bring up a dialog where you can edit the selected link dictionary although you may find this easier to do using a text editor.

See Using link dictionary files

Selecting the Style Definition File

This option allows you to select the Style Definition File you wish to use. This defines the "styles" that will be available for use in the FO (font) preprocessor tag.

It also allows you to select the Scope for font tags

See Pre-processor command: FO

Selecting the Table Definition File

This option allows you to select the Table Definition File you wish to use.

Selecting the Text Command File

This option allows you to select the Text Command File you wish to use.


Re-analysing the input file

This option, available from the conversion options menu, allows you to reset the analysis options by analysing the current input file. This is not normally necessary, as this will be done automatically during a conversion.

Resetting policies to default values

This option will reset all policies to their default values. If a policy file has been loaded, it will be unloaded.

Load policy file

AscToRTF has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the RTF it generates. These policies can be saved in a policy file for later re-use in future conversions. This dialog screen is primarily intended to allow you to load a previously saved policy file

Policy files are described more fully in Using policy files.

Options on this screen include :-

Save Policy File

This window is displayed whenever the user wishes to save their policies to a file, usually for use in later conversions.

To save the file, simply select the policy file name, usually with a .pol extension.

This window contains a radio button with two options:

If this option is selected, then only those policies that have been loaded from an existing file and/or been edited during the current session will be saved.

This is the recommended option, as it will exclude all policies that have been set up correctly automatically.

If this option is selected, that all policies are written to file. This is a good way of documenting the policies used, but is usually too restrictive to be loaded as input into conversions of other files.

The saved file is a text file designed so that it may be manually edited and reloaded. If you do so, take care not to change the key phrases at the start of each line.

Note:
If you find that conversions that used to work "stop working" it's possibly because you're using a complete policy file

Settings menu

The program settings menu allows you to customise the way AscToRTF executes each time it is invoked. This is kept separate from the use of policy files, which are used to customise the actual conversion process.

This menu has the following options :-

  Documentation Settings Specify the location of your documentation on your hard drive
  Diagnostic Settings Set message filters and alter the error reporting level to
    control the number and type of messages generated during
    conversions
  Drag and Drop Settings Set the program's properties when invoked by dragging files
    into the icon on the desktop
  Results viewers settings Specify the viewers to be used for viewing results
    files, and their method of invocation
  Use of policy file settings Specify any default policy file to be used.

Documentation settings

These options allow you to specify the location of the program's documentation on your local system. This is required for the option on the Help menu to work.

By default the documentation is placed in the same directory as the program on installation, so you should only need to change this setting should you decide to move the documentation.

Diagnostic settings

These options allow you to set the level of error reporting, or to suppress messages of various types from being displayed during conversion.

The types of messages include :-

  INFO messages Informational messages. These convey information
    telling you what was been done and why.
  WARNING messages Warning messages. These tell you that something
    you have requested has not been done, or something
    has been done which may not be correct. It's possible
    you may be able to take corrective action.
  TAG ERROR messages Tagging errors. Only occur when you use the
    preprocessor in-line tags and directives introduced
    in Version 4.0
  PROGRAM ERROR messages Program errors. The program has detected it
    has done something wrong. The conversion may still
    be successful, but there is nothing you can do about
    such messages except report them to the program's
    author at info<at>jafsoft.com
  URL messages URL detection. When a URL is found a message
    is displayed. When switched on this can be a quick way
    of listing all the URLs in a file :-)

Drag and drop settings

These options specify the behaviour of AscToRTF when invoked via drag and drop (i.e. by dropping a file icon on AscToRTF's icon).

Show the status screen

The status dialog, showing messages reporting how the conversion is going should be shown.

View results in browser once complete

The selected viewer (browser) for the results files should be invoked on the last file converted once conversion is complete

Start program after conversion

The program should be launched in Windows mode once the conversion is completed.


Results viewers settings

This identifies the viewers to be used whenever AscToRTF launches an application to view a results or documentation file. Viewers may be required for both HTML and RTF files.

You can elect to have results viewed automatically after each conversion. This will normally result in the named application being launched to view the last file converted.

For HTML, you can elect to use Dynamic Data Exchange (DDE) to have the results displayed in a currently active browser. This can be quicker and more efficient that launching a new instance of the browser each time. You should ensure your DDE browser matches the program named as the default browser so that if not already active, the program can start a fresh instance.

When DDE is used the results will vary from browser to browser. IE for example will come to the front, whereas Netscape will not, and if it is minimised you won't see the results until you maximise the browser again.

For RTF, DDE is not currently available.

Use of policy file settings

Using a default policy file

This determines which policy file, if any, is to be used by default when AscToRTF is first invoked. The actual policy file used can, of course, be changed via the policy dialogue.

The default policy file will also be used if AscToRTF is invoked via drag'n'drop. This avoids the need for creating batch files with the policy file name on the command line.

Always reload policy file during conversion

This specifies that the current policy file should be reloaded every time the conversion is done. If the file is large, and you are repeatedly converting using the same policy file, then this can slow you down. On the other hand if you are editing the policy file by hand outside the program between conversions then you will want this option enabled.

Language menu

From version 3.2 onwards it is possible to change the user interface to the language of your choice. This is a process being rolled out by a number of volunteers who are converting the menu, dialog, ToolTips, message and documentation text. At any given time you may still find English translations, especially in the messages displayed, and in the help and documentation files, but it is hoped that the efforts of these volunteers will make the program easier to use for non-English speakers.

Supported languages

At present work is under way on

Spanish Gonzalo San Martin is undertaking the Spanish translation.
Gonzalo operates a highly popular Real Madrid fan page (in
Spanish and English) which you can visit at
http://members.bigfoot.com/~G.SanMartin/
Gonzalo can be contacted at G.SanMartin<at>bigfoot.com
Italian The Italian translation is being undertaken by
Gianluigi Pizzuto who can be contacted at gibly<at>libero.it and
has a web page at http://web.tiscalinet.it/fotone
Swedish The Swedish translation is being undertaken by Dan Svarreby
who can be contacted at dan.svarreby<at>home.se.
German The German translations is being undertaken by Jörg Feierabend
who can be contacted at zeitenwanderer<at>t-online.de
French The French translation is being undertaken by Andre Martinez.
Portuguese The Portuguese translation is being undertaken by Ana Maria
G. F. de Mello who can be contacted at anagfm<at>bigfoot.com

If you would like to volunteer to help with this effort, please email translations<at>jafsoft.com or visit the web page at

http://www.jafsoft.com/products/translations.html

Language "Skins"
From version 1.1 the program supports the use of language 'skins'

Language 'Skins'

AscToRTF supports the use of "language skins", that is the ability to export, edit and re-import from text file the strings used in the program's user interface.

The "language skin" is a text file, usually with an .lng extension. This file consists of one string per line, with each line being numbered to identify the string. You can edit these strings into your own language, and then reload the modifications back into the program. If you do this, make sure you leave the numbers unchanged.

Export current language setting to file

This option allows you to export all the current language strings to an external .lng file. You may then edit this file to get the user interface strings that you want.

Load a language "skin"

If you check the "use language skin" box, then the program will load the specified file each time it runs, using the text in that file as the user interface. Changes will take effect when you press OK.

View menu

This menu contains the following options

View conversion results

Once you've converted a file, you can view the results in the browser of your choice. AscToRTF will detect the default browser used on your system. If you wish you can change this through the settings menu

You can view results in the selected browser by selecting the option on the view menu or by pressing the View results button on the main screen.

AscToRTF can also be configured to automatically review results when run from the command line or in drag'n'drop operation.


Help menu

The help menu has the following options:-

Contents Brings up the contents page of this help file. Help can be
  brought up anywhere in the program by pressing F1
RTF doco (offline) Brings up the local copy of the RTF documentation in your
  preferred browser
RTF doco (online) Brings up the Internet copy of the RTF documentation in your
  preferred browser.
Register (online) In the shareware version this will take you to the web page
  which gives registration details. You will need to be
  online for this to work
About Shows the program version and other details. Includes buttons
  to take you to the home page etc on the web.

Status window

The status window is displayed whenever a conversion is in progress. It displays messages showing how the conversion is progressing.

Usually these are just informational messages telling you of lines on which AscToRTF hasn't performed markup because they "fail policy". For example a line with a number at the beginning won't be turned into a header unless the number is in sequence, and the line is at the correct indentation level.

You should review these messages and check they don't indicate an error in conversion.

This screen can be retrieved by pressing the "Show messages window" button on the main window.


Running as a command line program

You can run AscToRTF from the command line inside a Command Line ("DOS") window. You can also run a console version, A2RCONS.

The command line has the syntax

c:> A2RCONS <files1> [<files2> ...] [<policy file>] [/qualifiers]

if running the console version, or

c:> AscToRTF <files1> [<files2> ...] [<policy file>] [/qualifiers]

if running the Windows version (although this doesn't support all qualifiers).

If you supply no <files1> on the command line, then the windows version will be launched as normal, but the console version will prompt you for filenames. The <files1> value can be any valid filespec, including wildcards. You can supply additional <files2>, <files3>... values should you wish. For example

c:> a2hcons a*.txt b*.txt c*.txt abc.pol /out=c:\temp\

will convert all the files a*.txt, b*.txt and c*.txt in the current folder using the policy file abc.pol and place all the output files in the folder c:\temp\.

If you supply one or more valid <files> value these files will be converted.

For the Windows version, depending on the Settings you've selected, the Status Window will be displayed during the conversion, the program will display once finished, and a viewer may be launched to view the results.

Note, generally we advise using the console version for command line operations

If you want to use a policy file, add this to the argument list. The policy file must have a .pol extension, and only the first policy file listed will be used.

Recognised qualifiers include

  /COMMA Input file is a comma-delimited table
  /CONSOLE Direct the output to the console stdout stream
  /CONTENTS Generate a contents list
  /DOS Generate DOS 8.3 filenames
  /HELP Generates a HELP message
  /LOG=filename Generate a log file.
  /LIST=filename Generate a list file.
  /OUTPUT=filespec Specify the output filename(s)
  /POLICY=filename Generate a .pol policy file from the analysis of the source file
  /SILENT Suppress all console messages
  /SIMPLE Treat the source file as "simple", i.e. don't look for complex constructs
  /TABBED Input file is a tab-delimited table
  /TABLE Input file is a plain text table

Qualifiers must begin with the slash (/) character but may be of mixed case and may be shortened provided they remain unique. So /H will get you help, whereas you can't use /S since that could be /SILENT or /SIMPLE

Command line qualifiers: /COMMA

New in version 2.0

Specifies that the source file is a comma-delimited table. In this case each line will become a row in a table, and each value separated by a comma will become a cell in the table.

Command line qualifiers: /CONSOLE

New in version 2.0

Specifies that the output should be direct to the output stream. This should normally be used with command line qualifiers: /SILENT to suppress all status messages.

This option could be useful if you wanted to pipe the output into some other application.

Command line qualifiers: /CONTENTS

This qualifier will cause a contents list to be generated containing links to all the headings detected ion the source document.

See the discussion on adding a contents list and the contents policies

Command line qualifiers: /DEBUG

This qualifier will cause the program to generate diagnostics files.

Command line qualifiers: /DOS

If specified the output filenames will be in the 8.3 format

Command line qualifiers: /HELP

On the console version this generates a help message detailing usage.

Command line qualifiers: /LIST

These qualifiers cause AscToRTF to generate some diagnostic files, which have extensions

  .LIS1   an analysis before policy is set
  .LIS   an analysis after policy is set

The list files can assist in understanding how AscToRTF has interpreted your file. The .stats file is neither pretty, nor easy to read, but can in extreme cases assist in diagnosing faults should you wish to report them.

If Command line qualifiers: /LIST is used, only the list files are created.

Command line qualifiers: /LOG

This qualifier will cause the status messages created by the program to be copied into a log file. This log file will include messages suppressed from the user interface.

You can specify a filename as /LOG="<name>", the default filename, if omitted, will be AscToRTF.log

Command line qualifiers: /OUTPUT

The /OUTPUT=filename qualifier specifies where the output file(s) should be placed. It can include wildcards, with the input file being used to replace any parts of the filename not specified.

Thus "/OUT=c:\temp\*.sav" will result in a file with the same name, but with a .sav extension, and in the "c:\temp\" directory folder.

If omitted, the output file will be given the same name as the input file but with a .rtf extension.

Command line qualifiers: /POLICY

This qualifier will cause the program to generate a .pol file for each file converted. This file will represent the "best guess" policy file generated by the program through analysis of your file.

WARNING:
The .pol file will have the same name as the file being converted with a .pol extension, and will overwrite any existing policy file of the same name. For this reason we recommend your input policy files should have different names (e.g.. by adding "in_" in front of the name.

Command line qualifiers: /SILENT

This qualifier suppresses all error messages from being displayed to the console. Mainly relevant in the OpenVMS and console versions of the program, rather than the Windows version.

Command line qualifiers: /SIMPLE

This qualifier indicates that you want the source file treated as a "simple" file, and that AscToRTF shouldn't look for more complex constructs such as headings etc.

This is equivalent to the Keep it simple policy

Command line qualifiers: /TABBED

New in version 2.0

Specifies that the source file is a tab-delimited table. In this case each line will become a row in a table, and each value separated by a tab will become a cell in the table.

Command line qualifiers: /TABLE

New in version 2.0

Specifies that the source file is a plain text table. In this the program will do its best to analyse the table structure, and reproduce it.

Running from the 'SendTo' menu

AscToRTF can make a useful addition to your "Send to" menu (available when you right-click on a file in explorer).

To add AscToRTF to this menu, simply add a shortcut to your /Windows/SendTo directory.

If you want to use a standard policy file (e.g. with a particular colour scheme), then create a simple .bat file with the command

AscToRTF %1 standard.pol



Previous page Back to Contents List Next page

Valid HTML 4.0! Converted from a single text file by AscToHTM
© 1997-2004 John A Fotheringham
Converted by AscToHTM