- Launch the program as normal.
- Select the file(s) to be converted by pressing the "browse" button.
- Press the "convert file(s)" button.
From a DOS command you can type
C:> AscToHTMor
C:> AscToHTM <file1> <file2> ...In the first case, AscToHTM will be launched as normal (see 4.1.1).
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.
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.2.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.
The VMS version and windows console version behave identically in terms of their use of command arguments.
To run AscToHTM simply type
AscToHTM Input_file.nameat the command line.
This will create a file :-
- input_file.HTML
An output file which will have the same file name with a .HTML extensionThe 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.
Certain aspects of AscToHTM's behaviour can be changed by adding qualifiers to he command line. These should be entirely upper or lower case (i.e. not mixed) and must not be shortened.
This has exactly the same effect as the add contents policy line described in 6.3.4.2
This qualifier causes 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
These files are neither pretty, nor easy to read, but they can assist diagnosing faults should you wish to report them.
This has exactly the same effect as the "use DOS filenames" policy line described in 6.3.3.4.
This has exactly the same effect as the "Keep it simple" policy line described in 6.2.1.8
This has exactly the same effect as the "Output Policy file" policy line described in 6.3.3.9
If all goes well the resultant HTML will be satisfactory, if a little grey, 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 Windows Help file.
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.
If your initial results are a little strange, then re-issue the command
AscToHTM Input_file.name /policyThis 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 Using document policy files to do this.
Once you've produced your new input policy file, re-run the conversion using the command
AscToHTM Input_file.name Input_policy_file.nameThe 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).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 : "[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.TXT.
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 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.
- "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.
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>.HTMWhen this name becomes two long, AscToHTM will create a name of the form
AAANNNNN.HTMWhere AAA comes from the file root, and NNNNN is a 5-digit code derived from the rest of the file name.
You can convert several files at the same time. To do this use the command
AscToHTM @List.file [rest of command line]Where the file "list.file" 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.
- If you can, try to use as much white space as possible, e.g. before paragraphs and new sections and at the end of the document.
This makes it easier for AscToHTM to place things in context, reduces ambiguity and increases the chances of correct HTML being generated.
- Ensure you have consistency in your use of indentation, bullets etc.
On the output pass AscToHTM rejects lines that "fail policy", so any inconsistencies are liable to lead to errors in the HTML.
- Try to avoid lines that may confuse AscToHTM. For example numbers at the start of a line of text may be interpreted as a section heading. If the number is out of sequence, or at an incorrect indentation this will "fail policy". However, it may cause confusion and is best avoided wherever possible.
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.
- Try to avoid using match words that are substrings of other match words.
If you can't avoid this, then list the longer entries first
- Try to ensure you match words will only match the places you want them to match.
This means avoiding overly short match words.
- If you can bracket your match words or phrases [like this]. This makes for less mistakes, and makes it clearer in the original that you expect a link adding at that point.
Contents list detection is tricky at the best of times. It becomes even trickier if
If the program wrongly determines that there is/isn't a contents list, use the following policy line
- There isn't one
- The list only contains chapters and no sub-sections
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.
Although AscToHTM is currently a console program, it can be invoked (without policy file) from windows as follows
Better still, create a .BAT file to invoke AscToHTM with a default policy file - e.g. with your favourite colour scheme (6.3.1.8), and some standard link definitions (6.3.7) - and add this the "SendTo" folder. In this way you can easily convert text files in any number of pre-defined manners.
- Drag and drop you text file onto the AscToHTM icon.
- Create a shortcut in your "SendTo" folder in Windows. This is under C:/WINDOWS or C:/WINNT/PROFILES/<USERNAME> depending which system you're using. Once this has been done, right-clicking on a file in explorer brings up the "Send to" menu, and you can now "send" your text file to AscToHTM directly.