Running as a Windows application

Main Dialog

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

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

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

Options on this screen include :-

Load policies from an existing policy file

Reset all policies to their default values

More options are available under the Conversion Options menu.

Search sub-folders

(New in version 5.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.

Input file type

(New in version 5.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 character
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.

Delimiter character

(New in version 5.0)
When the input file type is set to "other-delimited table", then
a field appears that allows you to enter the delimiter character that should
be used to distinguish cells in each input line.

Conversion type

The main screen of the program allows you to select the conversion type you wish to
perform. These types will essentially create the same HTML, but in different ways,
suited for different uses. The options include

Output HTML to file(s)

This is the default conversion type where the
HTML will be output to either a single file, or
a set of files if you elect to split a larger document.

Output to a set of HTML Frames

If you choose this option a set of HTML Frames
will be created.

Output to the Windows clipboard

If you choose this option the HTML generated will
be copied onto the Windows clipboard, and no HTML
files will be created.

May Overwrite Files

Depending on the conversion type you select, the main screen will
also allow you to specify whether or not existing files name be overwritten.

This protects against AscToHTM overwriting your files, but if you are
repeatedly converting the same files you will need to either disable this
option, delete all the existing files, or choose a different output location.

If converting multiple files, the program will abort at the first attempt
to overwrite an existing 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).

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

Output policies menu

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.

Selecting the HTML Fragments File

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.

Selecting the Table Definition File

Selecting the Text Command File

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

AscToHTM has many options known as "policies" to help you improve and
correct the analysis it performs, and to customise the HTML 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

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:

Save only those policies that have changed

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.

Save all policies

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

Drag and drop settings

These options specify the behaviour of AscToHTM when invoked via
drag and drop (i.e. by dropping a file icon on AscToHTM'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 AscToHTM 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.

Use of policy file settings

Using a default policy file

This determines which policy file, if any, is to
be used by default when AscToHTM 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 AscToHTM 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.

Tip of the day

The "Tip of the day" dialog will normally appear each time the program starts
up. It will show a different tip each time it is displayed. Next and
last buttons (labelled "<<" and ">>") can be used to review each tip in turn
and the tip number is shown at the bottom should you want to take note
and access the tip later.

You can disable this feature by unchecking the "Show on Startup" tickbox, and
you can always recall it via the option on the Settings Menu.

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 athttp://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. Thanks
also go to Joan Marsh and Sandy McGregor for help with the
earlier versions of the translation.

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

Dutch

The Dutch translation is being undertaken by Jurrien Dokter,
who can be contacted at info<at>c-webpromo.nl and runs
the web site at http://www.c-webpromo.nl/

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

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

Language 'Skins'

AscToHTM 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

View conversion results

Once you've converted a file, you can view the results in the browser
of your choice. AscToHTM 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.

AscToHTM 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

HTML doco (offline)

Brings up the local copy of the HTML documentation in your

preferred browser

HTML doco (online)

Brings up the Internet copy of the HTML 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.

Update menu

The updates menu has the following option

Check for newer versions
This option will take you to the web site, where a check will be made
to tell you if this is still the latest version of the software.

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

Once conversion is complete you can dismiss the window. You can automate
this by ticking the "dismiss on completion" box.

Should you wish to you can use the save to file button to save the
messages displayed to file. This can be useful for reviewing messages,
extracting URLs reported by the software (if showing URLs is enabled),
or for sending details when requesting support.

Running as a command line program

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

The command line has the syntax

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

if running the console version, or

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

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

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

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

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.

Command line qualifiers: /HELP

Command line qualifiers: /INDEX

This qualifier will cause the program to create a master index or "directory page" file
with hyperlinks to all the sections detected in the files converted. Only useful if
you're converting multiple files at one time.

Command line qualifiers: /LIST

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

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 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 AscToHTM.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 .html 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 AscToHTM shouldn't look for more complex
constructs such as headings etc.

Command line qualifiers: /TABBED

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

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

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

To add AscToHTM to this menu, simply add a shortcut to your
SendTo shortcuts folder. Under Windows 9x this is

/Windows/SendTo

under Windows XP this is

/Documents and Settings/<Your_User_Name>/SendTo

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

AscToHTM %1 standard.pol

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 if you were Running as a command line program.

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.

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