| Back to Contents List |
|
Contents of this section
Making your first attempt
Starting to use the console versionRefining your results
Starting to use the Windows version
Using policy files to improve the conversionProcessing several files at once
Using link dictionary files
Using multiple policy files
Use the pre-processor and in-line tags
Using text definition blocks
Working with tables
Using wildcardsGenerating a directory page
Using script files
Generating log files
Other tips and tricks
To run the console version a2hcons simply type
c:> a2hcons Input_file.name
at the command line. This will create a file :-
input_file.html
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.
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.
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.
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 :-
You can create a sample .pol policy file that documents the policies used. Do this either by using the command linec:> a2hcons 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 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.
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 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
[Hyperlinks]
------------
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
[Hyperlinks]
------------
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
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" + "www.google.com"
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 "www.google.com" with the text "Google search engine" being highlighted.
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
- Click on "Add a new link definition"
- Enter the definition details in the edit boxes, replacing the demonstration text
- Press the "Add link" button.
To update or remove a link
- Click on the desired link on the list on the left.
- Edit the details of the link in the edit boxes on the right
- 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
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.
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.
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.
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 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
..
$_$_END_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
$_$_DEFINE_VARIABLE PAGE_NUMBER 21
$_$_INSERT_BLOCK PAGE_FOOTER
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.
AscToHTM does a reasonable job of detecting and analysing Tables, but the following tips can be useful.
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.
- You can use wildcards to specify the filenames The wildcard will be expanded to a set of filenames, and each file will be processed in turn.
- (From the command line only) You can use a script file That is you can pass the name of a file which lists the files you want converted.
- (From the command line only) You can pass in multiple file specifications, each of which can be a wildcard. For details see running as a command line program
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
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
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 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.
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 :-
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.
 |
Converted from
a single text file by
AscToHTM © 1997-2004 John A Fotheringham |  |