      The HTML versions of this document has, of course, been produced
      using AscToHTM itself, no post-processing has been done to the
      HTML pages produced.  The contents list, the navigation bar and all
      the hyperlinks have been generated from a single [[SOURCE_FILE]]
      a2hdoco.txt (approaching 4,000 lines and *still* growing having spawned
      the 5,000 line [Policy Manual]) and a few small configuration files.

      See section 6.1 of this document to see a list of the actual files
      involved.

      Any RTF version has been generated by the new text-to-RTF program
      (name yet to be chosen) which uses the same analysis engine as
      AscToHTM.

      This document describes AscToHTM version [[TEXT 3.2]], which will be available in
      Autumn 1999

$_$_CONTENTS_LIST

1     Introduction
------------------

      AscToHTM is an ASCII to HTML conversion tool.  It has, of course,
      been used to generate the HTML version of this document from
      the text file a2hdoco.txt (see 6.1 for more details).  The HTML version
      of this document is presented "as is".  That is, *no post-production
      of the HTML has occurred*.  This should give you a flavour of what
      AscToHTM is capable of.

      Any RTF version of this document will have been made by [AscToRTF],
      the sister product that shares the same text analysis engine.

      AscToHTM is made available for download via the Internet from
      [download location].


1.1   AscToHTM's design objectives

1.1.1 Intelligent analysis.

      AscToHTM is designed to analyse a document to determine its structure
      and layout.  This analysis allows AscToHTM to decide how best to mark
      up the HTML so as to accurately represent the author's original
      meaning.

      It also helps AscToHTM to reduce errors by allowing it to
      spot anomalies in the document source.  This is important in minimising
      the amount of any post-production work required.


1.1.2 Human-readable HTML

      AscToHTM tries to create HTML that can be easily read and modified
      in an editor.  This is useful if corrections are necessary, or
      further development is required.

      For example AscToHTM

      	a) produces short (usually <80 character) output lines

        b) attempts to indent the HTML to match the output indentation.

      	c) adds comments to the HTML to indicate include files etc.

      	d) uses <BLOCKQUOTE> tags for indentation, rather than placing the
           whole file in <TABLE>...</TABLE> tags.

      Note, later moves to make more standards-compliant and browser-compatible
      HTML code tend to work against making user-readable code.  For example
      most browsers have rendering problems when newline characters are placed
      in certain key locations, whereas adding newline characters can make the
      HTML easier to read.


1.1.3 Simple user input

      Inevitably users have supply additional information to tell AscToHTM
      where its analysis has gone wrong and to add additional information
      such as a document title etc.  AscToHTM offers a large number of
      options (also known as "policies") that the user can modify.

      Broadly speaking, these policies fall into two camps

      	- Analysis policies.  These policies affect the way AscToHTM analyses
          your file, and can be used to disable searches for things like
          bullets, or to specify whether or not underlined headings are
          to be expected.

        - Output policies.  These policies influence the types of HTML
          markup that are produced.  They also allow you add colour, headers
          footers, background images and much more to your pages.

      AscToHTM can save your policies to a file, so that next time you
      run it you can load this information back from the "policy" file.

      Policies are described fully in the [Policy Manual].  Previously they
      were described in section 6 of this document.

      You can further refine the conversion by placing special lines and
      tags into your source file.  These are known as pre-processor commands
      (see [[GOTO Using the preprocessor]]) and in-line tags (see [[GOTO Using in-line tags]]).

      To help users formulate and modify their document's policy, AscToHTM
      can be made to create an output policy file (see 4.2.2.8).
      Users can then simply edit this file and feed it back into the
      conversion process.

      A summary of the recognised policy lines is given in the [Policy manual].


1.1.4 Standards compliance.

      *New in version [[TEXT 3.2]]*

      Prior to version [[TEXT 3.2]] AscToHTM made no real attempt to be
      standards compliance.  It didn't produce bad HTML, it simply didn't
      produce strictly correct HTML either.

      From [[TEXT 3.2]] onwards, standards compliance is a stated goal.  We
      can't _guarantee_ standards compliance because the HTML generation is
      so complex that errors can and do occur, but it _is_ a goal.

      Compliance has proved to be vital to get cross-browser compatability,
      and to stand a chance of successfully applying CSS to created pages.

      I wouldn't claim to be a born-again standards bearer, but I certainly
      "get the point" now, and hang my head in shame for my past sins.

      Original versions of AscToHTM were (loosely) targeted at producing
      HTML [[TEXT 3.2]] code.

      Version [[TEXT 3.2]] is targeted at "HTML [[TEXT 4.0]] Transitional", which
      allows CSS, but also permits <FONT> tags (although these are
      deprecated).  This is a compromise standard that is best placed to
      be well viewed by V3 and V4 browsers.

      Future versions of the program will attempt to generate stricter
      HTML [[TEXT 4.0]] code, while still offering production of the earlier
      HTML standards.


1.2   Expected uses of AscToHTM

      - Migration of "legacy" text to HTML.

        Large amounts of unconverted text exist.  As people plan to put
      	this information on the Web, conversion to HTML will become necessary.

      	This can be a tedious and time-consuming task.  AscToHTM will do much
      	of the work for you.

      	AscToHTM is priced to be worth an hour of two of your time.
      	Check the [Reg location] for details.

      	This means that the "pay back" time is negligible (we only mention this
      	in case you have bean-counters to convince :).  If you don't think
        AscToHTM will save you hours, then by all means don't buy it.

      - Facilitate mastering of HTML pages in ASCII

      	The HTML created by AscToHTM may not be as pretty or as clever as that
      	generated by a full blown HTML editor (read as "bloated").

      	But...

      	It'll be easier to write, edit and spell-check, and it may have a
	hyperlinked contents list generated.

      - Automated conversions

        AscToHTM can be used to automatically convert text documents that
        you receive.  For this we usually suggest you run in command line
        mode.


1.3   Other uses of AscToHTM

      - Convert Word documents

        Please note, AscToHTM *DOES NOT* convert Word's .doc or .rtf file
        formats.

      	AscToHTM was never intended to handle Word documents.  We fully
      	expect HTML export and import filters to appear (they have in
      	Word '97), and we would advise anyone whose master document is
      	in Word to search out these filters and give them a try.

      	That said... a lot of people seem unhappy with what's already
        available, and AscToHTM does a reasonable job if you save the file
      	as text with line breaks, though obviously tables and figures will get
      	lost (in the case of tables, because Word throws them away).

      	The main problem is that Word produces lousy looking text.  This
      	is one area where AscToHTM does a little better
        than "garbage in, garbage out"

      - Pre-process text for import to Word.

      	(This is a bit cheeky, but does actually work.).

      	Use AscToHTM to convert text to HTML, then import this into your
      	word processing package.  Since the text analysis engine in AscToHTM
	out-performs that in Word in many respects (URL, table and heading
	detection to name but three), you can often get better results than
	importing from text direct..

      	That's because AscToHTM's analysis engine is *smarter*.

	NOTE: In the near future the author plans to use the analysis engine
              to generate a text-to-RTF convertor more suited to this purpose.
	      This uses the same analysis, but slightly different formatting.
	      See the [AscToRTF] home page for details.

      - Pre-process text for printing

      	Use AscToHTM to convert text to HTML, then print the file from
      	within Netscape or whatever.  The result is a much nicer looking
      	document with fonts'n'stuff.

      - Add hyperlinks to fairly ordinary pages.

        AscToHTM has a "link dictionary" feature that can be used to add
        hyperlinks to any word or phrase (see the [Policy Manual]).

      	This can greatly enhance an otherwise dull set of text pages.


2     Installation
------------------

      The shareware version of AscToHTM is made available over the web
      from [Download location].  Once you register you can download the
      full version (no nags, no limits), and are entitled to free upgrades
      for an arbitrary (equals "my decision is final") period of time.  So
      far I've *never* requested payment for any [updates] over the last 2-3
      years.  Originally upgrades were every few months, but there's a big
      gap between version [[TEXT 3.0]] and version [[TEXT 3.2]].

      Installation will vary according to the type of install kit you've
      downloaded, but in each case you first download the .ZIP file
      appropriate to your system and unzip.


2.1   VMS installation

      Unzip the files.

      If you've taken an executable version, that's it.

      If you've taken an object library version, execute the build command
      file.

      You might want to define a foreign command to get better use out
      of the program.

      Have a cup of coffee and relax :)


2.2   Windows installation

      The current version of the software makes updates to your
      Registry.  See the Install notes that come with the software
      for a description of the registry settings used.

      The Windows version requires certain .DLLs.  In earlier versions these
      were supplied separately, with the result that the download size was
      doubled.  From version [[TEXT 3.2]] onwards the program is "statically linked", meaning
      you no longer need the .DLLs as well.  The price is a slightly larger
      .exe file.


2.2.1   InstallShield version

      If you've taken an installshield version, unzip the file and then run the
      Setup program.  This will move the files to a directory, and create
      all icons etc.

      Once installed, InstallShield will also offer an uninstall option.
      You can access this via Control Panel | Add/remove software.

      The InstallShield version is substantially larger than the manual
      install versions.  This means some people experience problems
      downloading the file.

      For this reason smaller kits without InstallShield are available
      (see 2.2.2)


2.2.2 Simple .ZIP file version

      This version should be used by anyone who anticipates problems
      with the InstallShield version, or who simply wishes to upgrade
      an existing version.

      It's about 6 times smaller than the InstallShield version.

      Once you've unzipped the files, move them to your preferred directory.

      There will be no uninstall command in this case (unless you are overlaying
      an earlier installed version).


2.2.3 Console application

      Originally AscToHTM was only available as a console application.  Now
      it is available as a fully-windowed application.  Consequently this
      version is not so widely available.

      The console version will be made available to registered users who wish
      it, as it is more suited for automated conversions inside batch jobs etc.

      The conversion engine is identical in each case, it's just GUI-less.

      Please note, this is *not* the same as any DOS version that we used
      to produce, and will require a Win32 environment.  The DOS version is
      no longer supported.

      Note:  From version [[TEXT 3.2]] onwards the Windows version of AscToHTM has merged the
             console and Windowed interfaces into a single program, making
	     the console version redundant.  As a result this is no longer
	     shipped unless users have a specific requirement.


3     How AscToHTM works
------------------------

3.1   The big assumption

      AscToHTM makes one big assumption :-

      		Each text file has been laid out in a consistent manner
      		by its author in a way that makes it easy for a human reader
      		to understand.

      Given this, AscToHTM tries to read the text file and mark it up in
      HTML accordingly.  This is achieved by making three passes through the
      document, an analysis pass (see 3.2), a collating pass (see 3.3),
      and an output pass (see 3.4).

      Note:     Sadly this assumption is not always true


3.2   The analysis pass

      During the analysis pass AscToHTM gathers together all the statistics
      that it needs to analyse how the author has laid out the file.

      For example, the distribution of line indentations and line lengths
      is observed, together with the number and types of bullets, section
      headings and lots of other stuff.

      Once this has been done, the program uses this data to determine how
      the author has structured the document.  For example are the section
      headings underlined, capitalised or numbered?  If numbered, what style
      of numbering is used, and at what level of indentation is the heading
      placed?

      This information is then used to set the analysis polices (see the
      [Policy Manual]) which may then be overridden by the user, or by
      loading a policy file with different values.


3.3   The collating pass

      *New in version [[TEXT 3.2]]*

      Having performed the analysis, the program makes a second "collating"
      pass.  This is effectively a dry run for the output pass.

      During this pass the program determines how the file will be output
      into one or more output files and where certain key in-line tags occur.

      It also assembles any contents list.

      This information is then used during the output pass to reduce the
      likelyhood of errors, and to ensure all internal hyperlinks are valid
      and will point to the correct anchor point in the correct output file.


