Documentation for the AscToHTM Text to HTML converter

Previous page Back to Contents List Next page

Getting the most from AscToHTM

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
Using text definition blocks
Working with tables
Processing several files at once
Using wildcards
Using script files
Generating a directory page
Generating log files
Other tips and tricks

Making your first attempt

Starting to use the console version

To run the console version a2hcons simply type

c:> a2hcons

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


An output file which will have the same file name with a .html 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 (.html) just created. This will usually be your default word processor package.

Refining your results

If all goes well the resultant HTML 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.

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

  1. 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:> a2hcons /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 .html file generated, you will now have an output policy file "input_file.pol" which describes the document policy file calculated by AscToHTM 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.

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


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

        Create hyperlinks:        Yes
        Create mailto links:      Yes
        Create NEWS links:        Yes

These are all default values used by AscToHTM. 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

        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 AscToHTM generates

Using link dictionary files

In addition to adding hyperlinks for all URLs, email addresses, section references and contents list entries, AscToHTM 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" + ""

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 "" with the text "Google search engine" being highlighted.

Link Dictionary Edit Dialog

Menu location: Conversion options -> Configuration files -> Link Dictionary
(Enter a filename and then select "Edit")

This dialog allows you to edit the links in your link dictionary, although if you take care you can do this more easily by opening up you dictionary file in a text editor such as NotePad.

To enter a new link

  1. Click on "Add a new link definition"
  2. Enter the definition details in the edit boxes, replacing the demonstration text
  3. Press the "Add link" button.

To update or remove a link

  1. Click on the desired link on the list on the left.
  2. Edit the details of the link in the edit boxes on the right
  3. Press the "Update link" or "Remove Link" buttons

Each link definition consists of three parts :-

Text to be matched

This is the text as it will appear in your source file. The text must be contained on a single line of the input file. Care should be taken to avoid using substrings of other matched text. For this reason it is a good idea to edit your source files to put brackets round the links your want [like this] and then only match the text including the brackets.

Replacement text

This is the text that will appear as the hyperlink text. Normally this is very similar to the matched text.

Hyperlink URL

This is the hyperlink's URL. It can be absolute or relative or even local to the current page. Just ensure it is correct

See also Using link dictionary files

Using multiple policy files

If you wish to use AscToHTM 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 AscToHTM allows two special types of line in the policy file.

  1. 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.

  1. "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

AscToHTM 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.

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

Using text definition blocks

Using pre-processor tags you can define "blocks" of text known as "definition blocks".

Definition blocks allow blocks of output to be defined out of sequence, that is the content is defined in one location, and then may be instantiated at a number of different locations.

A definition block has the form

        $_$_DEFINE_BLOCK <block name>
        text that forms the block

The text inside the block may contain in-line tags, but it cannot contain any other tag directives.

To invoke a block use the EMBED_BLOCK or INSERT_BLOCK commands.

One tag that is particularly useful inside blocks is the VARIABLE tag. You can define variables throughout the document and then quote them inside a define block.

A possible example of use would be the addition of "page" footers. You could define the text that goes inside a page footer, and include in it a variable called PAGE_NUMBER. You can then re-define the PAGE_NUMBER and output a new page boundary with the commands


having previously defined a PAGE_FOOTER block.

It should perhaps be pointed out that "pages" are anathema to HTML, but should you want this feature this is a possible implementation.

Working with tables

AscToHTM does a reasonable job of detecting and analysing Tables, but the following tips can be useful.

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.

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

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:> a2hcons @List.file [rest of command line]

Where the file "list.file" is a steering file which contains a list of AscToHTM 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

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 a2hcons 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.

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

Generating a directory page

When converting several files at once, AscToHTM can be made to generate a "Directory Page". This is an HTML index of all the files converted and their contents.

The policies available for controlling generation of a directory page are explained in "Directory page policies".

The directory page will consist of an entry for each file converted, in the order that files are converted (usually alphabetic). Each entry will (optionally) contain :-

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

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.

Other tips and tricks

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