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

Change History

Contents of this section

Version 2.0 (February 2004)
New features
Support for generating RTF as WinHelp source files
New ability to define table layouts and formatting rules
Ability to "tag" your own tables for greater accuracy
Input text manipulation and labelling using "Text commands"
Control over document styling by using a "Style Definition File"
Support for non-ASCII character types and character encodings
Support for comma-delimited and tab-delimited tables
New policies
New Font policies
New Heading policies
New Hyperlink policies
New file, page, paragraph and line structure policies
New Table policies
Other new policies
New programs
API version now available
New utility A2HDETAG
Other changes
New Preprocessor tags
Other new options
New document, the "Table Manual"
Changes to the Windows version
Changes to the command line version
Changes to document analysis
Changes to documentation
Version 1.5 (October 2002)
Version 1.00 (March 2000)

Version 2.0 (February 2004)

A major update since version 1, version 2 is essentially version 1.5, but fully documented. The changes listed here were mostly available in version 1.5. Some were obvious, others were not.

New features

Support for generating RTF as WinHelp source files

AscToRTF can now create RTF files suitable for conversion into WinHelp help files. Although this type of help file has been superceded by HTML help, many people still prefer this type of Help file.

The Help files are created from specially formatted RTF files using the free Help Compiler Workshop (HCW) utility, available from Microsoft.

To support this the following new policies have been added

See also the section Creating WinHelp files


New ability to define table layouts and formatting rules

To aid in processing tables, the program now allows you to identify various table structures by specifying various match conditions. Each time the software encounters a candidate table, it tests this against the match conditions to see if the "table" is of a known type.

For each table you can specify its structure, and various formatting rules to be used in its conversion. These structure and formatting definitions can be shared between multiple table types for your convenience.

All the table type, structures and formatting rules should be placed in an external text file, known as a Table Definition File (or TDF for short). A new policy allows you to identify which Table Definition File is to be used, and you can select this from the new Config File Location menu.

For full details see Using Table Definition Files (TDF).

NOTE
This feature was originally added to AscToHTM, and at present most of the formatting rules apply more to HTML generation, and so aren't available in the RTF generation of AscToRTF.


Ability to "tag" your own tables for greater accuracy

The program now supports Tagged Table commands. These commands allow you to completely markup a table, specifying the column details, the row details and the contents of each table cell.

This approach can be used by those who want complete control over how their tables are constructed, or who are generating text files from a source which knows the table layout and can explicitly state it.

By using the tagged approach, you avoid the prospect of the program making mistakes when analysing the layout of the table.

As an example of using tagged table commands, the following sequence in the source file

        $_$_BEGIN_USER_TABLE C,1 in
        $_$_COLUMN_DETAILS 1,,,L, 2 in
        $_$_COLUMN_DETAILS 2,,,C, 1 ins
        $_$_TABLE_BORDER 1

        $_$_NEW_ROW HEAD
        $_$_NEW_CELL
        Substance (units)
        $_$_NEW_CELL
        Year
        Sampled

        $_$_NEW_ROW DATA
        $_$_NEW_CELL
        Alpha emitters (pCi/L)
        $_$_NEW_CELL
        1999

        $_$_NEW_ROW DATA
        $_$_NEW_CELL
        Asbestos (MFL)
        $_$_NEW_CELL
        1993
        $_$_END_TABLE

becomes

Substance (units)
Year
Sampled
Alpha emitters (pCi/L)
1999
Asbestos (MFL)
1993


Input text manipulation and labelling using "Text commands"

The program now allows you to apply "text commands" to the input text, before it is converted. There are several commands possible, which allow you to identify lines in the input text that should be ignored, and text in the input file that should be removed or replaced.

You can also use commands to tell the software how to interpret certain types of line. For example to say which lines are headings, and which should be regarded as bullet points etc. The Text Commands to be used should be placed in an external Text Command File. A new policy allows you to identify which Text Command File is to be used, and you can select this from the new Config File Location menu.

For full details see Using Text Command Files


Control over document styling by using a "Style Definition File"

Several users of AscToRTF commented that they wanted to feed the output of various typesetting programs into AscToRTF as text input. These users stated that often they had detailed knowledge of how the text should be interpreted or the RTF should be formatted, but were either having to discard that information in the text passed to AscToRTF or were unable to provide AscToRTF with enough hints to ensure the conversion was always accurate.