3.4   The output pass

      During the output pass AscToHTM

      - Generates HTML (there's nothing like stating the obvious)
      - (optionally) creates a suite of inter-linked HTML pages
      - (optionally) generates a contents list
      - (optionally) generates a directory page


3.4.1 Generating HTML

      The HTML generated depends only on the original document, the calculated
      document policy, and any user policies supplied.

      [[GOTO HTML markup produced]] describes the markup produced in more detail.


3.4.2 Generating a contents list

      AscToHTM can detect the presence of a contents list in the original
      document.  Alternatively you can choose (see 6.3.4) to have
      AscToHTM to generate a contents list for you, in which case any
      original list is omitted from the output HTML document.

      Regardless of whether the original or generated contents list is used,
      AscToHTM will turn the contents list into hyperlinks that will take
      you to the correct HTML file and location.

      There is a fuller discussion of contents lists in 5.6.2.  The policies
      that influence contents list production are listed in 6.3.4, whilst
      the pre-processor commands are described in 7.1.3.


3.4.3 Splitting the document into many HTML pages

      By default AscToHTM creates a single .HTML file.  However, through file
      organisation document policies (see 6.3.3) it is possible to

      a) Split the document into a number of smaller .HTML files (see
         the policy [[HYPERLINK POLICY,"Split Level"]]).

      b) Insert standard JavaScript into the <HEAD> ... </HEAD> section of
         each page (see also the policy [[HYPERLINK POLICY,"HTML script file"]]).

      c) Add a HTML "header" to the top of each generated file (see also the
	 policy [[HYPERLINK POLICY,"HTML header file"]])

      d) Add a navigation bar at the foot of each page with links to the
         Next/Previous .HTML page and the contents list (see also the
	 policy [[HYPERLINK POLICY,"Add navigation bar"]]).

      e) Add a HTML "footer" to the end of each generated page (see also the
	 policy [[HYPERLINK POLICY,"HTML header file"]])


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 [[TEXT 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 [[TEXT 3.0]] and further enhanced
      in version [[TEXT 3.2]].  The main changes are

      	- Introduction of a Windows Menu to replace the old button bar
      	- More options on this menu to make locating the correct features
	  more accessible.
      	- The policy property sheets no longer have to be closed when doing
          a conversion.
	- Use of DDE to view results in browsers already running.


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:

      - *Convert*

      	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.


      - *Load policies from file*

      	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.

      - *Save policies to file*

      	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

      - *Exit*

      	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.

      - _Analysis policies_ represent a description of what the source file
	does and does not contain.  These policies are usually set to default
	values and/or calculated by analysing the source document.  They
	should only ever need to be manually adjusted if you wish to
	correct the analysis, or override the detection of certain
	typographical features.

      - _Output policies_ represent styling and other options that cannot be
	inferred from the source document.  These include styling and markup
	options, and allow the user to "add value" to the HTML generated.

      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

      - *Load, or change, the policy file used*

	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)

      - *Re-analyse the file*

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

      - *Reset to defaults*

      	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 [[TEXT 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

      - *Documentation*

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

      - *Diagnostics*

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

      - *Drag and drop execution*

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

      - *Results viewers*

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

      - *Use of policy files*

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

      - *Language*

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


4.1.2.5 The View menu

      - *Messages*

      	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.

      - *Last conversion*

      	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 [[TEXT 3.2]]*

      From version [[TEXT 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 :-

      - ToolTips
      - Menu Text
      - Window Text
      - Messages
      - Windows help file
      - HTML documentation

      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 [[text 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

      - *Contents*

      	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.

      - *Register/check updates*

        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

      - *HTML documentation*

      	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)

      - *Other products*

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

      - *About*

      	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 [[TEXT 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 [[TEXT 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 [[TEXT 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 [[TEXT 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 [[TEXT 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 [[TEXT 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 [[GOTO 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 [[TEXT 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 [[HYPERLINK POLICY,"add contents list"]]
      policy line.


4.2.2.3 The /DEBUG and /LIST qualifiers

      *Updated in version [[TEXT 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 [[HYPERLINK POLICY,"Use DOS filenames"]] policy line

4.2.2.5 The /INDEX qualifier

      This has exactly the same effect as the [[HYPERLINK POLICY,"Make Directory"]] policy line

4.2.2.6 The /LOG[=filespec] qualifier

      *New in version [[TEXT 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 [[TEXT 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 [[HYPERLINK POLICY,"Output Policy file"]] policy line.


4.2.2.9 The /SILENT qualifier

      *New in version [[TEXT 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 [[HYPERLINK POLICY,"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 :-

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

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

      b) "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 [[TEXT 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 [[GOTO Using the preprocessor]] and [[GOTO 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

$_$_BEGIN_PRE
		! this is the main document
		DOCO.TXT   	IN_DOCO.POL /DOS
		#
		# These are the other chapters
		CHAPTER2.TXT
		CHAPTER3.TXT	/SIMPLE
$_$_END_PRE


      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 [[TEXT 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 :-

      - *From the command line*

      	On the command line you can use to launch the program, add the
      	the /LOG=<filespec> qualifier (see 4.2.2.6).

      - *From the policy file*

      	Use the [[HYPERLINK POLICY,"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.

      - *From the Status Dialog*

      	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

      - Read the [FAQ]

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


4.4.2 Link dictionary

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


4.4.3 Contents List detection

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

      a) There isn't one

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

      - Drag and drop your text file onto the AscToHTM icon.

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

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

      	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.

      - If the extent of the table is wrongly calculated, mark it up using
        TABLE pre-processor commands described in 7.1.2, or insert an extra
      	blank line before and/or after the table.  Tables will rarely bridge
      	a two-line gap.

      - If AscToHTM places a code fragment or diagram in TABLE markup, mark
        the source using CODE or DIAGRAM pre-processor commands (7.1.5
        and 7.1.6)

      - Avoid mixing tabs and spaces.  This makes spotting column alignments
        positions more difficult.  If you do mix them, check that the
        [[HYPERLINK POLICY,"TAB size"]] policy has a suitable value.

      - If you want the heading in bold, try drawing a line all the way
        across, separating header from data

      - If AscToHTM creates too many columns, adjust the [[HYPERLINK POLICY,"Minimum TABLE column separation"]]
	to be greater than 1, and ensure there are at least two spaces
	between columns (see 7.4).  Alternatively "break formation" by
	inserting a space at the start of every second or
        third line.

      - If AscToHTM puts lines in tables when they shouldn't be, increase
        the [[HYPERLINK POLICY,"Minimum automatic <PRE> size"]] value.  This is
        a common problem in email digests with people's .sigs in them.

      - If you wish to fine-tune a particular table, use the pre-processor
        commands described in 7.4.

      - If the table layout is approximately correct, switch off the table
      	border (set the value to 0).  Often this will look acceptable, even
        though the analysis has gone wrong.


5     HTML markup produced
--------------------------

5.1   Text layout

5.1.1 Indentation

      AscToHTM performs statistical analysis on the document to determine
      at what character positions indentations occur.  This information is
      used on the output pass to determine the indentation level for each
      source line.

      AscToHTM attempts to indent the HTML code to match the output
      indentation level, to make it easier to read.

      The indentations themselves will be marked up using
      <BLOCKQUOTE> ... </BLOCKQUOTE> tags.

      Future versions (after version [[TEXT 4.0]]) of AscToHTM may offer you the option of using
      <DIV> tags.


5.1.2 Hanging paragraph indents

      Some documents, especially ones dumped from Word, have hanging paragraph
      indents.  That is, each paragraph starts at an offset to the rest of the
      paragraph.

      AscToHTM struggles heroically with this, and tries not to treat this as
      text at two indent levels, but it does occasionally get confused.

      If writing a text file from scratch with AscToHTM in mind, then it is best
      to avoid this practice.


5.1.3   Bullets

      AscToHTM detects and supports several types of bullets.


5.1.3.1 Bullet chars

      Bullet chars are lines of the type

$_$_BEGIN_PRE
      	- this is a bullet line

      	- this is a bullet paragraph
      	  because it carries over onto
      	  more lines
$_$_END_PRE

      That is, a single character followed by the bullet line.  AscToHTM
      can determine via statistical analysis which character, if any, is being
      used in this way.  Special attention is paid to the '-' and 'o'
      characters.

      Bullets of this type are given a <UL> ... <LI> ... </UL> markup.


5.1.3.2 Numbered bullets

      AscToHTM can spot numbered bullets.  These can sometimes be confused
      with section headings in some documents.  This is one area where
      the use of a document policy really pays dividends in sorting the
      sheep from the goats.

      Numbered bullets are given a <OL TYPE=1 START=N> ... <LI> ... </OL>
      markup.

      Note:	Not all browsers support this type of markup.  In such
      		cases, it's possible that the numbering of bullets will
      		get reset to 1 every so often.  However, this isn't a
      		problem with either Netscape or Internet Explorer.


5.1.3.3 Alphabetic bullets

      AscToHTM detects upper and lower case alphabetic bullets.  These are
      marked up like numbered bullets, with TYPE=a.


5.1.3.4 Roman Numeral bullets

      AscToHTM detects upper and lower case roman numeral bullets.  These are
      marked up like numbered bullets, with TYPE=i.


5.1.4 Centred text

      AscToHTM can attempt to spot sections of centred text.  However, because
      this can easily go wrong this option is normally switched off.

      Centering is only switched on for single isolated lines, or any group
      of at least two lines.  <CENTER> ... </CENTER> markup is used.


[[LINKPOINT "Definitions"]]
5.1.5 Definitions

5.1.5.1 Definition lines

      A definition line is a single line that appears to be defining
      something.  Usually this is a line with either a colon (:) or an
      equals sign (=) in it.  For example

$_$_BEGIN_PRE
      	IMHO = In my humble opinion

        Address : Somewhere over the rainbow.
$_$_END_PRE

      AscToHTM attempts to determine what definition characters are used
      and whether they are strong (only ever used in a definition) or
      weak (only sometimes used in a definition).

      AscToHTM marks up definition lines by placing a <BR> on the end of the
      line to preserve the original line structure.  Where this decision is
      made incorrectly unexpected breaks can appear in text.

      AscToHTM offers the option of marking up the definition term in
      bold.  This is not the default behaviour however.


5.1.5.2 Definition paragraphs

      AscToHTM also recognises the use of definition paragraphs such
      as :-

$_$_BEGIN_PRE
      Note:	This is a definition paragraph whereby the whole
      		paragraph is defining the term shown on the first line.
      		Unfortunately AscToHTM currently only copes with single
      		paragraphs (i.e. not with continuation paragraphs), and
      		only with single word definitions.
$_$_END_PRE

      This gets marked up in a <DL> <DT>...</DT> <DD>...</DD> </DL> sequence

      Note:	This is a "definition" paragraph, i.e. the whole
      		paragraph defines the term shown on the first line.
      		Unfortunately AscToHTM currently only copes with single
      		paragraphs (i.e. not with continuation paragraphs), and
      		only with single word definitions.


5.2   Text formatting

5.2.1 Quoted lines

      AscToHTM recognises that, especially in Internet files, it is
      increasingly common to quote from other text sources such as e-mail.
      The convention used in such cases is to insert a quote character
      such as > at the start of each line.

      Consequently, AscToHTM adds a <BR> tag at the end of such lines to
      preserve the line structure of the original, and marks it up in
      <EM>..</EM> tags to differentiate the quoted text


5.2.2 Emphasis

      AscToHTM can look for text emphasised by placing asterisks (*) either
      side of it, or underscores (_).  AscToHTM will convert the enclosed text
      to *bold* and _italic_ respectively using <STRONG> and <EM> tags
      respectively.

      From version [[TEXT 3.2]] onwards AscToHTM will also look for combinations of asterisks
      and underscores which will be placed in _*bold italic*_.  The asterisks
      and underscores should be properly nested, e.g.

      The emphasised word or phrase should span no more than a few lines, and
      in particular should *not* span a blank line.  If the phrase is longer,
      or if AsctoHTM fails to match opening and closing emphasis marks, the
      characters are left unconverted.

      Tests are made to ignore double asterisks and underscores.


5.3   Added hyperlinks

5.3.1 Contents List lines

      Contents list lines are marked up in bold, and turned into a hyperlink
      pointing at the section referenced.  The text is sized according to
      heading type in the range +/- 1 font size from normal (3).


5.3.2 Cross-references

      AscToHTM can convert cross-references to other sections into hyperlinks
      to those sections.  Unfortunately this is currently only possible for
      second, third, fourth... level numeric headings (n.n, n.n.n, n.n.n.n etc)

      This is because the error rate becomes too high on single numbers/letters
      or roman numerals.  This _may_ be refined in future releases, although
      it's hard to see how that would work.


5.3.3 URLs

      AscToHTM can convert any URLs in the document to hyperlinks.  This
      includes http and ftp URLs and any web addresses beginning with
      www.


5.3.4 Usenet Newsgroups

      AscToHTM can convert any newsgroup names it spots into hyperlinks to
      those newsgroups.  Because this is prone to error, AscToHTM currently
      only converts newsgroups in known USENET hierarchies such as
      rec.gardens by default.

      This can be overcome either by

      	a) placing "news:" in front of the newsgroup name (e.g.
      	   news:this.is.a.newsgroup.honest)
      	b) relaxing this condition via a document policy (see the policy
           [[HYPERLINK POLICY,"Only use known groups"]])
      	c) specifying the newsgroup hierarchy as recognised via a policy
      	   [[HYPERLINK POLICY,"Recognised USENET groups"]].


5.3.5 E-mail addresses

      AscToHTM can convert any email addresses into hypertext mailto: links.


5.3.6 User-specified keywords

      AscToHTM can convert use-specified keywords into hyperlinks.  The words
      or phrase to be converted must lie on a single line in the source
      document.  Care should be taken to ensure keywords are unambiguous.
      Normally I mark my keywords in [] brackets if authoring for conversion
      by AscToHTM

      See the discussions on "link dictionaries" in 4.3.2.2 and 4.4.2.


5.4   Section headings

      AscToHTM recognises various types of headings.  Where headings are found,
      and deemed to be consistent with the prevailing document policy (correct
      indentation, right type, in numerical sequence etc), AscToHTM will use
      the standard <Hn> ... </Hn> markup.

      In addition to this, AscToHTM will insert a named Anchor tag (<A> ...
      </A>) to allow hyperlink jumps to this point.  These anchors are used
      for example in the contents list and cross-reference hyperlinks that
      AscToHTM generates.


5.4.1 Numbered headings

      This is the preferred heading type and the type that AscToHTM has most
      success with.  Sections of type N.N.N can be checked for consistency,
      and references to them can be spotted and converted into hyperlinks.

      At present more exotic numbering schemes using roman numerals and
      letters of the alphabet are not fully supported.  This is planned
      to be implemented soon, possibly via user policy files.


5.4.2 Capitalised headings

      AscToHTM can treat wholly capitalised lines as headings.  It also
      allows for such headings to be spread over more than one line.


5.4.3 Underlined headings

      AscToHTM can recognise underlined text, and optionally promote the
      preceding line to be a section header.  The "underlining" line should
      have no gaps in it.


5.4.4 Numbered paragraphs

      Some types of documents use what look like section numbers to number
      paragraphs (e.g. legal documents, or sets of rules).

      AscToHTM can recognise this, and mark up such lines by placing
      the number in bold, and not using <Hn> ... </Hn> markup on the whole
      line.


5.4.5 Mail and USENET headers

      *New in version [[TEXT 3.2]]*

      Some documents, especially those that were originally email or USENET
      posts, come with header lines, usually in the form of a number of
      lines with a keyword followed by a colon and then some value.

      AscToHTM can recognise these (to a limited extent).  Where these are
      detected the program will parse the header lines to extract the Subject,
      Author and Date of the article concerned.  A heading containing this
      information will then be generated to replace all the unsightly header
      lines.


5.5   Pre-formatted text

5.5.1 Lines and form feeds

      Lines are interpreted in context.  If they appear to be underlining
      text, or part of some pre-formatted structure such as a table, then
      they are treated as such.  Otherwise they become horizontal rules (<HR>).

      Form feeds or page breaks also become <HR> markups.


5.5.2 User defined pre-formatted text

      AscToHTM normally ignores any HTML markup in the original text.  The
      sole exceptions are any preprocessor tags which a user may insert
      into their text document (see [[GOTO Using the preprocessor]]).

      For example :-

$_$_BEGIN_PRE
      The use of BEGIN_PRE and END_PRE preprocessor commands (see 7.1.7) in
      the text documents tells AscToHTM that this portion of the document
      has been formatted by the user and should be left unchanged.
$_$_END_PRE


5.5.3 Automatically detected pre-formatted text

      AscToHTM attempts to spot sections of preformatted text.  This can vary
      from a single line (e.g. a line with a page number on the right-hand
      margin) to a complete table of data.

      Where such text is detected AscToHTM analyses the section to determine
      what type of pre-formatted text it is.  Options include

      	- Tables
      	- Code samples
      	- Ascii Art and diagrams
        - some other formatted text

      You can adjust the sensitivity of AscToHTM to pre-formatted text by
      setting the minimum number of lines required for a pre-formatted region
      using the [[HYPERLINK POLICY,"Minimum automatic <PRE> size"]] policy.


5.5.3.1 Tables

      Tables are marked out by their use of white space, and a regular pattern
      of gaps or vertical bars being spotted on each lines.  AscToHTM will
      attempt to spot the table, its columns, its headings, its cell alignment
      and entries that span multiple columns or rows.

      Should AscToHTM wrongly detect the extent of a table, you can mark up
      a section of text by using the BEGIN_TABLE ... END_TABLE
      pre-processor commands (see 7.1.2).  Alternatively you can try adding
      blank lines before and after, as the analysis uses white space to
      delimit tables.

      You can alter the characteristics of all tables via the table policies
      (see 6.3.7).

      You can alter the characteristics of all or individual tables via the
      table pre-processor commands (see 7.4).

      Or you can suppress the whole thing altogether via the
      [[HYPERLINK POLICY,"Attempt TABLE generation"]] policy


5.5.3.2 Code samples

      AscToHTM attempts to recognise code fragments in technical documents.
      The code is assumed to be "C++" or "Java"-like, and key indicators
      are, for example, the presence of ";" characters on the end of lines.

      Should AscToHTM wrongly detect the extent of a code fragment, you can
      mark up a section of text by using the BEGIN_CODE ... END_CODE
      pre-processor commands (see 7.1.5).

      You can choose what type of markup is used for the code fragment
      (see the policy [[HYPERLINK POLICY,"Use <CODE>..</CODE> markup"]]).

      Of you can suppress the whole thing altogether via the policy
      [[HYPERLINK POLICY,"Expect code samples"]].


5.5.3.3 Ascii art and diagrams

      AscToHTM attempts to recognise Ascii art and diagrams in documents.
      Key indicators include large numbers of non-alphanumeric characters
      and the use of white space.

      However, some diagrams use the same mix of line and alphabetic
      characters as tables, so the two sometimes get confused.

      Should AscToHTM wrongly detect the extent or type of a diagram,
      you can mark up a section of text by using the BEGIN_DIAGRAM ... END_DIAGRAM
      pre-processor commands (see 7.1.6).


5.5.3.4 Other formatted text

      If AscToHTM detects formatted text, but decides that is is neither
      table, code or art (and it knows what it likes), then the text may be
      put out "as normal", but with <BR> added to each line.  In such regions
      other markup (such as bullets) may not be processed such as it would
      be elsewhere.



5.6   Added value markup

5.6.1 Document Title

      AscToHTM can calculate - or be told - the title of a document.  This
      will be placed in <TITLE>...</TITLE> markup in the <HEAD> section of
      each HTML page produced.

      The Title is calculated as in the order shown below.  If the first	
      algorithm returns a value, the subsequent ones are ignored.

      1) If a $_$_TITLE pre-processor command (see 7.2.1) is placed in the
         source text, that value is used

      2) If the [[HYPERLINK POLICY,"Use first header as title"]] policy is set
         then the first heading (if any) encountered is used as the title.

      	 Note: 	Depending on your document structure, this is prone to give
         	bland tiles like "Introduction" , "Overview" and "Summary"

      3) If the [[HYPERLINK POLICY,"Use first line as title"]] policy is set
         then the first line in the file is used as the title.

      4) If the [[HYPERLINK POLICY,"Document title"]] policy is set then this value
         is used.

      	 Note:  If this is the value you want, ensure the other policies
         	outlined above are disabled.


      5) Finally, if none of the above result in a title the text
      	 "Converted from <filename>" is used.



5.6.2 Contents lists

      AscToHTM can detect the presence of a contents list in the original
      document, or it can generate a contents list for you from the headings
      that it observes.  There are a number of policies that give you control
      over how and where a contents list is generated (see 6.3.4).

      There are three different situations in which contents lists may, or
      may not be generated.  These are :-

      	- Default conversions (see 5.6.2.1).

      	- Conversion to a single file, using policies (see 5.6.2.2).

      	- conversion to a multiple files, using policies (see 5.6.2.3).


5.6.2.1 Contents lists in default conversions

      By default AscToHTM will not generate a contents list for a file unless
      it already has one.

      If it should detect a contents list in the document, then that list
      will be changed into hyperlinks to the named sections.  In such a case,
      only those headings shown in the contents list are converted into
      links, and the link text is that in the original contents list, and
      not the text in the actual heading (often they are different).

      Note:	AsctoHTM currently only detected numbered contents lists, and
      		is occasionally prone to error when they are present.  If
      		you experience problems, either delete the contents list
      		and get AscToHTM to generate one for you, or mark up the
      		existing list using the contents pre-processor commands
      		(see 7.1.3)


5.6.2.2 Contents lists in conversions to a single HTML file

      As described in 5.6.2.1, AscToHTM will not generate a contents list
      by default unless it already has one.

      _Requesting a contents list_

      However, you can request that a contents list is always generated, by
      using the [[HYPERLINK POLICY,"Add contents list"]] policy.  In this case a
      contents list will be either

      a) made from the existing contents list, or

      b) generated from the observed headings.  in this case the contents
         list will only be as good as the detection of headings in
         the rest of the document permits.

      _Forcing a generated contents list_

      You can force a generated list to be used by disabling the
      [[HYPERLINK POLICY,"Use any existing contents list"]] policy.

      If an existing contents list is present, it will be deleted from the
      output.  Normally it's best to either use the existing contents list,
      or to delete it from the source text and request a generated list.

      _Contents lists placement_

      By default the contents list will be placed at the top of the output
      file.  In earlier versions of AscToHTM the contents list was always
      placed in a separate file.

      *New in version [[TEXT 3.2]]*

      You can cause contents lists to be placed wherever you want by using
      the CONTENTS_LIST preprocessor command (see 7.3.3).  If you do this,
      then contents lists will be placed *only* where you place CONTENTS_LIST
      markers.


      _Generating a contents list in a separate file_

      If you select the [[HYPERLINK POLICY,"Generate external contents list"]] policy
      the contents list will be placed in a separate file, and a hyperlink
      to that file called "Contents List" is placed at the top of the HTML
      page generated form the document.

      You can choose the name of the external file using the
      [[HYPERLINK POLICY,"External contents list filename"]] policy.  If omitted, the file
      will be called "Contents_<filename>", where <filename> is the name of
      the document being converted.


5.6.2.3 Contents lists in conversions to multiple HTML files

      AscToHTM can be made to split the output into many files.  At present
      this is only possible at numbered section headings.  Each generated
      page usually has a navigation bar, which includes a hyperlink back
      to the following section in any contents list.

      The behaviour is identical to that in 5.6.2.2 expect that

      a) the output is now split into several files.

      b) the options to generate an external contents list in a separate
         file are no longer available.

      c) if the contents list is being generated, it is now placed at the
      	 foot of the first document, rather than at the top (unless the
         CONTENTS_LIST preprocessor command is used)

      	 This is usually *before* the first heading (which now starts the
      	 second document), and *after* any document preamble.

      Note:	Where the original contents list is used when splitting files
      		it is possible that not every file will be directly accessible
      		from the contents list, and that the back links to the contents
      		list may not function as expected.  In such cases you can
      		go from the contents list to a major section, and then use
      		the navigation bars to page through to the minor section.


5.6.3 Directory page

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

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

      - A link to the file being converted.  The link will either be the
        converted file's HTML title, or failing that, the filename itself.

      - Links to each of the sections of the converted file as detected
      	by AscToHTM.


5.6.4 Headers, footers and JavaScript

      AscToHTM can be made to add standard header, footers and JavaScript to
      each page generated.  It does this by allowing you to specify include
      files to be copied into the generated HTML.  These include files can
      contain any valid HTML commands.

      The program supports three types of such files :-

      i) Header files.  These contain any HTML you want placing immediately
         after the output's <BODY> tag.

      	 A good example might be a standard header, with a logo and links
      	 back to the home page.

      ii) Footer files.  These contain any HTML you want placing immediately
         before the closing </BODY> tag.

      	
      iii) Script files,  These contain any HTML you want placing inside
      	   the <HEAD> ... </HEAD> portion of the generated file.  Such tags
           are not usually visible.

      	You should place in here any JavaScript you want, although it
      	will be difficult to make this apply to the converted text.


      You can specify include files for the converted files, as well as for any
      directory page (see 5.6.3) that you create.  If you don't specify values
      for the directory page, then it will use the same files as the generated
      files.


$_$_TABLE_WIDTH 60%

6     Using Document Policy files
---------------------------------

      *This chapter has been largely superceded by the [Policy Manual]*

      Document policy files are ordinary text files that list the "policies"
      that AscToHTM should implement when converting your document.  The
      file can have added comment lines (starting with a "!" or "#" character)
      and headings for clarity.

      A summary of the recognised policy lines is given in the [Policy manual].

      In most cases recognised policy lines are identical to those listed in
      the generated policy file (see 4.1).  This is usually a good place to
      start when making your own policy.

      Only those lines that are recognised policies will be acted upon.

      To use a policy file, simply list it on the command line after the
      name of the file being converted (see 4.2.2.2).

      Document policies have two main uses :

      a) To correct any failure of analysis that AscToHTM makes.  Hopefully
         this won't be needed too much as the core analysis engine improves.

      	 Examples include page width, whether or not underlined section
         headings are expected etc.

      b) To tell the program how to produce better HTML end product in ways
         that couldn't possibly be inferred from the original text.

      	 Examples include adding colour and titles to the page, as well
      	 as requesting a large document is split into several pages, and
         a contents list created.

      *Change in version [[TEXT 3.2]]*

      The document sections in this chapter that described the policies in detail
      have been moved to a standalone document called The "[Policy Manual]".
      That document describes the scope, effect, location and default values
      for all policies recognised by the program.


6.1   An example conversion

      This documentation has itself been converted using AscToHTM.  The
      files used were

      - a2hdoco.txt.  This is the text version of the documentation.  The
      	text version is kept as the master copy and updated as required.
        It's then converted to HTML.

      - in_a2hdoco.pol.  This is the policy file used to create the HTML version
      	of this document.  Only those policies that differ from the defaults
        have been added.

      	This policy file "includes" the link dictionary A2HLINKS.DAT.

      - a2hdocoh.inc.  This is the header HTML added as the bottom of each
      	generated HTML page.

      - a2hdocos.inc.  This is the JavaScript HTML added into the <HEAD>...
      	</HEAD> portion of the generated HTML page.  This particular example
        toggles the logo when the mouse is over it (only if you use
      	Netscape [[TEXT 3.0]] or above though).

      - a2hlinks.dat.  This is the link dictionary used for this document
        and is used to add hyperlinks to the main text file.

      - a2hdocof.inc.  This is the footer HTML added as the bottom of each
      	generated HTML page.

      These files are included in the distribution kit as an example
      set of documentation.

      You can, of course, use AscToHTM to convert this doco into whatever
      format, colour etc that you wish.


6.2   Analysis policies

      *Change in version [[TEXT 3.2]]*

      The policy descriptions previously in this section have been moved
      to the [Policy Manual]

6.2.1 Overview ("look for") policies

      *New in version [[TEXT 3.2]]*

      The following analysis policies help give you an overview of what the
      program is looking for, and to enable/disable what is being looked for.

      [[HYPERLINK POLICY,"Attempt TABLE generation"]]
      [[HYPERLINK POLICY,"Look for MAIL and USENET headers"]]
      [[HYPERLINK POLICY,"Look for bullets"]]
      [[HYPERLINK POLICY,"Look for hanging paragraphs"]]
      [[HYPERLINK POLICY,"Look for horizontal rulers"]]
      [[HYPERLINK POLICY,"Minimum ruler length"]]
      [[HYPERLINK POLICY,"Look for indentation"]]
      [[HYPERLINK POLICY,"Look for preformatted text"]]
      [[HYPERLINK POLICY,"Look for quoted text"]]
      [[HYPERLINK POLICY,"Look for short lines"]]
      [[HYPERLINK POLICY,"Look for white space"]]
      [[HYPERLINK POLICY,"Search for definitions]]


6.2.2 General Layout policies

      The following analysis policies help control general layout parameters:-

      [[HYPERLINK POLICY,"Definition Char"]]
      [[HYPERLINK POLICY,"Expect blank lines between paras"]]
      [[HYPERLINK POLICY,"Expect code samples"]]
      [[HYPERLINK POLICY,"Hanging paragraph position(s)"]]
      [[HYPERLINK POLICY,"Indent position(s)"]]
      [[HYPERLINK POLICY,"Keep it simple"]]
      [[HYPERLINK POLICY,"Min chapter size"]]
      [[HYPERLINK POLICY,"New Paragraph Offset"]]
      [[HYPERLINK POLICY,"Page width"]]
      [[HYPERLINK POLICY,"Search for Definitions"]]
      [[HYPERLINK POLICY,"Short line length"]]
      [[HYPERLINK POLICY,"TAB size"]]
      [[HYPERLINK POLICY,"Text Justification"]]


6.2.3 Bullet policies

      AscToHTM has the following bullet point policies that will normally be
      correctly calculated on the analysis pass :-

      [[HYPERLINK POLICY,"Bullet char"]]
      [[HYPERLINK POLICY,"Expect alphabetic bullets"]]
      [[HYPERLINK POLICY,"Expect numbered bullets"]]
      [[HYPERLINK POLICY,"Expect roman numeral bullets"]]

      *New in version [[text 3.2]]*
      [[HYPERLINK POLICY,"Recognise '-' as a bullet"]]
      [[HYPERLINK POLICY,"Recognise 'o' as a bullet"]]

      AscToHTM tries hard not to get confused by the "1", "a" and "I" that
      happen to end up at the start of lines by random.  These could get
      mistaken for bullet points.

6.2.4 Headings

      AscToHTM has the following section heading policies that will normally be
      correctly calculated on the analysis pass :-

      [[HYPERLINK POLICY,"First Section Number"]]
      [[HYPERLINK POLICY,"Expect Numbered Headings"]]
      [[HYPERLINK POLICY,"Expect Underlined Headings"]]
      [[HYPERLINK POLICY,"Expect Capitalised Headings"]]
      [[HYPERLINK POLICY,"Expect Second Word Headings"]]
      [[HYPERLINK POLICY,"Smallest possible section number"]]
      [[HYPERLINK POLICY,"Largest possible section number"]]

      *New in version [[text 3.2]]*
      [[HYPERLINK POLICY,"Preserve underlining of headings"]]

      Section headers are far and away the most complex things the analysis
      pass has to detect, and the most likely area for errors to occur.

      AscToHTM will also document to a policy file the headings it finds.
      This is still to be finalised, but currently has the format

$_$_BEGIN_PRE
      We have 4 recognised headings
          Heading level 0 = "" N at indent 0
          Heading level 1 = "" N.N at indent 0
          Contents level 0 = "" N at indent 0
          Contents level 1 = "" N.N at indent 2
$_$_END_PRE

      AscToHTM will read in such lines from a policy text file, but does not
      yet fully supported editing these via the Windows interface.

      The syntax is explained below, but this will probably change in future
      releases.  You can edit these lines in your policy file, and through
      the policy options in Windows.

      The lines are currently structured as follows

$_$_BEGIN_TABLE
        Line component          Value
        --------------------------------------------
        xxxx                    Either "Heading" or "Contents" according
                                to the part of the policy being described

        Level n                 Level number, starting at 0 for chapters
                                1 for level 1 headings etc.

        "Some_word"             Any text that may be expected to occur before
                                the heading number.  E.g. "Chapter" or "Section"
                                or "[".  The case is unimportant.

        N.Nx                    The style of the heading number.  This will
                                ultimately (in later versions) be read
                                as a series of number/separator pairs.

                                The proposed format is
                                  "N" = number
                                  "i" / "I" = lower/upper case roman numeral
                                with an 'x' at the end signalling that trailing
                                letters may be expected (e.g. 5.6a, 5.6b)

        at indent n             The indentation that this heading is expected
                                at.  This is important in helping to eliminate
                                false candidates.
$_$_END_TABLE

6.2.5 Pre-formatted text

      AscToHTM has the following section heading policies that will normally be
      correctly calculated on the analysis pass :-

      [[HYPERLINK POLICY,"Minimum automatic <PRE> size"]]

      And for tables :-

      [[HYPERLINK POLICY,"Attempt TABLE generation"]]
      [[HYPERLINK POLICY,"Expect sparse tables"]]
      [[HYPERLINK POLICY,"Minimum TABLE column separation"]]


6.2.6 Contents List policies

      There is only one analysis contents policy:-

      [[HYPERLINK POLICY,"Expect contents list"]]

      This is described together with all the output contents list policies
      in 6.3.4.  For more information on content list generation see 5.6.2.


6.3 Output policies

      *Change in version [[TEXT 3.2]]*

      The policy descriptions previously in this section have been moved
      to the [Policy Manual]


6.3.1 Added HTML details

      AscToHTM has the following HTML policies that will only ever take effect
      if supplied in a user policy file :-

      [[HYPERLINK POLICY,"Active Link Colour"]]
      [[HYPERLINK POLICY,"Background Image"]]
      [[HYPERLINK POLICY,"Background Colour"]]
      [[HYPERLINK POLICY,"Document title"]]
      [[HYPERLINK POLICY,"Document keywords"]]
      [[HYPERLINK POLICY,"Document description"]]
      [[HYPERLINK POLICY,"HTML Script file"]]
      [[HYPERLINK POLICY,"HTML header file"]]
      [[HYPERLINK POLICY,"HTML footer file"]]
      [[HYPERLINK POLICY,"Text Colour"]]
      [[HYPERLINK POLICY,"Unvisited Link Colour"]]
      [[HYPERLINK POLICY,"Use first heading as title"]]
      [[HYPERLINK POLICY,"Use first line as title"]]
      [[HYPERLINK POLICY,"Visited Link Colour"]]

      *New in version [[text 3.2]]*
      [[HYPERLINK POLICY,"Suppress all colour markup"]]

      These "polices" allow you to start "adding value" to the HTML generated.
      That is, they allow to specify things that cannot be inferred from the
      original text.

      You can also add HTML to your files by using the HTML preprocessor
      command (see 7.1.4)


6.3.2 Hyperlinks

      AscToHTM has the following hyperlink policies set as defaults :-

      [[HYPERLINK POLICY,"Create hyperlinks"]]
      [[HYPERLINK POLICY,"Create mailto links"]]
      [[HYPERLINK POLICY,"Create NEWS links"]]
      [[HYPERLINK POLICY,"Cross-refs at level"]]
      [[HYPERLINK POLICY,"Only use known groups"]]
      [[HYPERLINK POLICY,"Recognised USENET groups"]]

      Hyperlinks can also be added by using a link dictionary (see 4.3.2.2
      and 4.4.2).


6.3.3 File generation

      AscToHTM has the following HTML policies that will only ever take effect
      if supplied in a user policy file :-

      [[HYPERLINK POLICY,"Add navigation bar"]]
      [[HYPERLINK POLICY,"DOS filename root"]]
      [[HYPERLINK POLICY,"Error reporting level"]]
      [[HYPERLINK POLICY,"Generate diagnostics files"]]
      [[HYPERLINK POLICY,"Input directory"]]
      [[HYPERLINK POLICY,"Min HTML File size"]]
      [[HYPERLINK POLICY,"Minimise HTML file size"]]
      [[HYPERLINK POLICY,"Output directory"]]
      [[HYPERLINK POLICY,"Output file extension"]]
      [[HYPERLINK POLICY,"Output policy file"]]
      [[HYPERLINK POLICY,"Output policy filename"]]
      [[HYPERLINK POLICY,"Split level"]]
      [[HYPERLINK POLICY,"Use DOS filenames"]]
      [[HYPERLINK POLICY,"Use .HTM extension"]]

      *New in version [[text 3.2]]*
      [[HYPERLINK POLICY,"Break up long HTML lines"]]

      These policies specify how your document is divided into one or more HTML
      files, and how those files are to be named and linked together with
      hyperlinks.


6.3.4 Contents

      AscToHTM has the following HTML policies that influence the detection
      and generation of contents lists :-

      [[HYPERLINK POLICY,"Add contents list"]]
      [[HYPERLINK POLICY,"Expect Contents List"]]
      [[HYPERLINK POLICY,"External contents list filename"]]
      [[HYPERLINK POLICY,"Generate external contents file"]]
      [[HYPERLINK POLICY,"Hyperlinks on numbers"]]
      [[HYPERLINK POLICY,"Use any existing contents list"]]

      See also the discussion in 5.6.2


6.3.5 Preprocessor policies

      AscToHTM has the following policies that can be used to influence
      the preprocessor (see [[GOTO Using the preprocessor]]), and hence the HTML output :-

      [[HYPERLINK POLICY,"Include document section(s)"]]
      [[HYPERLINK POLICY,"Use Preprocessor"]]


6.3.6 Style

      AscToHTM has the following "styling" that can be used to influence
      the HTML output :-

      [[HYPERLINK POLICY,"Allow automatic centring"]]
      [[HYPERLINK POLICY,"Allow definitions inside PRE"]]
      [[HYPERLINK POLICY,"Automatic centring tolerance"]]
      [[HYPERLINK POLICY,"Document Style Sheet"]]
      [[HYPERLINK POLICY,"Headings colour"]]
      [[HYPERLINK POLICY,"Highlight Definition Text"]]
      [[HYPERLINK POLICY,"Ignore multiple blank lines"]]
      [[HYPERLINK POLICY,"Largest allowed <Hn> tag"]]
      [[HYPERLINK POLICY,"Smallest allowed <Hn> tag"]]
      [[HYPERLINK POLICY,"Search for emphasis"]]
      [[HYPERLINK POLICY,"Use <DL> markup for defn. paras"]]
      [[HYPERLINK POLICY,"Use <CODE>..</CODE> markup"]]

      *New in version [[text 3.2]]*
      [[HYPERLINK POLICY,"Use <EM> and <STRONG> markup"]]


6.3.7 Table Generation

      AscToHTM has the following policies that can be used to influence
      whether or not AscToHTM will attempt to detect and generate HTML
      tables, and the attributes of any tables generated.

      Tables may be tailored individually by adding pre-processor commands
      to your source text (see 7.4)

      [[HYPERLINK POLICY,"Attempt TABLE generation"]]
      [[HYPERLINK POLICY,"Convert TABLE X-refs to links"]]
      [[HYPERLINK POLICY,"Default TABLE border size"]]
      [[HYPERLINK POLICY,"Default TABLE header rows"]]
      [[HYPERLINK POLICY,"Default TABLE header cols"]]
      [[HYPERLINK POLICY,"Default TABLE cell spacing"]]
      [[HYPERLINK POLICY,"Default TABLE cell padding"]]
      [[HYPERLINK POLICY,"Default TABLE colour"]]
      [[HYPERLINK POLICY,"Default TABLE border colour"]]
      [[HYPERLINK POLICY,"Default TABLE caption"]]

      *New in version [[text 3.2]]*
      [[HYPERLINK POLICY,"GOTO Colour data rows"]]
      [[HYPERLINK POLICY,"Default TABLE even row colour"]]
      [[HYPERLINK POLICY,"Default TABLE odd row colour"]]
      [[HYPERLINK POLICY,"Default TABLE cell alignment"]]


6.3.8 Link Dictionary

      Link definitions appear as follows :-


        [Link Dictionary]
        -----------------
        Link definition       :  "a2hdoco.txt" = "Source text" + "/~jaf/A2HDOCO


      That is, the text to be matched, the text to be used in its placed as
      the highlighted text, and the URL this link is to point to (in this case
      a relative URL).

      See the discussions in 4.3.2.2 and 4.4.2.

6.3.9 Directory Page

      AscToHTM has the following policies that can be used to influence
      whether or not AscToHTM will attempt to generate a Directory page
      for the files being converted.  This is really only appropriate when
      converting more that one file at once (see 4.3.3)

      The Directory Page will consist of entries for each file being
      converted (in order of conversion), and can have hyperlinks to the
      files, and to recognised headings in the files.  This makes it suitable
      for use as a master index to a set of files converted in a single
      directory.

      [[HYPERLINK POLICY,"Make Directory"]]

      [[HYPERLINK POLICY,"Directory filename"]]
      [[HYPERLINK POLICY,"Directory title"]]
      [[HYPERLINK POLICY,"Directory keywords"]]
      [[HYPERLINK POLICY,"Directory description"]]
      [[HYPERLINK POLICY,"Directory return hyperlink text"]]
      [[HYPERLINK POLICY,"Directory script file"]]
      [[HYPERLINK POLICY,"Directory header file"]]
      [[HYPERLINK POLICY,"Directory footer file"]]
      [[HYPERLINK POLICY,"Indent headings in Directory"]]
      [[HYPERLINK POLICY,"Show file titles in Directory"]]


6.4   Saving and loading policy files

      This section has been copied into the Policy manual section on
      [[HYPERLINK URL,"policy_manual_3.html#Section_3.1","placing policies in a file"]]

6.4.1 Overview

      AscToHTM allows you to save policies to file so that you can later
      reload them.  This allows you to easily define different ways
      of doing conversions, either for different types of files, or to
      produce different types of output.

      The policy files have a .pol extension by default, and are simple
      text files, with one policy on each line.  You can, if you wish,
      edit these policies in a text editor... this is sometimes easier
      that using all the dialogs in the Windows version.

      When editing policies, it is important not to change the key phrase
      (the bit before the ":" character), as this needs to be matched exactly
      by AscToHTM.

      For best results, it is advisable to put in your policy file only
      those policies you want to fix.  This leaves AscToHTM to calculate
      document-by-document policies that suit the files being converted.

      Note:	Avoid using "full" policy file for your conversions.  Such
      		files prevent the program from adjusting to each source
      		file, often leading to unwanted results.


6.4.2 Generating policy files for your document

      The normal way to create a policy file is by setting options and them
      saving them using the "save policy file" dialog.  This will offer you
      the choice of creating a partial policy file or a full policy file
      (see 6.4.2.1 and 6.4.2.2).

      Alternatively, you can set the [[HYPERLINK POLICY,"Output policy file"]] policy
      which will generate a full policy file resulting from the analysis
      of the converted document.

      Once a file is generated you can either edit them in a text editor -
      deleting policies that are of little interest to you, and editing those
      that are - or reload them into the program, change them and save them
      again.


6.4.2.1 Partial policy files

      Partial policy files are files which have values for some, not all,
      policies.

      These are recommended, because the unstated policies can be set by
      AscToHTM, allowing it to adapt to the details of the document being
      concerned.

      For example, you should only set the indentation policy if you *know*
      what indents you are using, or if you want to override those calculated
      by AscToHTM.  Normally it is best to omit this policy, and allow
      AscToHTM to work it out itself.

      When you save a policy file from inside AscToHTM, a partial policy file
      will contain

      	- all policies loaded from the current policy file (if any)
      	- all policies changed in AscToHTM during the current session (if any)


6.4.2.2 Full policy files

      A "full" policy file contains a value for every possible policy.
      Such files are usually only useful for documentation and analysis
      reasons, and should almost never be expected to be reloaded as input
      into a conversion, as this would totally fix the conversion details.


6.4.3 Naming policy files

      Whenever the [[HYPERLINK POLICY,"Output policy file"]] policy is set the
      generated "full" policy file is usually called

      	<filename>.pol

      where <filename> is the name of the file being created.  When this
      happens any existing file of that name will be overwritten.

      For this reason we *strongly* advise you adopt a naming convention of
      the form

      	in_<filename>.pol or i<filename>.pol

      or place your input policies in a different directory and ensure they
      are backed up.


$_$_TABLE_WIDTH

7     Using the preprocessor
----------------------------

      The preprocessor was introduced in version V1.05 to allow users more
      flexibility in the HTML they generate.  As such it moves AscToHTM
      towards being a HTML authoring tool, as opposed to a simple text
      conversion or migration tool.  Although this wasn't AscToHTM's
      original intention, it is increasingly the use to which AscToHTM's
      "power users" are putting it.  As such this is a rapidly growing
      area of functionally within the product.

      The preprocessor looks for lines that begin with a special character
      sequence.  Presently this is "$_$_", but this will become configurable
      in later versions.

      Preprocessor lines are not normally output to the HTML generated.
      Instead they are used to modify AscToHTM's behaviour in a number of ways.


7.1   Marking up sections of text

      The pre-processor can be used to mark sections in your document so that
      AscToHTM will process them as you wish.

      Note:	AscToHTM does attempt to spot much user-formatted text
      		automatically, but this is a difficult area and prone to
      		error.  Hence the use of these directives can reduce the
      		error rate on such occasions.


7.1.1 User SECTIONS

      This directive is used to divide the document up into named section
      types.  Section type names can be repeated through the document, and
      by default text is assumed to belong to a section called "all",
      indicating that this text is always copied to the output file.

      Section type names must contain no white space, but may contain underscores.

      This has no effect unless the user supplies a policy file indicating
      that they wish to select only certain section types for output.

      For example, if the text document looks like this

$_$_BEGIN_PRE
      		Some text that'll always get copied, because it is in an
      		"all" section type by default.

      	$_$_SECTION Private

      		Some text that will be copied either when the preprocessor
      		is switched off, or when the user's policy file indicates
      		that "private" section types are to be included.

      	$_$_SECTION Other

      		Likewise, this is an "other" section type.

      	$_$_SECTION Private

      		And here's some more "private" text.

      	$_$_SECTION all

      		Some text that will always get copied because it is explicitly
      		in an "all" section type.
$_$_END_PRE

      If the user then supplies a document policy file which includes the
      lines (see 6.3.5)

      	[Preprocessor]
      	--------------
      	Use Preprocessor             : Yes

      then the two section types marked "private" won't be copied into the
      converted file unless the line


      	Include document section     :   Private


      is added to the policy file.  Similarly with the "other" section.

      Note_1:	Strictly speaking the "use preprocessor" line above isn't
      		needed as this is set to "yes" by default.  This means that
      		any $_$_SECTION lines will cause text to be omitted unless
      		you supply an appropriate policy file.

      Note_2:	Be aware that any sections omitted are also omitted from
      		the analysis pass.  This may have unexpected results as
      		AscToHTM responds only to the input text that is to be
      		included in the output.


7.1.2 TABLE and DELIMITED_TABLE sections

      The BEGIN_TABLE ... END_TABLE directives are used to bracket a
      table in the source text.  AscToHTM will then attempt to analyse this
      table as best it can.

      This is explained more in the [AscToTab Doco].

      Inside this section you can use other TABLE pre-processor commands
      to tailor the HTML generated (see 7.4).

      Similarly the BEGIN_DELIMITED_TABLE ... END_DELIMITED_TABLE directives
      can be used to delimit a series of tab-delimited data values that should
      be interpreted as a table (e.g. data originally exported from a
      spreadsheet such as Excel)


      The presence of these directives overrides any value set in the
      [[HYPERLINK POLICY,"Attempt table generation"]] policy


7.1.3 CONTENT sections

      The BEGIN_CONTENTS ... END_CONTENTS directives are used to bracket a
      contents list in the source
      document.  AscToHTM will attempt to automatically detect the presence
      and location of any contents list in the document, but the algorithm
      can be problematic.

      Use this markup only when the document contains a contents list that
      AscToHTM fails to detect correctly.

      See the discussion in 5.6.2.


7.1.4 HTML sections

$_$_BEGIN_HTML
      <IMG SRC="a2hdoco1.jpg" BORDER=0 ALIGN=RIGHT
       HEIGHT=160 WIDTH=160 ALT="AscToHTM">
$_$_END_HTML

      The BEGIN_HTML ... END_HTML directives are used to bracket actual
      HTML in the source document.
      The bracketed HTML will be transcribed to the output file unconverted.

      This device will allow you to embed images, tables and other HTML
      constructs not normally generated by AscToHTM.

      This is how the image to the right has been added.

      If you simply wish to insert a single line of HTML, the HTML_LINE
      command (see 7.3.2) offers a more compact form.

      For in-line HTML use the HTML in-line tag (see 8.2.7)


7.1.5 CODE sections

      The BEGIN_CODE ... END_CODE directives are used to bracket a piece
      of sample code in the source text.

      AscToHTM will either render this in <PRE> ... </PRE> markup or
      <CODE> ... </CODE> markup (see the discussion about the
      policy [[HYPERLINK POLICY,"Use <CODE>..</CODE> markup"]] to see why the former
      is used as default).


7.1.6 DIAGRAM sections

      The BEGIN_DIAGRAM ... END_DIAGRAM directives are used to bracket a piece
      of Ascii art or text diagram in the source text.

      AscToHTM will render this in <PRE> ... </PRE> markup.


7.1.7 PRE (pre-formatted text) sections

      The BEGIN_PRE ... END_PRE directives are largely replaced by the
      TABLE, CODE and DIAGRAM directives.  They are maintained for backwards
      compatability, and have the same effect as the DIAGRAM commands
      (see 7.1.6).


7.1.8 IGNORE sections

      *New in version [[TEXT 3.2]]*

      The BEGIN_IGNORE ... END_IGNORE directive delimit a section of text that
      should be ignored.  This could be used to place comments in the source
      file, or to mark text that shouldn't be converted when the file is being
      generated by some third party software package.


7.2   Commands that influence the <HEAD>..</HEAD> of a file

7.2.1 The TITLE command

      This directive allows you to specify the <TITLE>...</TITLE> to be inserted
      into the <HEAD> section of the output page.  This title will appear in
      the browser's frame title whenever the page is viewed, and will be the
      text shown in your browser's history.

      The presence of a TITLE command overrides any title specified in
      a policy file (see 6.3.1).

      To fully understand how titles are calculated, see the discussion in 5.6.1


7.2.2 The DESCRIPTION command

      This directive allows you to specify a description of your document
      that is added to a META tag inserted into the <HEAD> section of the
      output page(s) as follows :-

      	<META NAME="description" CONTENT="your description">

      This tag is often used by search engines (e.g. AltaVista) as a brief
      description of the contents of your page.  If omitted the first few
      lines may be shown instead, which is often less satisfactory.

      The presence of a DESCRIPTION pre-processor command overrides any
      description specified via a [[HYPERLINK POLICY,"Document description"]] policy line.


7.2.3 The KEYWORDS command

      This directive allows you to specify keywords that are added to a
      META tag inserted into the <HEAD> section of the output
      page(s) as follows :-

      	<META NAME="keywords" CONTENT="your list or keywords">

      This tag is often used by search engines when indexing your HTML page.
      You should add here any relevant keywords possibly not contained in
      the text itself.

      The presence of a KEYWORDS pre-processor command overrides any keywords
      specified via a [[HYPERLINK POLICY,"Document keywords"]] policy line.


7.2.4 The STYLE_SHEET command

      This directive allows you to specify the URL of a style sheet file,
      usually with a .css extension.  Style sheet files are a new HTML feature
      that allow you specify fonts and colours to be applied to your document.

      The resulting HTML is inserted into the <HEAD> section of the output
      page(s) as follows :-

      	<LINK REL="STYLESHEET" HREF="URL" TYPE="text/css">

      The presence of a STYLE_SHEET pre-processor command will overrides any
      style sheet specified via a [[HYPERLINK POLICY,"Document style sheet"]] policy
      line.


7.3   One line pre-processor commands

7.3.1 The INCLUDE command

      This directive allows you to specify the name of a source file to be
      included at this point.  This is useful if you wish some standard text
      inserted into many related documents, or into the same documents at
      many locations.

      The included file will be treated as though it were part of the original
      file during both the analysis and output passes.

      The include will fail is the fail cannot be found, and a test for
      recursive include files will be made.


7.3.2 The HTML_LINE command

      This directive allows you to embed a single line of HTML in your source
      file.  The rest of the line is copied across faithfully to the output
      file.

      Essentially this offers the functionality as the HTML section commands
      (see 7.1.4), but in a more compact form.


7.3.3 The CONTENTS_LIST and NAVIGATION_BAR commands

      *New in version [[TEXT 3.2]]*

      These command allow you to add navigational aids to your document.

      The CONTENTS_LIST command inserts a contents list at the present
      location.  When this is present the normal generation of a contents
      list at the top of the document is suppressed.

      The CONTENTS_LIST directive may also be supplied as an in-line tag
      (see 8.2.3).  The same user arguments apply.

      The NAVIGATION_BAR command inserts a navigation bar that takes to to
      the next/previous and contents files.  This will only be generated when
      you have selected to split your file by setting the
      [[HYPERLINK POLICY,"Split level"]] policy.


7.3.4 The LINERULE command

      *New in version [[TEXT 3.2]]*

      The LINERULE directive allows you to insert a horizontal line into
      your text.  It has the syntax:-

        LINERULE <length>,<thickness>

      where

        <length>          length of line in pixels/pts
        <thickness>       thickness of line in pixels/pts


7.3.5 The TOC (table of contents) command

      *New in version [[TEXT 3.2]]*

      The TOC directive marks a point in the file that will receive an
      anchor point, and then be linked to from any generated contents lists.

      This can be useful to index non-headings like key diagrams and tables.

      The syntax is:

            TOC <level>, <link name>, <display text>

      where,

$_$_BEGIN_TABLE
      <level>           the level in the TOC, starting with 1 being the most
                        significant, equivalent to "chapter"

      <link name>       The (usually short) name by which this linkpoint may
                        be known.  This is the value used to create an ANCHOR
                        point, and which may be referenced in any
                        HYPERLINK tag.

      <display text>    The text to be shown in the TOC.  This will also be
                        used to generate an ANCHOR name, and may be used in
                        a TOC type HYPERLINK Tag, although this is marginally
                        less portable than referencing the link name

                        If omitted, defaults to the link name, and only one
                 	ANCHOR is created.
$_$_END_TABLE

      See also the section on HYPERLINK tags (8.2.9).


7.4   The TABLE commands

      These directives are used to tailor the HTML generated in any tables
      AscToHTM creates.  They are placed either

      a) *At the top of the file*

      	Directives placed here become defaults for the whole file, and will
        replace any policies that have been set (see 6.3.7)

      b) *Inside a BEGIN_TABLE ... END_TABLE section*

      	Directives placed here will apply only to the table marked up by
      	these commands (see 7.1.2).

      The table commands are described (naturally enough) in the following
      table.

$_$_CHANGE_POLICY Convert TABLE X-refs to links : Yes
$_$_BEGIN_TABLE
Directive			Value    Effect
--------------------------------------------------------------------------------
TABLE_BGCOLOR           	Colour   Colour of background

TABLE_BORDER            	Number   Size of border.  0 = None

TABLE_BORDERCOLOR       	Colour   Colour of border

TABLE_CAPTION			Text     Table caption.  Added centred at
                                         the top

TABLE_CELL_ALIGN		Align	 Specifies the default alignment of
      					 cells.  Left, right or center

TABLE_CELLSPACING       	Number   Spacing between cells.

TABLE_CELLPADDING       	Number   Padding inside each cell

TABLE_COLOUR_ROWS or		(none)	 If present this specifies that the
TABLE_COLOR_ROWS			 odd and even rows of the table should
      					 be coloured differently.  See also the
      					 [[HYPERLINK POLICY,"Colour data rows"]] policy.

TABLE_CONVERT_XREFS             (none)   If present, indicates that any section
                                         cross-references in the table may
                                         be converted to hyperlinks
                                         (see also the policy line
					 [[HYPERLINK POLICY,"Convert TABLE X-refs to links"]])

TABLE_EVEN_COLOUR or		Colour   When data rows are to be coloured
TABLE_EVEN_COLOR			 this specifies the colour of the
      					 even numbered rows.

TABLE_HEADER_ROWS       	Number   Number of header rows.  These
                                         will be placed in <TH> .. </TH> markup

TABLE_HEADER_COLS               Number   Number of header columns.
                                         These will be marked up in bold

TABLE_MAY_BE_SPARSE             (none)   If present, indicates that the TABLE
                                         may be sparse (see also the policy
      					 [[HYPERLINK POLICY,"Expect sparse tables"]])

TABLE_MIN_COLUMN_SEPARATION     Number   Number of spaces to be taken as a
                                         column separator when analysing the
                                         table (see also the policy
      					 [[HYPERLINK POLICY,"Minimum TABLE column separation"]]).

TABLE_ODD_COLOUR or		Colour   When data rows are to be coloured
TABLE_ODD_COLOR				 this specifies the colour of the
      					 odd numbered rows.

TABLE_WIDTH             	Text     The width of the table (see also the
					 policy [[HYPERLINK POLICY,"Default TABLE width"]])

$_$_END_TABLE

      Colours must be HTML acceptable values which will placed in the
      various attributes of the <BODY> tag and other.

      You can enter any value acceptable to HTML.  Normally a value is
      expressed as a "#" and a 6-digit hexadecimal value in the range #000000
      (black) to #FFFFFF (white), but certain colours such as "white",
      "blue", "red" etc may also be recognised by HTML.  AscToHTM simply
      transcribes your value into the output file.

      A value of "none" signals the defaults are to be used.  By default
      AscToHTM changes the background colour to be white (the true HTML
      default is a light gray whose value is "#C0C0C0").


7.5   The CHANGE_POLICY command

      NOTE: 	This feature has the potential to cause mayhem, and as such is offered
      		to users on a "as is" basis.  That is, we offer no support for getting
      		this feature to have the effect a user may desire.

      This directive allows you change a particular policy in part of a
      document.  This is a potentially powerful feature, allowing you to tailor
      the conversion of your file *in different sections of that file*, or
      to embed the policy particular to a file in commands inserted at the top
      of the file itself.

      The syntax of the command line is

      	$_$_CHANGE_POLICY <Policy Line>

      where <Policy_line> is a policy line as it would appear in a policy file,
      and (usually) as it appears in the [Policy Manual].

      For example the following would all be valid directives

$_$_BEGIN_PRE
      	$_$_CHANGE_POLICY Background Colour : red
      	$_$_CHANGE_POLICY Ignore multiple blank lines : Yes
$_$_END_PRE

      Although how and when they would take affect will depend on the policy.

      For example, the background colour would only take effect if splitting
      the file up, and only on the next file generation.  This works, BTW, so
      if anyone wants to split a file into many pages, all different colours,
      then be my guest.

      There are a *many* caveats to this behaviour :-

      - *Not all policies are supported*

      	Not all policies may be changed in this way.  In particular policies
      	that open other policy files are not supported.  Even if a policy
      	if "changed", it does not follow that changing the policy will have
      	an effect.

      - *analysis policies*

      	It is unlikely that this feature can be sensibly used to influence the
      	analysis of file, other than when placed at the top of the file only.
      	If such a manner it is simply an alternative to using a separate
      	policy file.

      - *output policies*

      	Output policies are referenced at different times.  Only those that are
      	referenced *after* the line is read from the source file may be
      	influenced, thus things like output file name may have no effect.

      - *toggleable policies*

      	Not all policies once changed, can be changed back.  This is
      	particularly of policies that contain values to be added to a list.
      	This is an issue that may be addresses in later versions.
      	
      - *unpredictable behaviour*

      	Messing with policies can cause unpredictable behaviour.  For example
      	if you alter the section splitting parameters, then the chances of a
      	section cross-reference elsewhere in the document being calculated
      	as a correct hyperlink diminishes.

      	*That's why this feature is offered UNSUPPORTED*

      - *readahead buffer*

      	To further complicate matters, AscToHTM uses a readahead, write behind
      	buffer which means that you may need to experiment with the placing
      	of your policy change to within 40 lines (the size of the buffer).

      	This problem is alleviated since version [[TEXT 3.2]].


8     Using in-line tags
------------------------

*New in version [[TEXT 3.2]]*

In-line tags are introduced in version [[TEXT 3.2]].  They allow you to place
special codes in your source text to achieve effects that couldn't be done
by converting plain text alone.  As such they greatly enhance AscToHTM's
ability to be used as a web authoring tool.

8.1 Format of inline tags

      In-line tags are introduced in version [[TEXT 3.2]].  In-line tags are an extension of
      the preprocessor tags introduced in earlier versions.  As the name
      implies, in-line tags may be placed "in line" with the source tag, giving
      greater flexibility for their use.

      In-line tags are signified by the start and end delimiters "[[OT]]" and
      "[[CT]]", for example :-

      	[[OT]]HTML_COMMENT this will become an HTML comment[[CT]]

      The whole tag must be contained within a single line of the source file,
      that is there cannot be any newline characters in the middle of a tag.
      You can have as many tags as you like on any given line, but they may
      not be nested.

      In-line tags form a large part of what will be available in version
      [[TEXT 4.0]], at which time they will be fully documented.  In the
      meantime a summary of some of the in-line tags available is given in 8.2.


8.2 Summary of in-line tags

      *New in version [[TEXT 3.2]]*

      This is a brief overview of some of the more useful in-line tags.  A
      fuller description of using in-line tags will br produced when
      version [[TEXT 4.0]] is released.


8.2.1 BR

      *New in version [[TEXT 3.2]]*

      Inserts a <BR> tag


8.2.2 COLOUR <value>

      *New in version [[TEXT 3.2]]*

      [[OT]]COLOUR <value>[[CT]]

      Change text colour.  If <value> is omitted, text reverts to black.


8.2.3 CONTENTS_LIST

      *New in version [[TEXT 3.2]]*

      [[OT]]CONTENTS_LIST <number levels> <Style>[[CT]]

      Inserts a contents list with the specified number of heading levels
      (1=chapter, 2=main sections...)

      A <style> value of "1" gives a traditional list, whilst "2" generates
      a navigation bar (best used with level set to 1)

      This may also be set as a directive $_$_CONTENTS_LIST (see 7.3.3).


8.2.4 ENTITY

      *New in version [[TEXT 3.2]]*

      [[OT]]ENTITY <HTML entity number>[[CT]]

      Inserts a HTML entity of the form &#nnn;  The entity number must be
      valid.  Note not all entities are supported by all browsers


8.2.5 FONT

      *New in version [[TEXT 3.2]]*

      [[OT]]FONT 0,<list of fonts>,<font size>[[CT]]

      Changes the current font.  When supplying a list of fonts it is a
      good idea to ensure you include a font commonly available.


8.2.6 GOTO

      *New in version [[TEXT 3.2]]*

      [[OT]]GOTO <Section title>[[CT]]

      Inserts a hyperlink to the named section title within the current
      document.  For example

      		[GOTO Use the preprocessor]

      becomes

      		[[GOTO Using the preprocessor]]


8.2.7 HTML

      *New in version [[TEXT 3.2]]*

      [[OT]]HTML <embedded HTML>[[CT]]

      Inserts the embedded HTML at the current location.  This can be
      useful, although care must taken that the HTML that is inserted
      fits in with that generated by the program itself.


8.2.8 HTML_COMMENT

      *New in version [[TEXT 3.2]]*

      [[OT]]HTML_COMMENT <comment text>[[CT]]

      Inserts a HTML comment containing the supplied text.


8.2.9 HYPERLINK

      *New in version [[TEXT 3.2]]*

      [[OT]]HYPERLINK URL,"<url>","<display text>"[[CT]] or [[BR]]
      [[OT]]HYPERLINK LINK,"<link name>","<display text>"[[CT]]

      Inserts a hyperlink.  When "URL" is requested, you should supply
      the URL to be linked to, and the display text, both in quotes.

      When "LINK" is requested, a hyperlink to a named LINKPOINT (see below)
      will be added, and you should supply the LINKPOINT name and the
      hyperlink display text, both in quotes.

      For example

          [[OT]]HYPERLINK URL,"[[TEXT http://www.jafsoft.com/]]","JafSoft Limited"[[CT]] and [[BR]]
          [[OT]]HYPERLINK LINK,"Definitions","section on definitions"[[CT]]

      becomes

          [[HYPERLINK URL,"http://www.jafsoft.com/","JafSoft Limited"]] and[[BR]]
          [[HYPERLINK LINK,"Definitions","section on definitions"]]


8.2.10 LINKPOINT

      *New in version [[TEXT 3.2]]*

      [[OT]]LINKPOINT "<link name>"[[CT]]

      Inserts a named anchor point into the HTML.  This can be used to
      create a known anchor point that is available for use in HYPERLINK 	
      tags (see above 8.2.9), or in any other files that you want to
      create.


8.2.11 NB or SPACES

      *New in version [[TEXT 3.2]]*

      [[OT]]NB <Number of spaces>[[CT]]
      [[OT]]SPACES <Number of spaces>[[CT]]

      Inserts the specified number of spaces, or non-breaking spaces.

      Since both tags are currently implemented using &nbsp; there is
      currently no difference between the two.


8.2.12 SOURCE_FILE

      *New in version [[TEXT 3.2]]*

      [[OT]]SOURCE_FILE <display text>[[CT]]

      Inserts a hyperlink to the text file used to create the HTML.  If
      the display text is omitted the string "source file" will be used.
      The link generated assumes the text file will be placed in the same
      directory as the HTML file.

      This can be useful where you want to make both text and HTML versions
      of a document available.


8.2.13 SUPER and SUB

      *New in version [[TEXT 3.2]]*

      [[OT]]SUPER <superscript text>[[CT]] and
      [[OT]]SUB <subscript text>[[CT]]

      Places the supplied text in [[SUPER superscript]] or [[SUB subscripts]]


8.2.14 TEXT

      *New in version [[TEXT 3.2]]*

      [[OT]]TEXT <protected text>[[CT]]

      Protects text from various AscToHTM conversions.  For example a section
      number line any URL like :-

      	section [[TEXT 3.1]] and [[TEXT http://www.jafsoft.com/]]

      would normally be turned into hyperlinks like this:-

      	section 3.1 and http://www.jafsoft.com/


8.2.15 TIMESTAMP

      *New in version [[TEXT 3.2]]*

      Inserts a timestamp (currently a date) indicating when the HTML
      file was converted from text.  For example :-

      	This file was last converted on [[OT]]Timestamp[[CT]]

      becomes

      	This file was last converted on [[Timestamp]]



9     Purchasing AscToHTM, and contacts on the web
--------------------------------------------------

9.1   Purchasing AscToHTM

9.1.1 Why should I purchase AscToHTM?

      You need a reason?  What kind of a skinflint are you?

      Oh well... here are some reasons to visit the [Reg location] :-

      - You'll get a warm glow from supporting the author financially.

      Not enough eh?  Okay...

      - You'll get support from the author, especially in your early days as
      	a new user.

      - You'll be notified of any [upgrades].  To date all upgrades have been
        *free* to _registered_ users.  This means people who paid last year's
      	price are getting this years software at a discount (plus they've
        had a year's use).

      	You can read details of the 10 or more upgrades made over 2-3 years
        in the [[GOTO "Change History"]].  Every single one of these has
      	been free to those who have registered to date.

      - You'll be able to ask the author for new features.  You won't always
        get them, but you'd be *amazed* at how much of the functionality arose
        directly from _registered_ users party requests.

      Finally...

      - No nag lines at top and bottom of each page, and no nag screen when
        you start the program up.

      - All limitations on the program (file size etc) are removed


9.1.2 What happens if I don't register the shareware version of AscToHTM?

      Originally I wanted to produce a fully-featured, but time-limited
      shareware version.  However, for various reasons we've had to move
      to move to producing a largely-featured version with a 30 day time limit.

      Sorry 'bout that.

      At present the shareware version of the program comes with an expiry
      date (usually 30 days after installation).  Each time the program runs
      it will tell you how may days left you have.  During this period the
      program inserts a one line reminder to register at the top and bottom
      of each HTML page generated.

      This line is easily deleted from the output source file, but we expect
      this to become quite tedious if the program is used repeatedly,
      particularly when large documents are split into a number of small
      files, or a large number of files are being converted.  *Some people have
      actually put such pages on the web*.

      There are other limitations of the shareware version :-

      - If you don't register, it will cease to function properly after 30
        days.  Specifically after 30 days any conversions will convert all
        your text to random case.  This will still allow you to evaluate the
        software, but the resulting HTML will be of little use to you.

      - In the shareware version you're limited to only the first 500 lines of
        any source file.  After 500 lines a warning is placed in the
        output, and all subsequent lines are converted to upper case.  This
      	allows you to gain an impression of what the HTML will look like for
      	evaluation purposes.

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

      - Certain other policies are not supported in the shareware version.

      I don't like limiting the software, but there you go.


9.1.3 Can't I get something for nothing?

      Only if you fall into either of the following two categories:

      - You're an FAQ maintainer.  FAQ maintainers add a lot of value to
        the Internet.  As a little "thank you" I'm making this software
        free to anyone who maintains an FAQ.  See the [Reg location] for
        more details.

      - VMS users.  The software is largely developed and tested under VMS.
        Although the VMS version doesn't have the windowed interface, but
        does share the underlying conversion software.

        *<SOAPBOX>*
        We VMS users pay too much for software (that's when we can get it), so
        the VMS version of this software is made available for free.
        *</SOAPBOX>*

        If you really want a free copy, buy an OpenVMS system :)  If you find
      	any for less than $40, let me know :)


9.1.4 I'm convinced.  How to I purchase AscToHTM?

      First we recommend you try out the product to convince yourself that
      it meets your needs.

      You've done that right?

      Okay, visit the [Reg location] and follow the instructions there.
      You can buy AscToHTM online using credit cards, or via snail mail.
      Credit cards are processed by a third party who contact us once payment
      is cleared.

      If you experience any problems registering email sales@jafsoft.com with
      details.  Currently most registrations result in an email from Jaf
      anyway.


9.2   Contacts on the Web

9.2.1 The home page

      The AscToHTM [home page] is hosted on the [JafSoft] web site.

      If you have problems locating the home page and suspect it has moved,
      go to [AltaVista] and enter

      		+"John A Fotheringham" +AscToHTM

      to locate any new home page.


9.2.2 E-mail

      E-mail any feedback to info@jafsoft.com.  Sadly, we cannot guarantee any
      replies. OTOH, no-one who has ever emailed us has ever waited more than
      a day or so for a response (no holidays, you see :)


9.2.3 Support

      A limited amount of support is available to registered users by emailing
      support@jafsoft.com.  Any enquiries should be directed to the same
      address.

      Sadly, we cannot guarantee any replies, though we do try to be helpful.
      Priority is given to people who have registered copies.

      Recently a [FAQ] has been created.  Although not complete, it may help
      to answer some of the commoner questions people have.


10     Known problems
---------------------

      We listen to all suggestions, and indeed many of the features added
      have been in direct response to customer feedback.  (You couldn't
      expect us to *invent* all this stuff on our own now, could you? :)


10.1  Bug reports

      _Registered_ users are free to make bug reports or suggestions for
      enhancements to support@jafsoft.com.  We try to fix bugs ASAP, and to date
      have usually shipped fixes to specific problems within 72 hours, but we
      can't promise this response time.

      We used to maintain a bug list, but we prefer spending the time fixing
      them rather than documenting them.


10.2  Features

      All good software has features (ask Microsoft).

      - Links in the link dictionary that have some common text may get
        confused.  The problem generally is that having put some HTML
      	markup into your line, it becomes hard not to search the contents
      	of that markup subsequently.

      	This is my problem not yours.  Unless it catches you out when,
      	of course, it becomes your problem, not mine.

      - Bullet characters inside section headings used to cause confusion.

      The following are consequences of how the program works, and may
      take longer to "fix"

      - The program currently assumes a structure of contents list and/or
      	main body.  It doesn't (yet) cope with Appendices.  Nor does it
      	cope with several sections all with their own numbering systems.

      - Certain algorithms put a <BR> on the end of the line.  Where these
      	algorithms "misfire" you may find unexpected breaks in large paragraphs.

      	Over time more of these will be configurable via the document policy,
      	but originally we tried to avoid the need for such micro-control.


10.3   Coming soon... or not.

      An on-line [wishlist] is now maintained.  However, it's not kept
      wonderfully up to date, and a *lot* of features have fast-tracked their
      way into the software without ever being mentioned on the list.

      Many, many features have been added in direct response to (_registered_)
      users requests.  Many, thanks to all those who've come up with
      suggestions and feedback (you all know who you are).



11    Change History
--------------------

11.1  Version 1.01 (April '97)

      New functions

      - Added the /CONTENTS qualifiers (see 4.2.2.2).
      - Added the /SIMPLE qualifier (see 4.2.2.10).

11.2  Version 1.04 (early July '97)

11.2.1 Bug fixes

      - Fixed lots of memory leaks

      - Improved cross-reference detection.  These are now range checked
        against the observed section numbers.  This will reduce the likelyhood
        of DirectX 3.0 and Windows 95 becoming links to chapters 3 and 95.

      - Contents list generation for documents with chapters and no subsections
        now works.

      - Improved Contents list detection.

      - Fixed bug that caused links to underlined or capitalised heading
        with very long names to sometimes fail.

11.2.2 New functions

      - Added policy [[HYPERLINK POLICY,"Minimum automatic <PRE> size"]].  This
	replaces the policy "Allow automatic 1-line <PRE>"

      - Added policies [[HYPERLINK POLICY,"Largest allowed <Hn> tag"]] and
	[[HYPERLINK POLICY,"Smallest allowed <Hn> tag"]] to allow control over generated heading
	sizes.

      - Added policy [[HYPERLINK POLICY,"Short line length"]]

      - Added Batch processing to allow multiple files to be converted at
        the same time. (see 4.3.3.2)

11.2.3 Other changes

      - Created a 16-bit DOS version

      - VMS version now available as freeware.

      - Added "SendTo" tips for Windows 95/NT users section to the
        documentation (see 4.4.4)



11.3 Version 1.05 (late July '97)

11.3.1 Bug fixes

      - fixed some errors that occur when directory paths are included
        in the filenames.  Probably still more changes required in this area,
      	particularly with a view to supporting multiple file drag'n'drop
      	under Windows.

      - improved detection of pre-formatted regions.

11.3.2 New functions

      - Added an [[HYPERLINK POLICY,"Output directory"]] policy.  This allows
	redirection of output to a directory different from that containing
	the source files.

	Note:	This functionality may not be available in
		the shareware version of the software.

      - Added an [[HYPERLINK POLICY,"Output policy"]] policy.  This allows the
	suppression of output policy files where not wanted.

      - Added a [[HYPERLINK POLICY,"Expect code samples"]] policy. This helps in
        technical documents that include samples of C code.

      - Added preprocessor support to allow variant documents to be
      	produced (see 6.3.5 and [[GOTO Using the preprocessor]])

11.3.3 Other changes

      - Policies now accept "Yes/No" as well as "True/False".  "Yes/No" is
	now the default when outputting policies.

      - shareware version now limited to processing the first 500 lines only.

      - Lines with email addresses no longer have <BR>'s forced on the end.
        Lines with http, ftp and news links still do.  This will become
        fully configurable in later versions.


11.4 Version 1.1 (August '97)

11.4.1 Bug fixes

      - Several hyperlink parsing errors fixed.  Previously there were
        problems with punctuation around links, email addresses with
        protocols (e.g. MX%"info@jafsoft.com") and newsgroups with the
        word "news:" in front e.g. news:uk.jobs.

      - improved output of pre-formatted text.  "<" characters were getting
        confused, and the pre-formatted lines were being broken in two.

11.4.2 New functions

      - Added a [[HYPERLINK POLICY,"Only use known groups"]] policy to improve accuracy
      	of newsgroup hyperlink detection.

      - Added more document colour policies

      - Added a /POLICY and [[HYPERLINK POLICY,"Output Policy file"]] option (see
	4.2.2.8) to make the generation of an output policy file optional

      - Added preprocessor support for user-formatted sections (see 7.1.7)

11.4.3 Other changes

      - Indentation is now done using <BLOCKQUOTE> markup.

      - Changed default background colour to white.

      - Generation of a .pol file is no longer default (see 4.2.2.8)

      - The use of <PRE> ... </PRE> to mark up user-formatted text is replaced
        by the new preprocessor commands BEGIN_PRE and END_PRE (see 7.1.7)

      - re-write of section 4.1

      - Improved error reporting.  The .LIS file created if the /DEBUG
        qualifier is used (see 4.2.2.3) now has error and information messages
        included in it.


11.5  Version 2.00 (October '97)

      Version 2.0 marks the production of the first fully-windowed version
      for Windows 95/NT.  This took a few months to be produced, so a fair
      number of other features have been added over this time.

11.5.1 Bug fixes

      - Loads of bugs in parsing user PRE sections (sorry Dennis!).

      - < and > characters inside a PRE section caused characters to be lost
        off the end of lines

      - URL-parsing improved

      - Contents list file links back to main file if no other section links
	generated

      - Newsgroups in headings no longer converted


11.5.2 New functions

      - New [[HYPERLINK POLICY,"Output policy filename"]] policy

      - New [[HYPERLINK POLICY,"Use .HTM extension"]] policy

      - New [[HYPERLINK POLICY,"Generate diagnostics files"]] policy

      - New [[HYPERLINK POLICY,""External contents list filename"]] policy

      - New [[HYPERLINK POLICY,"Use <DL> markup for defn. paras"]] policy

      - New [[HYPERLINK POLICY,"Ignore multiple blank lines"]] policy

      - New [[HYPERLINK POLICY,"Search for emphasis"]] policy

      - New [[HYPERLINK POLICY,"Allow definitions inside PRE"]] policy

      - New Pre-processor CONTENTS command (see 7.1.3)

      - New Pre-processor HTML command (see 7.1.4)

      - New Pre-processor TITLE command (see 7.2.1)

      - New Pre-processor INCLUDE command (see 7.3.1)


11.5.3 Other changes

      - White space immediately adjacent to PRE sections now ignored.

      - Changed anchor names to contain no spaces (makes URL's easier to
	quote)

      - Title defaults to "Converted from filename" instead of "No title"
        (see also 7.5)

      - Introduced some support for use of ctrl-H (backspace) in Unix
	documents to underlined and highlighted words

      - Automated "simple" file detection now attempted

      - Automated "code samples" detection now attempted

      - Some policies have been renamed as follows :-

                Was                             Now
                ---                             ---
      		Expect Numbered sections	Expect Numbered Headings
      		HTML header 			HTML header file
      		HTML footer 			HTML footer file

      - The policy section headings have been renamed as well.  This may
        cause "ignored policy line" messages when old policy files are used.


11.6 Version 2.10 (never officially released)

      V2.1 was never officially released, but much of this functionality
      "crept out" as the shareware version was updated.  Some of these versions
      were shown as V2.01 instead of V2.1.  There's nothing like a bit of
      consistency (and yeah, this was *nothing* like a bit of consistency).

11.6.1 Bug fixes

      - Fixed "Minimum automatic <PRE> size".  Previously didn't work
        at all like advertised.

      - Colour samples in Windowed version were being shown as gray on initial
        draw and on re-draw.

      - Anchor points added to generated contents list had their </A> missing.

      - Fixed occasional "Invalid indent -1" error


11.6.2 New functions

      - New [[HYPERLINK POLICY,"Document keywords"]] policy and pre-processor KEYWORDS
        command (see 7.2.3).

      - New [[HYPERLINK POLICY,"Document description"]] policy and pre-processor
      	DESCRIPTION command (see 7.2.2).

      - New [[HYPERLINK POLICY,"Hyperlinks on Numbers"]] contents policy

      - New [[HYPERLINK POLICY,"Document style sheet"]] policy and pre-processor
      	STYLE_SHEET command (see 7.2.4).



11.6.3 Other changes

      _All versions_

      - Now recognise domain names without a protocol specified (such as http://
        or ftp:// etc.) that end in standard domains (e.g. .edu, .net, .org
        etc) as probable FTP sites.  This allows references to sites like
        rtfm.mit.edu to be correctly turned into hyperlinks.

      - Some renumbering of this document has occurred

      - Quoted text is now marked up using <em>..</em> markup


      _Windows version_

      - Now stores data in the Registry under the
	HKEY_CURRENT_USER root with a "\Software\JafSoft\AscToHTM\..." key

      - Now supports "most recently used" lists for both policy
        files and files to be converted.  These are accessed via a drop-down
	Combo box.

      - Now remembers last source directory each time
      	the program is run.  This is used as the initial directory next time
      	the Browse button is pressed.

      - The filenames now include the path.  This is to allow the most
      	recently used (MRU) file drop-down list to function correctly.



11.7 Version 2.20 (Feb '98)

      First major release after V2.0 (when AscToHTM first went fully-Windowed).
      Major change this time has been the introduction of TABLE generating
      algorithms.  These were first made available as a separate freeware
      utility [AscToTab].

      This version is reviewed by ZDNet and awarded 5-stars, their highest
      award.

11.7.1 Bug fixes

      - End effects now fixed.

      - Various emphasis features eliminated.

      - In-situ contents lists weren't getting the right file names in their
	hyperlinks when the file was being split.

      - Right justified numbered sections weren't being detected correctly
        past section 9.

      - No longer break long URLs over two lines.  This occasionally led to
	hyperlinks that didn't work.

      - No longer generate files for underlined sections when document has
	numbers sections as well, and is being split into files.

      - No longer detect pre-formatted text inside BEGIN_HTML ... END_HTML
	section.

      - Fixed tab conversion bug.


11.7.2 New functions

      _Table generation_

      This is the biggest change in this version.  AscToHTM now incorporates
      the technology first introduced in [AsctoTab].  To support this the
      detection of pre-formatted text has been improved, new policies added,
      and new preprocessor commands added.

      New policies include :-

      	[[HYPERLINK POLICY,"Attempt TABLE generation"]]
      	[[HYPERLINK POLICY,"Default TABLE border size"]]
      	[[HYPERLINK POLICY,"Default TABLE header rows"]]
      	[[HYPERLINK POLICY,"Default TABLE header cols"]]
      	[[HYPERLINK POLICY,"Default TABLE cell spacing"]]
      	[[HYPERLINK POLICY,"Default TABLE cell padding"]]
      	[[HYPERLINK POLICY,"Default TABLE colour"]]
      	[[HYPERLINK POLICY,"Default TABLE border colour"]]
      	[[HYPERLINK POLICY,"Default TABLE caption"]]


        New Pre-processor commands      Description
        -------------------------------------------
        BEGIN_CODE ... END_CODE         7.1.5
        BEGIN_DIAGRAM ... END_DIAGRAM   7.1.6
        BEGIN_TABLE ... END_TABLE       7.1.2
        TABLE_BORDER                    7.4
        TABLE_BORDERCOLOR               7.4
        TABLE_BGCOLOR                   7.4
        TABLE_CAPTION                   7.4
        TABLE_CELLSPACING               7.4
        TABLE_CELLPADDING               7.4
        TABLE_HEADER_ROWS               7.4
        TABLE_HEADER_COLS               7.4


      _Other changes_

      - Added a policy to allow <CODE> markup to be used for code
        fragments in the document (see 6.3.6.11)

      - Added pre-processor CODE commands to allow sections of code samples
        to be identified and distinguished from tables (see 7.1.5)

      - Added pre-processor DIAGRAM commands to allow diagrams and sections
      	Ascii art to be identified and distinguished from tables (see 7.1.6)


11.7.3 Other changes

      _Documentation_

      - Added the "Policy Dictionary" (since superceded by the [Policy manual]),
        and renumbered the document accordingly.


      _All versions_

      - "tables/pre-formatted text"

      - Various improvements to detecting the start and end of pre-formatted
	regions of text.

      - Shareware now expires after 30 days, rather than after a fixed date.

      - Headings policies have been revised.  Still more work to be done in this
      	area.

      - Slight improvement in detection of centred text.  Still not good
        enough to offer as a default though (too prone to errors).

      - Added section on saving/using policy files (see 6.4)

      - Shareware version now adds nag lines at top and bottom of the page,
        instead of just the top.

      - A number of improvements in code sample detection

      - Reduced number of "error" messages reported.  These may be made
	optional in a later version, and are still placed in the diagnostic
	files if these are created.


      _Windows version_

      - Now added a "Settings" dialog to allow you to configure various aspects
        of how the program runs such as what browser to view files with,
      	what policy file to use as default etc, etc.



11.8 Version 2.3 (late April '98)

      Minor bugfixes and upgraded functionality over V2.2.  The main functional
      changes have been

      a) The introduction of wildcard support to allow conversion
         of multiple files at once.

      b) (related to the above) the introduction of the Directory Page
         feature (see 5.6.3 and 6.3.9) that allows the generation of a
         hyperlinked document spanning all the files in a directory.

      c) Major re-write of the contents-list generating routines.  The
         program now makes a third, intermediate, pass through the document
         to analyse the contents structure.  This means that contents lists
         are now placed at the top of the HTML file be default, rather than
      	 in a separate file as previously - though that behaviour is still
         supported if wanted.

      	 This approach is expected to pay further dividends in later releases.


11.8.1 Bug fixes

      - Hyperlinks added from a link dictionary sometimes got broken over
        two lines - inserting white space into the URL - preventing the link
        from working

      - Confusion with numbered sections beginning with "0" or ending ".00"
        eliminated.

      - Problems with formatting after underlined headings fixed.

      - Failed to "view results" when DOS-compatible files we're being
        generated.

      - Various email/ftp/URL improvements

      - Now ignore date-like "headings" e.g. 11.3.1998

      - Capitalised headings were omitted from contents lists, and had
        bad anchor names (contained spaces, difficult to quote)

      - Automatic detection of centred text had stopped working.


11.8.2 New functions

      _Windows Version_

      - Added a "Preform simple conversion" tick box on the front panel.
        This does exactly the same as the [[HYPERLINK POLICY,"Keep it simple"]] policy.

      - Improved the Headings dialog to allow headings policies to be more
        easily edited now.

      - Pre-processor document sections now working.

      _All versions_

      - Wildcard support has been added (see 4.3.3.1).

      - Major re-writing of contents list generation has occurred (see 3.4.2).
        Includes new [[HYPERLINK POLICY,"Use any existing contents list"]] and
	[[HYPERLINK POLICY,"Generate external contents file"]].  More changes are expected
        here in later versions.

      - New Directory Page feature (see 6.3.9).  Supporting policies include:-

      	[[HYPERLINK POLICY,"Make Directory"]]
      	[[HYPERLINK POLICY,"Directory filename"]]
      	[[HYPERLINK POLICY,"Show file titles in Directory"]]
      	[[HYPERLINK POLICY,"Indent headings in Directory"]]
      	[[HYPERLINK POLICY,"Directory title"]]
      	[[HYPERLINK POLICY,"Directory keywords"]]
      	[[HYPERLINK POLICY,"Directory description"]]
      	[[HYPERLINK POLICY,"Directory return hyperlink text"]]
      	[[HYPERLINK POLICY,"Directory Script file"]]
      	[[HYPERLINK POLICY,"Directory header file"]]
      	[[HYPERLINK POLICY,"Directory footer file"]]

      - New [[HYPERLINK POLICY,"Minimum TABLE column separation"]] policy and
      	TABLE_MIN_COLUMN_SEPARATION pre-processor command (see 7.4)
        to allow some tuning of table analysis.

      - New [[HYPERLINK POLICY,"Use first heading as title"]] policy
      - New [[HYPERLINK POLICY,"Use first line as title"]] policy

      - New [[HYPERLINK POLICY,"Recognised USENET groups"]] policy

      - New [[HYPERLINK POLICY,"Automatic centring tolerance"]] policy

      - New [[HYPERLINK POLICY,"Use <P> markup for paragraphs"]] policy to allow
        choice of either <P> or <BR> markup to be used for paragraphs.

      - New [[HYPERLINK POLICY,"Default table width"]] policy and TABLE_WIDTH
	pre-processor command (see 7.4) to allow table widths to be specified

      - New pre-processor command HTML_LINE (see 7.3.2)


11.8.3 Other changes

      - Reinstated some of the "error" messages removed in the last version,
        to do with section numbering.  This should make it more visible when
        the section heading analysis goes wrong.

      - Added error reporting to file open.  You should now get an error
        message if the program fails to find/open a file somewhere.

      - Now support headings down to 5 levels (previously this was 4).  Note,
        if you only have a couple at this level, the program may still ignore
        them as statistically insignificant.

      - Removed certain policies (such as "generate policy file") from the
        output when generating a full policy file.  This is because, when
      	they were read back in, they could cause problems.

      - The "Include document section" policy is now renamed to
        "Include document section(s)" reflecting the fact that you can now
        enter multiple values on one line, rather than requiring multiple
        lines with one value each as previously.

      - Major re-structuring and additions to [[GOTO HTML markup produced]] to make the section
        more coherent and up to date.  Some of the sections marked as new
        in this version are simply the documentation catching up on the
        features added in earlier releases.

      	Sometimes I just work too hard :^)


11.9 Version 3.0 (August '98)

      There are a fair number of small changes in functionality over V2.3,
      together with a fair number of bugfixes and refined algorithms.  A lot
      of development during this time was directed towards the production of
      a text-to-RTF converter ([AscToRTF]) using the same analysis engine.
      Consequently there are a lot of changes "under the bonnet".

      The main functional change has been the revamp of the Windows User
      Interface.  A new section (4.1.2) has been added to this document
      describing the Windows interface in some detail.  The changes
      include :-

      	 - the button bar is replaced by a proper Windows menu, allowing
      	   easier access to the programs functions.

      	 - under the Help menu a link to the HTML documentation shipped with
           the software is now provided.

      	 - the policy sheets are now "non-modal".  This means you no longer
           have to dismiss them in order to do a conversion, you can leave
           them up whilst the conversion is going on, making it easier to
           go through the convert-change policy-convert cycle.


11.9.1 Bug fixes

      _Windows version_

      - General Protection Fault was occurring on the "Analyse file" button
        if a file had not yet been converted.  This bug was introduced in
        V2.3

      _All versions_

      - No longer inserts <BR> before first heading if the first line in the
        file is a heading

      - "headings" that were underlined, but which were in fact part of
        a table are no longer added to generated contents lists.

      - Underlined/capitalised headings now get correct hyperlinks in contents list
      	lists when using DOS filenames

      - Fixed bug that caused contents lists immediately following underlined
        headings to not be recognised

      - URLs in heading no longer lead to invalid anchor tags

      - Various URL changes; "alt." and "news." no longer treated as
        a newsgroup, https:// pages now recognised

      - Properly reject "indent" of 1.  Previously this was reported as
        rejected, but was actually accepted.

      - [[HYPERLINK POLICY,"Expect code samples"]] policy was being ignored in table
        calculations.

      - The TABLE_HEADER_COLS directive only worked when there were header
        rows as well.

      - Use of emphasis inside a TABLE cell was not being detected at all.  Now
        it is detected if held on a single line.  Phrases that are emphasised
        over several lines inside a table cell may still not be detected.

      - Fixed a bullet numbering problem.  Previously the bullet numbering
        wasn't being reset correctly if two sets of bullets were separated
        by text with a larger margin than the bullets.

      - Emphasis at end of line now properly recognised

      - Fixed bug that caused emphasis markup near pre-formatted sections of
        text

      - Small correction to line-splitting algorithm to prevent <TAG>s being
        spilt when they're near the natural break.

      - Pre-processor command $_$_TITLE was being ignored if the
	[[HYPERLINK POLICY,"Use first heading as title"]] policy was set.


11.9.2 New functions

      _Windows Version_

      - Major re-structuring of the user interface (see 4.1.2)

      - Program's Help options now provide access to the online and offline
        versions of the HTML doco.  A lot of people were downloading the
        software and then picking up a version of the doco, unawares they
        already had it.  Don't you people read README.TXT files or what?


      _All Versions_

      - New [[HYPERLINK POLICY,"Search for Definitions"]] policy

      - New [[HYPERLINK POLICY,"TAB size"]] policy

      - New [[HYPERLINK POLICY,"Expect sparse tables"]] policy and TABLE_MAY_BE_SPARSE pre-processor
        command (see 7.4)

      - New [[HYPERLINK POLICY,"Add <BR> to lines with URLs"]] policy

      - New [[HYPERLINK POLICY,"Output file extension"]] policy

      - New [[HYPERLINK POLICY,"Minimise HTML file size"]] policy

      - New [[HYPERLINK POLICY,"Headings colour"]] policy.  Eventually I hope to add
        a whole suite of heading styling options, as these have been requested
        by a number of people.

      - New [[HYPERLINK POLICY,"Convert TABLE X-refs to links"]] policy and TABLE_CONVERT_XREFS
        pre-processor command (see 7.4)

      - New CHANGE_POLICY pre-processor command (see 7.5)

      - New [[HYPERLINK POLICY,"Error reporting level"]] policy


11.9.3 Other changes

      - Improved Windows interface

      - Empty lines in a table cell now get an extra &nbsp; added, in addition
        to the <BR>.  This is to compensate for a bug in Internet Explorer 3
        which would ignore the <BR> otherwise, leading to alignment errors.

      - Now treat phrases with all the words connected by underscores, and with
        underscores at both ends as well as underlined e.g.
        _this_type_of_thing_

      - Improved handling of tables with long urls in them.  Previously these
        would not be recognised as part of a table.  Increased "long line"
        limit inside tables to 110 characters

      - Improved error reporting/handling

      	- Report unrecognised pre-processor lines
      	- Report results of table analysis (e.g. if diagrams are detected)
        - Report failure to find requested files
      	- Abort conversion if can't find requested policy file

      - Improved detection of "mal-formed" tables.  Previously this was
        over-cautious, especially on short tables.

      - Now add a trailing "/" to www etc URLs if none present (e.g.
        www.jafsoft.com).  This is a more correct URL, which should be accessed
        slightly more efficiently.

      - Now recognised "....." underlining, although why people do this is
        beyond me :)

      - Improved contents list detection in short documents with only level
        one headings, and documents with a chapter "0".

      - Improved headings detection in small files.  Made this less trigger
        happy.

      - Improved code detection, and now add bold emphasis of C++ like comments
        inside a code section

      - No longer allow "{" and "}" to be detected as probable bullet characters
        when code is expected

      - I've produced (with help from antipodean friends) an icon for files
      	converted by AscToHTM.  It's called a2hlogo.gif.  Feel free to use it
      	should you wish on any pages created with AscToHTM.

      	An example piece of HTML code would be

$_$_BEGIN_PRE
      	<A HREF="http://www.jafsoft.com/asctohtm/?doco">
        <IMG SRC="a2hlogo.jpg" WIDTH=100 HEIGHT=36 BORDER=0
        ALT="Converted by AscToHTM"></A>
$_$_END_PRE

      - With the introduction of the [[HYPERLINK POLICY,"Add <BR> to lines with URLs"]] policy
      	this behaviour is no longer default.  That is, if you *do* want <BR>
	added at the end of all lines containing URLs you will need to switch
	this behaviour on using the new policy.

      - With the introduction of the [[HYPERLINK POLICY,"Convert TABLE X-refs to links"]] policy
        this behaviour is no longer default.  That is, if you *do* want
	section links inside your tables, you will need to switch
      	this behaviour on using the new policy.

      - ".htm" files are now with a lowercase extension, unless
	[[HYPERLINK POLICY,"Use DOS filenames"]] policy selected



11.10 Version 3.2 (October '99)

      (Version [[TEXT 3.1]] was never released, but a release of [AscToTab] occurred
      sometime after version [[TEXT 3.0]], and so in keeping with the policy of
      synchronizing version numbers *that* was labelled version [[TEXT 3.1]])

      Over a year after the last release, version [[TEXT 3.2]] is a major upgrade, but is only
      given a minor version number change because the remainder of the
      functionality produced in that time will be revealed in version [[TEXT 4.0]].
      In point of fact the main difference between the two versions is that
      [[TEXT 4.0]] will fully document many of the features that are lying
      dormant in version [[TEXT 3.2]] (especially in-line tagging and CSS/font
      support).  Once the documentation is complete, the next version [[TEXT 4.0]]
      will be announced as a major upgrade (suitable for review by software reviewers).

      Version [[TEXT 3.2]] starts to prepare the groundwork for Cascading Style Sheet (CSS)
      and general font support that will be introduced in version [[TEXT 4.0]].
      This has required a fairly radical change to the type of HTML code
      generated and how this is put together.

      For example the HTML is now more standards compliant (this is now a
      stated goal of the software, although I can't always promise full
      compliance see 1.1.4), and as an aid towards CSS support "optional" end tags such
      as </P> are now being placed in the generated HTML.

      Note that the use of the <FONT> tag is deprecated in HTML [[TEXT 4.0]], and
      if you choose to add FONT markup to your pages they'll become much
      bigger, especially if they contain tables.  This is because the HTML
      standard requires the FONT tag to continually be re-expressed to
      achieve the right appearance in all browsers (believe me, I only
      accepted this through bitter experience and grudgingly).

      Major changes in version [[TEXT 3.2]] include :-

        - The program now *always* makes three passes through
          the document - previously it only did this if a contents list was
          requested (see 3.3).  This may make the conversion a little slower.  The
          middle pass calculates how the file will be split into
          sections, where all the hyperlinks should point to and what the
          contents list should be.  This approach should be less error prone
          than previously.

        - New "overview" options (see 6.2.1).  These allow you to easily
      	  enable and disable the program's search for certain features.

	- Introduction of in-line tagging (see [[GOTO "Using in-line tags"]]).
      	  These allow you to get more out of your conversion by inserting
      	  commands into your source text.

	- Addition of DDE support (in Windows) (see 4.1.3.4)

	- New and improved command line options, and full command line support built
	  into the Windows version (see 4.2.2.)

        - Improved message filtering.  Each message is now labelled according
      	  to its type (information, warning etc), and may be optionally
      	  suppressed or filtered by severity.  A new /SILENT command qualifier
      	  (see 4.2.2.9) allows complete suppression of messages.

        - Improved log file capability (see 4.3.4)

        - Added support for mail and USENET headers (see 5.4.5)

        - (Limited) support added for stripping out page markers, converting
      	  "double spaced" files, and converting .prn and VT escape sequences.
      	  This functionality may be improved in later versions.

      	- New options to colour the odd and even rows of tables differently
      	  (see 6.3.7 and 7.4)


11.10.1 Bug fixes

      _Windows version_

      - The Windows help file in version [[TEXT 3.0]] wasn't accessible via
      	the F1 key.  This is now fixed.

      - INCLUDE statements now report any failure to open the file, and
	insert directory paths where necessary to resolve the file
	locations (Windows)

      - Fixed various bugs so that the output filename and directory can
      	be changed.  Previously this didn't work too well.

      - So many others, I can't remember them all :-)


      _All versions_

      - Numbers in the text will now only convert to hyperlinks if the
        *exact* section number can be found in the document.  This improves
        on previous versions that only did approximate range checks.

      - Underlined headings may now be split into files, and duplicate
        filenames are now avoided

      - URLs separated by semi-colons were not being correctly converted

      - email addresses with two "@"s are now rejected, and no longer accept
        "%" at start of email address

      - No longer treat ___some_text___ as underlined

      - Contents list generation failed for documents with "Section: n" as
        the headings

      - Fixed bug that could wrongly right-align some columns in a table
        if there was a big gap.

      - Fixed various bugs related with emphasis phrases that spanned multiple
        lines.  We now no longer allow detection of "nested" emphasis, nor
        is emphasis allowed to cross blank lines.

      - Improved file handling.  Now get error messages when files aren't
        found, and the program is better at locating files under Windows.
        The program now supports the use of relative filenames for include
        files etc.

      - In a usenet reference such as news://comp.os.vms the "news:" was
      	being left outside the display part of the generated hyperlink

      - Repeated Link definitions on the same line weren't being
      	substituted correctly

      - Improved handling of user-delimited contents lists using the
      	BEGIN_CONTENTS ... END_CONTENTS directives


11.10.2 New functions

      _Windows Version_

      - Added "Save" option to status dialog, so that the messages can be
        saved into a .log file

      - Added DDE support to display results in existing browser window

      - Full drag and drop support added.  You can now drag files onto the
	program when it is visible.

      - New "browse for directory" buttons added.

      - More menu options added to make finding policies easier.


      _All versions_

      - Now support tab-delimited tables (mainly for AscToTab) (see 7.1.2)

      - Support for stripping out mail and USENET headers (see 5.4.5)

      - New pre-processor directives :-

      	- BEGIN_DELIMITED_TABLE ... END_DELIMITED_TABLE section delimiters
      	  (see 7.1.2)
      	- IGNORE command (see 7.1.8)
      	- CONTENTS_LIST command (see 7.3.3)
      	- NAVIGATION_BAR command (see 7.3.3)
      	- LINERULE command (see 7.3.4)
      	- TOC command (see 7.3.5)

      - New and improved command line qualifiers

      	- /CONSOLE (see 4.2.2.1)
      	- /LIST (see 4.2.2.3)
      	- /OUT=filename (see 4.2.2.7)
      	- /SILENT (see 4.2.2.9)

      	- (improved) /LOG=<filespec> (see 4.2.2.6).  You can now specify the
      	  log filename
      	- (improved) /POLICY=filename (see 4.2.2.8).  You can now specify the
      	  created policy filename

      - New overview "look for" analysis policies :-

        - [[HYPERLINK POLICY,"Look for indentation"]]
      	- [[HYPERLINK POLICY,"Look for paragraphs"]]
      	- [[HYPERLINK POLICY,"Look for short lines"]]
      	- [[HYPERLINK POLICY,"Look for quoted text"]]
      	- [[HYPERLINK POLICY,"Look for preformatted text"]]
      	- [[HYPERLINK POLICY,"Look for mail headers"]]
      	- [[HYPERLINK POLICY,"Look for horizontal rules"]] and
          [[HYPERLINK POLICY,"Minimum ruler length"]]
      	- [[HYPERLINK POLICY,"Look for MAIL and USENET headers"]]
      	- [[HYPERLINK POLICY,"Look for bullets"]]
      	- [[HYPERLINK POLICY,"Look for hanging paragraphs"]]
      	- [[HYPERLINK POLICY,"Look for white space"]]


      - Other new analysis policies :-

      	- [[HYPERLINK POLICY,"Input file has page markers"]] and
          [[HYPERLINK POLICY,"Page marker size (in lines)"]]

      	- [[HYPERLINK POLICY,"Input file is double spaced"]]

      	- [[HYPERLINK POLICY,"Recognise '-' as a bullet"]]
      	- [[HYPERLINK POLICY,"Recognise 'o' as a bullet"]]


      - New diagnostic policies :-

      	- [[HYPERLINK POLICY,"Monitor tag generation"]]

      	- [[HYPERLINK POLICY,"GOTO Display messages"]] policy and /SILENT
          qualifier (see 4.2.2.9)

        - [[HYPERLINK POLICY,"Suppress INFO messages"]],
        - [[HYPERLINK POLICY,"Suppress TAG ERROR messages"]]
        - [[HYPERLINK POLICY,"Suppress URL messages"]]
        - [[HYPERLINK POLICY,"Suppress WARNING messages"]]
        - [[HYPERLINK POLICY,"Suppress program ERROR messages"]]


      - Other new output policies :-

      	- [[HYPERLINK POLICY,"Create a log file"]] and
          [[HYPERLINK POLICY,"Output log filename"]]

      	- [[HYPERLINK POLICY,"Maximum level to show in contents"]]

      	- [[HYPERLINK POLICY,"Preserve underlining of headings"]]

      	- [[HYPERLINK POLICY,"Use <EM> and <STRONG> markup"]]

      	- [[HYPERLINK POLICY,"Colour data rows"]] and related policies
      	  (see 6.3.7).

      	- [[HYPERLINK POLICY,"Default TABLE cell alignment"]] and
	  TABLE_CELL_ALIGN directive (see 7.4)

        - [[HYPERLINK POLICY,"Suppress all colour markup"]]

      	- [[HYPERLINK POLICY,"Open link in new browser window"]] and
	  [[HYPERLINK POLICY,"new browser window name"]]

        - [[HYPERLINK POLICY,"Break up long HTML lines"]]



11.10.3 Other changes

      _On the web site, and documentation_

      - A dedicate site www.jafsoft.com now deals with AscToHTM and related
      	products.

      - An [updates] page has been added to the Web site.  This will list all
        the updates available for AscToHTM, although in most cases you'll
        need to be a registered user to receive details for you to
      	obtain the update.

      - An [FAQ] has been added to the web site.  It's not finished yet (what
        part of the web is?), but it may help answer some of your questions.

      - Created a new document called "The [Policy Manual]".  This replaces
        what was becoming the largest section of this document.


      _Windows version_

      - The Windows help file now has a better Index.  It also has a full
        contents list as a topic, showing you the structure of the RTF file
        used to generate the Help file.  Unfortunately I've been unable to
      	hyperlink this topic.

      - The Windows version now "remembers" which options page you were on
        so that each time you go back there the same sheet is shown.

      - The Windows version is now "statically linked" against the necessary
	.DLLs.  This makes the program slightly larger, but makes the download
	smaller as it is no longer necessary to ship .DLLs with the program.
	This makes overall version management simpler.


      _VMS version_

      - The VMS version now converts all filenames to lower case internally.
        This is so that all hyperlinks and references to the file are in
        lower case, making them more Internet-friendly and portable to
        other systems.


      _All versions_

      - Changes to the tagging to aid standards compliance and CSS support.
      	this includes the addition of the </P> tag which was previously
      	omitted.  These changes have introduced slight differences in th
      	amount of vertical white spacing produced in places.

      - Improvements have been made to the file splitting algorithms.  In
        particular

      	- The program will no longer generate two output pages with the
      	  same name.  Where duplicate names are detected, the second file
          is given a generated name, usually by appending "_n" (n=1,2,3...)
      	  to the filename.  All hyperlinks pointing to sections in the
      	  duplicate file will be adjusted accordingly.

      	- A file with underlined headings can now be split into pages at the
          heading boundaries.  The subsequent pages have _U1, _U2... appended
          to the name of the first page.

        - Local links (i.e. to anchors in the same file) are now recognised
      	  as such, and the filename is omitted.

          This should make it easier to rename files after production without
      	  breaking local hyperlinks.  Links to/from other files would still
          stop working though.

      - link names for underlined or capitalised headings that are more than
        60 characters long are now truncated.  They are given a link name
        derived from the first 30 characters of the section name with
        a unique identifier tagged on the end.  This avoids long link names
        being split over two or more lines and becoming unusable.

      - Allow relative links to subtract out filename (e.g. in contents list)
        when target is in same file

      - Can now recognise URLs with commas in then such as
        recognise http://cgi.pathfinder.com/netly/opinion/0,1042,1692,00.html
        in addition to comma separated lists of URLs.

      - The KEYWORDS, DESCRIPTION and TITLE pre-processor commands
      	can now be multi-line.  This allows long lists of keywords to be
      	placed over several lines (each beginning with the command), making
      	then easier to manage.

      - The default name for the directory index file is now "dirindex.html"
        rather than "index.html" to prevent overwriting of any existing
        index file.

      - Program now always does a "contents pass".  Benefits of this are
	  - can now generate in situ contents lists /contents bars
          - can now generate nav bars wherever wanted
          - can now eliminate duplicate filename generation
          - can check hyperlink cross references are correct

      - Improved table/diagram recognition

      - Now support conversion of tab-delimited data into tables, provided
      	it's placed inside BEGIN_DELIMITED_TABLE ... END_DELIMITED_TABLE
      	directives (see 7.1.2)

      - Relaxed indentation test on "n.n" headings.  Heading can now be
        2 characters to the left, or 1 character to the right of the expected
        position

      - Now recognise use of asterisk and underscore combined to produce
      	bold-italic emphasis.  Previously only asterisk (bold) and underscore
      	(italic) by themselves were recognised.

      - Now recognise "]" as a possible "quoting" character.

      - Now recognise '+' as an underling character

      - Improved error reporting when file errors occur.  The program will
      	now abort the conversion on error, instead of continuing and reporting
      	errors for each line.

      - Now detect read-only output directories and abort conversion.  This
        would occur if you tried to convert a file on CD.

      - Definitions now use <DL compact> offering a more-faithful rendition
        of the original text

      - Underlined heading and text will now be rendered as underlined by
        default.  Previously this either promoted the previous line to be
        a heading, or was drawn as a line.

      - Improved handling of first line indents on paragraphs.  Now these
        are preserved in the output by the inclusion of &nbsp; characters,
        and the error whereby the following line was deemed to be a different
        indentation (and thus acquire a <BLOCKQUOTE>) has been largely
        solved.

      - Introduction of the TEXT in-line tag (see 8.2) now allows numbers
        like Windows [[TEXT 3.1]] to be protected from conversion into a
        hyperlink to section 3.1.
