AscToHTM

Documentation for the AscToHTM conversion utility

This documentation can be downloaded as part of the documentation set in .zip format (370k)


Previous page Back to Contents List Next page

4 Running AscToHTM

4.1 Windows version

4.1.1 Launching the program

4.1.1.1 Normal activation

Just run the program as you would any other Windows program, i.e. by clicking on its icon, or launching it from the Start menu.


4.1.1.2 Execution from a command line

From a Windows console command prompt you can type

C:> AscToHTM

or

C:> AscToHTM <file1> <file2> ...

In the first case, AscToHTM is launched as normal.

In the second case AscToHTM will convert the specified files, briefly displaying a status window, and then exiting. In this case, one of the named files can be a .pol policy file.

Note, a console version of AscToHTM (A2hCONS) exists that can only be run from the Command line prompt. The Windows version also supports this command syntax, but users wanting to do large conversions, or conversions from within a batch file are advised to use the console version. Currently the console version is only being made available to registered users.


4.1.1.3 Drag'n'Drop execution

Create an Icon for AscToHTM, and simply drag'n'drop files onto it. The results are identical to those obtained by typing in the filenames as described in 4.1.1.2.

Alternatively, run the program as normal and then drag files onto the running program. You can configure the program's behaviour in drag'n'drop operation by using the Settings | Drag'n'Drop menu.

One useful suggestion is to add AscToHTM to your "SendTo" menu (shown when you right-click on a file). See the Windows help file for more details.

See 4.4.6 for more suggestions on using desktop icons.


4.1.1.4 Output to the Windows clipboard

New in version 4

You can use the program to convert the file to HTML, and to copy the HTML into the Windows clipboard, ready for pasting into other applications (such as a HTML editor).

To do this, launch the Windows program as normal, and set the Conversion Type on the main screen to "Output HTML to clipboard".

The HTML copied to the clipboard will be without the <HEAD> and <BODY> tags to make the HTML more suited to pasting into an existing HTML page.


4.1.2 Using the Windows Interface

The Windows interface was re-vamped in version 3.0 and further enhanced in version 3.2. The main changes are

4.1.2.1 Doing a straightforward conversion

To do a simple conversion, simply enter the name of the file to be converted or use the "Browse" button to locate the file to be converted.

Then press the "Convert file(s)" button.

A status screen is displayed whilst the conversion is in progress. For small files this may flash up so fast you can't actually read it. (If you want to see what it said go to the View...Messages menu option)

To view the HTML, press the "View results" button. This should launch your preferred HTML viewer to display the newly created HTML page. If you want to automate that process, edit the program's viewer settings (see 4.1.2.4).


4.1.2.2 The File menu

The File menu has the following options:

Initiates the conversion. If you already have a file selected, this file is converted. If you don't, then a browse window will open allowing you to choose a file to convert.

This option is identical to pressing the "Convert files" button.


This option allows you to load a set of policies previously saved to a policy file. This allows a conversion to be repeatedly done the same way, or a set of conversions to be done the same way (see 6.5)

Note, you can set a policy file to be used by default see 4.1.3.

This option allows you to save your current set of policies to a policy file for later re-use. It is recommended that only a partial set of policies (i.e. any loaded policies and manually set policies) be saved to allow the program maximum flexibility when converting future files.

See section 6.5 and the discussion in 6.5.2.1

Exits the program


4.1.2.3 The Conversion options menu

AscToHTM offers the advanced user a large number of program options. These are called policies, and may be saved in policy files for later re-use. Policy files are described in detail in Chapter 6 of this document.

Policies broadly come in two sorts.

The Conversion Options menu has options to allow you to view and change many of the program's policies (but not all, see the Policy manual for details).

The menu also has options to

These options allow you to browse for and open the policy file that you want to use. Essentially they are identical to the load option on the File menu (see 4.1.2.2)

