AscToHTM Documentation for the AscToHTM conversion utility
This documentation can be downloaded as part of the documentation set in .zip format (200k).

Prev | Next | Contents


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 will be 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:
There used to be a console version of AscToHTM that could only run from the DOS prompt. As of version 3.2 the Windows version now supports the command syntax, making it better suited for batch processing (see 4.2)

4.1.1.3 Drag'n'Drop execution

Create an Icon for AscToHTM, and simple drag'n'drop files onto it. The results will be 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.

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.


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 will be 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 will be 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.4)

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.4 and the discussion in 6.4.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 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

Expanded in version 3.2

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 they should be invoked (see 4.1.3.4).

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

Specifies the language you would like the program to run in (see 4.1.2.6).


4.1.2.5 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 will be shown. This option has the same effect as the "View results" button.


4.1.2.6 The Language menu

New in version 3.2

From version 3.2 onwards there will be 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.

Elements that may be converted include :-

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.

In version 3.2 there is some support for German and Spanish.

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.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?doco

This option launches the copy of the HTML documentation on your own computer inside the preferred browser. Each installation of AscToHTM comes complete with HTML documentation. You can view the copy on your had disk (offline), or the latest version on the web (online).

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

New in version 3.2

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

New in version 3.2

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

New in version 3.2

Allows you to specify how you want the program to behave when it is launched by dropping files into the program's icon.


4.1.3.4 Results viewers

New in version 3.2

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. Prior to version 3.2 a new instance of a browser was 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 will be 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.


4.1.3.5 Use of policy files

New in version 3.2

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.


4.2 VMS and console application versions

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


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 /CONSOLE qualifier

New in version 3.2

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.2 The /CONTENTS qualifier

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


4.2.2.3 The /DEBUG and /LIST qualifiers

Updated in version 3.2

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.4 The /DOS qualifier

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

4.2.2.5 The /INDEX qualifier

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

4.2.2.6 The /LOG[=filespec] qualifier

New in version 3.2

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.7 The /OUT=filespec qualifier

New in version 3.2

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 will be 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.8 The /POLICY qualifier

This has exactly the same effect as the "Output Policy file" policy line.


4.2.2.9 The /SILENT qualifier

New in version 3.2

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


4.2.2.10 The /SIMPLE qualifier

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



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 button. The Messages window will briefly display. If you wish to view these messages later, press the Show Messages button.

To view the last file converted, press the View results button. 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 change all that by creating your own document policy.

In the Windows version, this is done by editing policies via the Options button, 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 re-issue the command

AscToHTM Input_file.name /policy

This time in addition to the .HTML file, 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.

Review the contents of this file, looking for any policies that don't look right. Create a new .POL file containing only those policies you think are wrong, and edit them to have correct values.

You'll need to review the Policy manual in order to do this fully.

Once you've produced your new input policy file, re-run the conversion using the command

AscToHTM Input_file.name Input_policy_file.name

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. These are ignored in the input policy, as are any lines whose keywords are not recognised or not yet supported.

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


(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

New in version 3.2

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

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

4.3.3.2 Using a steering command file

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

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

4.3.4 Generating log files

New in version 3.2

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

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


Prev | Next | Contents


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