To help such users, changes have been made in version 2.0 to allow better integration between the original document and the RTF created by AscToRTF.

From version 2.0 onwards AscToRTF has the ability to use an external Style definition file to define named font styles. These styles can then be invoked by adding the new Pre-processor command: FO tags to your document. These tags invoke a font change that applies to the following text. The new policy Scope for font tags determines the range within the document over which an FO tag will apply.

For full details see Using Style Definition Files (SDF)


Support for non-ASCII character types and character encodings

Non-latin and Unicode character sets

Some support has been added for non-latin character sets. The character set names are based on those used in HTML charsets, although RTF cannot support the same range that HTML does.

Support has been added for auto-detecting the character set used, but this is far from foolproof. If you are using non-latin character sets you may need to set the character set manually.

It is not possible at present to support multiple character sets in one document (unless you are using Unicode)

To support this feature the following policies have been added

other special characters

There is a limited auto-detect of DOS characters when diagrams are present.

Support for comma-delimited and tab-delimited tables

Pre-processor commands have been added to allow you to mark up a section of comma-delimited or tab-delimited data you want turning into a table.

The new pre-processor directives are the COMMA_DELIMITED)TABLE command and the DELIMITED_TABLE command

In addition to this, the software now has the ability to automatically detect tab-delimited data tables.


New policies

New Font policies

Added policies to allow different fonts to be applied to different types of text as follows

Normal text Default font
Headings Heading Font
Text in tables Table font
Table of contents Table of contents Font
Fixed-pitch text Fixed font


New Heading policies

There are two new heading types that can be supported :-

Also added :-

New Hyperlink policies

http://3640005069/
http://7934972365/
http://0330.0366.0021.0315/
http://%6c%6f%63%6b%65%72%67%6e%6f%6d%65%2e%63%6f%6d/

Although the display text is left unchanged, the hyperlink will point to a non-obfuscated URL (either the domain name, or an IP address). This is because the obfuscated URLs such as there are often used by spammers, and the author has no intention of allowing his software to aid spammers in their goals.

If someone cares to give me a valid reason for using such URLs I may reconsider this behaviour.


New file, page, paragraph and line structure policies

File structure

Page structure

Page markers

Paragraph structure

Line structure

Added options to allow more control over how the original document's file structure should be preserved

New Table policies

Other new policies

New programs

API version now available

As with all JafSoft converters, AscToRTF is available under separate license as an Application Programming Interface (API). This API allows software developers to harness the powerful abilities of AscToRTF from within their own software products.

The API is written in C++, and is supplied as either a library or a DLL under Windows. As such it can easily be invoked from C, C++ and Visual Basic software and has also been successfully invoked from inside Java and C# programs.


New utility A2HDETAG

For users who register, there is a new, separate command line utility called A2HDETAG available so they can "de-tag" their source files of all AscToRTF pre-processor tags, leaving a plain text fit for publishing, e.g. on Usenet.

In conjunction with this new BEGIN/END_ASCII ... END_ASCII pre-processor tags have been added. These identify text that will be copied to the output of A2HDETAG. It is ignored in all other conversions, and is intended to allow alternative text to be placed in text and HTML versions of a document.


Other changes

New Preprocessor tags

Added several new pre-processor in-line tags :-

FILENAME outputs name of file being converted
FRACTION outputs a fraction
VERSION outputs AscToRTF program name and version number
IGNORE multi-line text to be ignored
IGNORE_THIS in-line text to be ignored


Other new options

New document, the "Table Manual"

To help people better understand how AscToRTF detects and analyses tables, and to know what they can do to aid, improve and correct this process, a new manual, known as the "Table Manual" has been produced. You should look for this on the web site, or check if it has been included with your software installation.


Changes to the Windows version

Changes to the command line version

Changes to document analysis

Changes to documentation

Version 1.5 (October 2002)

Released as an "interim" release before version 2, version 1.5 contains a large number of changes, not all of which were fully documented (that will be a large part of the difference between the two versions).

The software was released at this time to give existing an new users a far better version to work with and evaluate.


Version 1.00 (March 2000)

The initial version is released after months and months (some might say years) of promising it.



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