This allows you to reload the policy file (e.g. because you've just edited it by hand)

This allows you to save the current policies to file for later reuse.

This option forces AscToHTM to re-analyse the current source file to (re-)calculate the analysis policies.

This option forces all policies back to their AscToHTM defaults. This will negate the effect of any manually set policies, or policies loaded from a policy file.


4.1.2.4 The Settings menu

The Settings menu allows you to tailor the way in which the program executes. These settings will usually be saved in your Registry so that they are remembered for next time.

The Settings menu includes options for

Specifies the location of the program's documentation on your hard disk (see 4.1.3.1).

Specifies the level and type of error reporting wanted during the conversion (see 4.1.3.2)

Specifies the program's behaviour when invoked by dragging files onto the program's icon (see 4.1.3.3.).

Specifies the browser to be used to view results files, and how it should be invoked (see 4.1.3.4).

Specifies any default policy file to be used (see 4.1.3.5).


4.1.2.5 The Language menu

The language menu allows you to change the language used in the user interface. These translations are provides by a group of volunteers. Currently translations exist for :-

The software supports the concept of language "skins" which allow the user interface to be exported to an external file which may be edited and then re-loaded. This allows users to offer their own translations, or to correct errors in the existing translations.

You can read more in Language support


4.1.2.6 The View menu

This option allows you to re-view the Messages window displayed during file conversion. On small files this window can sometime be shown too briefly to view the messages.

This option will launch the preferred browser for the last file converted. If a wildcard conversion was done, the last file in the group is shown. This option has the same effect as the "View results" button.


4.1.2.7 The Help menu

This option brings up the Windows help file. This offers a lot of context-sensitive help which can usually be accessed by pressing F1 or "Help" anywhere in the program.

Over time the Windows Help file has adopted a secondary role compared to the HTML documentation.

This option takes you to the web page offering registration details or (if you've already registered) listing recent updates.

Currently the registration page is http://www.jafsoft.com/asctohtm/register_online.html?from=doco

This option allows you to view the HTML documentation for the software. You can either view your local copy from your hard disk, or read the version on the web site (you'll need to connect to the Internet in that case).

Each installation of AscToHTM comes complete with HTML documentation. Should you decide to move your copy of the documentation, you'll need to alter the settings (see 4.1.3)

A list of web pages describing other JafSoft Limited products that may be of interest to you.

This option launches the About screen. This gives program version information, shows your registration status, and provides a couple of buttons to access the home page and other pages on the Web.


4.1.3 Program settings

These settings allow you to customize the program's behaviour to a limited extend.


4.1.3.1 Documentation

Allows you to specify the location of the HTML documentation for the program on your machine. By default this is the same as the program directory, and you should only need to change this if you move it.


4.1.3.2 Diagnostics

Allows you to select the level of detail you want in the messages displayed during conversion. You can also elect to suppress messages by type.


4.1.3.3 Drag and drop execution

Allows you to specify how you want the program to behave when it is launched by dropping files into the program, or its icon on the desktop.


4.1.3.4 Results viewers

Allows you to specify the HTML browser to be used to view the created HTML. You can elect to always invoke a results viewer after conversion, and to use DDE to achieve this.

DDE allows the program to tell an existing browser to display the results. Without DDE a new instance of the browser is launched each time. The behaviour of the browser when sent the results file varies from browser to browser.

If the DDE call fails for any reason, a new instance of the default browser is launched, so you should ensure this is the same browser as that identified for DDE.

This dialog also allows an RTF viewer to be selected. This may be used for viewing RTF files, although it's possible that at present your version of the program doesn't require this yet.

NOTE:
On some systems DDE doesn't always work properly. This would cause the program to hang when it attempted to display results. In such cases you would need to stop the program from the task manager. The program will now detect when this has happened and disable use of DDE next time it runs. You can re-enable it using the Settings | Viewers menu option
NOTE:
Whereas DDE works fine with Netscape versions up to and including 4.7, it doesn't work with Netscape 6.0 since initial versions of that browser don't support DDE under Windows

4.1.3.5 Use of policy files

Allows a default policy file to be specified. This is not normally desirable, but if you always use the same policy file, this will save you having to load it each time you run the program.

You can also elect to always reload the policy file during conversion. This should only be necessary if you're repeatedly changing the policy file in a text editor between conversions while the program is running.

Note, an alternative to using a default policy file is to define a desktop icon with the policy file specified on the command line (see 4.4.6)


4.1.4 Language support

There is an ongoing effort to make AscToHTM available in more languages. This effort is being undertaken by a number of volunteers. It's unlikely that full translations of User Interface, error messages, help files and documentation will be available in all languages, but the hope is to make the program a little easier for those whose first language is not English.

Please note that the author only speaks English, and thus can only offer support in English.

Elements that may be converted include :-

Less likely to be translated are :-

4.1.4.1 Existing translations

Depending on how far the process has gone (and how many changes have been made recently) not all text may be in your selected language.

Currently translations exist for :-

My thanks to all those involved. If you'd like to get involved in this effort, visit

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


4.1.4.2 Adding translations using "Language skins"

The program now supports the concept of language "skins". This allows the existing translation to be exported to a text file called a "language skin". This file consists of one line per translation per line, with a unique number at the start of the line identifying the text, and then the text itself.

You can edit this file - conventionally with a .lng extension - to contain your own versions of the strings, and then reload this back into the program via the Language menu. The changes will take immediate effect, and are remembered next time you run the program.

Using this technique we can now offer via and American spellchecker and the translation services of http://babelfish.altavista.com/ three new languages :-

These translations are not expected to be ideal, but they offer a starting point. If anyone cares to mail me corrected version I'll happily make these available... with full credit to the translator.

Mail updates to info@jafsoft.com


4.2 VMS and console application versions

The VMS version and windows console version behave identically in terms of their use of command arguments.

A Linux version has also been beta tested.

The Windows console version performs identically to the Windows version (which supports the command line operation), but is more suited to use inside batch operations. For example the Windows version is likely to gain focus when it executes, which can be distracting.

The Windows console version is called A2HCONS (to distinguish it from the fully windowed version AscToHTM), but is only available to registered users of the software.


4.2.1 Command line arguments

The command line should be of the form

AscToHTM <filespec> [<policy_file>] [</qualifiers>]

Where

Filespec
Any valid file specification for the system you're using. This can include wildcards.


In the Windows version, this can also be space
separated lists of files


Policy_file
The name of any policy file (see Using Document Policy files) you want to use for the conversion. Policy files are recognised by having a .pol file extension. For this reason you cannot convert .pol files to HTML.
Qualifiers
Extra commands that may be passed in via the command line. In most cases these are equivalent to policies, they're just made available on the command line for your convenience.

4.2.2 Command line qualifiers

Certain aspects of AscToHTM's behaviour can be changed by adding qualifiers to the command line. 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


4.2.2.1 The /COMMA qualifier

New in version 4

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.


4.2.2.2 The /CONSOLE qualifier

Specifies that the HTML generated should be directed to the output stream, rather than to an output file. This is a step towards making the program more suited for use inside a web server, e.g. to dynamically convert text to HTML on demand, although it is expected this process has some distance to go yet.


4.2.2.3 The /CONTENTS qualifier

This has exactly the same effect as the "add contents list" policy line.


4.2.2.4 The /DEBUG and /LIST qualifiers

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

.LIS1
an analysis before policy is set
.LIS
an analysis after policy is set
.STATS
a statistics file

The list files can assist in understanding how AscToHTM 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 the /LIST qualifier is used, only the list files are created. If the /DEBUG qualifier is used the .stats file is also created.


4.2.2.5 The /DOS qualifier

This has exactly the same effect as the "Use DOS filenames" policy line


4.2.2.6 The /INDEX qualifier

This has exactly the same effect as the "Make Directory" policy line


4.2.2.7 The /LOG[=filespec] qualifier

This specifies that a .log file should be created. This will contain a copy of all messages generated during the conversion, together with some that may have been suppressed.

You can specify the log filespec. This can include wildcards, with the input file being used to replace any parts of the filename not specified.

If omitted, the default log file name is AscToHTM.log


4.2.2.8 The /OUT=filespec qualifier

This 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=*.shtml" will result in a file with the same name, but a .shtml extension. In VMS "/OUT=[.sub]" will place the output in a sub-directory called "sub".

If omitted, the output file is given the same name as the input file but with a .html extension. That behaviour may change dependant on the values of a number of other policies.


4.2.2.9 The /POLICY qualifier

This has exactly the same effect as the "Output Policy file" policy line. When used it will generate a new policy file (possibly overwriting an exsisting file) which completely documents the policy used in the conversion.

This file will be a full policy file, and should not normally be used as an input policy file, as it will overly-constrain the program's ability to adapt. Instead you should edit this file to remove all bar the most important lines.

NOTE:
If you want to supply an input policy file to the conversion you do this by supplying the name of the policy file (which must have a .".pol" extension) after the names of the files to be converted. For example

AscToHTM file.txt input_policy.pol /pol=output_policy.pol

See the discussion of "full" and "partial" policy files in Chapter 3 of the Policy manual


4.2.2.10 The /SILENT qualifier

This specifies that no messages should be displayed on the console. When used with the /CONSOLE qualifier (see 4.2.2.2) this makes the program suitable for use in a web server, although you may need to use redirection under Windows.


4.2.2.11 The /SIMPLE qualifier

This has exactly the same effect as the "Keep it simple" policy line.


4.2.2.12 The /TABBED qualifier

New in version 4

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.


4.2.2.13 The /TABLE qualifier

New in version 4

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.


4.3 Getting the most from AscToHTM

4.3.1 Making your first attempt

4.3.1.1 From the command line

To run AscToHTM simply type

AscToHTM Input_file.name

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 indicating source lines that it rejects because they "fail policy". Source lines that fail policy are usually simply copied to the output file with no markup applied. These messages 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.


4.3.1.2 From Windows

Enter the name of the file to be converted in the text field. If you wish, use the browse button to search for the file to be converted.

Once you've chosen the file, the output filename and input and output directories are inferred from the filename. If you wish, you may edit the output filename and directory.

Press the Convert file(s) button. The Messages window will briefly display. If you wish to view these messages later, select the View | Show Messages from last conversion menu option.

To view the last file converted, select the View | Results of last conversion menu option. This should launch your default browser for the file types (.htm or .html) just created. If you get the message "cannot detect default browser", use the Settings menu to set up the path to the browser you wish to use and try again.


4.3.2 Refining your results

If all goes well the resultant HTML will be satisfactory and all in one file. You can further refine the conversion by creating your own document policy.

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

However, in all versions the policies can be saved to a text policy file and it is the format of that file that is shown and discussed in this document.


4.3.2.1 Using a policy file

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

AscToHTM 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 .html file generated, you will now have an output policy file "input_file.POL" which describes the document policy file calculated by AscToHTM (see 3.2) 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.

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.

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


                [Added HTML]
                ------------
                Document Title          : (none)

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

                [Hyperlinks]
                ------------
                Create mailto links     : No


                [Added HTML]
                ------------
                Document Title          : Title text for the HTML page

(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


4.3.2.2 Using a link dictionary

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    :   "[AV]" = "AltaVista" + "Using_AltaVista.html"

The syntax used here is

      Link definition    :   "match phrase" = "replacement phrase" + "link"

In this case the string "[AV]" is replaced by a link to a web page "Using_AltaVista.html" with the text "AltaVista" being highlighted.

The link dictionary used for this documentation can be seen in the file a2hlinks.dat.


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


4.3.2.4 Creating DOS-compatible files

Occasionally it may be necessary to create files consistent with the DOS nnnnnnnn.nnn naming convention. This can happen when working on a DOS or windows 3.n machine, or via a network that has this limitation e.g. Pathworks.

AscToHTM supports this. There are two ways to achieve this. Either use the command

AscToHTM input_file.name /DOS

Alternatively, simply add the lines

                [File generation]
                -----------------
                Use DOS filenames       : Yes
                DOS filename root       : A2H

to your policy file. AscToHTM will then create a base file called (in this case) A2H.HTM.

If you're splitting a large document into many files, subsequent files have the form

<filename_root>_<section number>.HTM

When this name becomes two long, AscToHTM will create a name of the form

AAANNNNN.HTM

Where AAA comes from the file root, and NNNNN is a 5-digit code derived from the rest of the file name.


4.3.2.5 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, embedding raw HTML or adding a timestamp to the file being converted.

See Using the preprocessor and In-line tags for more details.


4.3.3 Processing several files at once

4.3.3.1 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 is 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 steering command file (see 4.3.3.2)

Note:
In the shareware version, wildcard conversions are limited to only 10 files

4.3.3.2 Using a steering command file

In the console version you can convert several files at the same time in the order and manner of your choosing. To do this use the command

AscToHTM @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 /DOS
                #
                # 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 AscToHTM line are used as defaults for each conversion, but are 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 10 files

4.3.4 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 the /LOG=<filespec> qualifier (see 4.2.2.7).

Use the "Create a log file" 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. This dialog is currently limited to 32,676 characters.


4.4 Other tips and tricks

4.4.1 General

This makes it easier for AscToHTM to place things in context, reduces ambiguity and increases the chances of correct HTML being generated.

On the output pass AscToHTM rejects lines that "fail policy", so any inconsistencies are liable to lead to errors in the HTML.

Where a number has to be at the start of a line, try using an indentation level that doesn't match that used by your headings.

4.4.2 Link dictionary

If you can't avoid this, then list the longer entries first

This means avoiding overly short match words.

4.4.3 Contents List detection

Contents list detection is tricky at the best of times. It becomes even trickier if

  1. There isn't one :-)

  2. The list only contains chapters and no sub-sections

If the program wrongly determines that there is/isn't a contents list, use the following policy line

Expect Contents List : No

to tell AscToHTM how it has gone wrong. The usual error is to decide there is a contents list where none exists.


4.4.4 Using "Send to" in Windows 95/NT

AscToHTM can be invoked (without policy file) from windows in a number of additional ways as follows

If you want a policy file, drag that at the same time

If you want a policy file, add it as an argument to the shortcut's command line.

Better still, create a .BAT file to invoke AscToHTM with a default policy file - e.g. with your favourite colour scheme, and some standard link definitions (see Link dictionary policies) - and add this the "SendTo" folder.

In this way you can easily convert text files in any number of pre-defined manners.


4.4.5 Tables

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

If the table extent is wrong, try adjusting the "Table extending factor" (shown as "Extend preformatted regions" on the Conversion Options -> Analysis policies -> Tables menu option.

4.4.6 Using desktop icons and policy files

New in version 4

AscToHTM can support arguments being passed on the command line. One useful way to use the program is to add an icon to the desktop, allowing you to "drop" files onto the icon to get them converted.

If you use policy files, edit the icon properties so that the command line reads something like

"c:\program files\jafsoft\asctohtm.exe" "c:\mydir\mypolicy.pol"

This will ensure the policy file mypolicy.pol is used in the conversion. You may also need to set the working directory to something suitable.

If you have multiple policy files (e.g. different colour schemes), simply create additional icons with different policy files.



Previous page Back to Contents List Next page

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