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

      [AscToTab] is a highly specific ASCII to HTML conversion tool.  It
      converts plain text files to HTML tables.  That's all it does.  It
      doesn't convert tab separated lists, or comma separated lists.

      [AscToTab] evolved out of the development of [AscToHTM], the
      general-purpose text to HTML conversion utility.  AscToTab now
      forms a subset of AscToHTM, and is offered as "as is" freeware.  It
      will probably only improve as it's contribution to AscToHTM is
      improved.  As of Version V2.3, AscToTab version numbers will simply
      match the AscToHTM release they are a subset of.

      The HTML version of this document has been produced using AscToHTM, and
      no post-processing has been done to the HTML pages produced.
      It has been generated from a single source document and a few small
      configuration files.

      This document describes AscToTab V2.3, which is available as freeware
      (or postcardware if you like, but I'm still waiting for my first
      postcard) from April 1998.  [AscToHTM] is available as shareware, and
      has been awarded 5 stars by ZDNet, the only text to HTML converter to
      attain this award to date.

      As of V2.3, AscToTab forms a complete subset of [AscToHTM].  This
      includes the command line interface and the use of policy files.  For
      this reason, and to avoid duplication, reference is occasionally made
      to the [A2hDoco].

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


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

      AscToTab is downloadable as a .ZIP file from [AscToTab Download location].
      You should download the version best suited to your needs.

      Once downloaded, simply unzip the files and move them to a suitable
      location.

      AscToTab V2.3 runs as a console application ("DOS program") under
      Windows 95/NT, and from the command line under OpenVMS.


3     How AscToTab works
------------------------

      AscToTab looks at the layout of your text file and tries to spot the
      column boundaries in your table.  It doesn't require or recognise
      comma- or tab-delimited values.

      Having detected your column positions, it attempts to detect if your
      table has a header.

      Finally it outputs your table, paying attention to the following

      	- Data alignment.  The alignment of a column is checked, and
          where suitable, numerical values are right-aligned.

        - Column-spanning.  Where a value appears to span two or more columns
          the COLSPAN attribute is used, and the alignment re-calculated.
      	  If too many values appear to span columns, the columns are liable
          to be merged.

        - Table headers.  Where the heading is underlined, this is detected
          and the header row(s) are marked up using <TH> markup.

        - Cell entries that span multiple lines.  Where possible, this is
      	  detected and the entries are added together with <BR> inserted to
          preserve the original layout.

        - Blank lines.  Usually omitted, unless they appear to be separators,
          in which case this information is fed back into the cell analysis.

        - Border.  Added unless a number of user-supplied lines are detected
          in which case these are shown, and the HTML border omitted.

      In addition to it's automatic features, AscToTab can be customised to
      give even better output.  See [section 6] for details.


4     Running AscToTab
----------------------

4.1   Execution from a command line

      From a command prompt (Windows or OpenVMS) you can type

        AscToTab <textfile> [<policy file>] [/qualifiers]

      Where

      	<textfile>

      	Name of file to be converted.  The output will
      	be the same name with a ".html" extension.  Wildcards are allowed.

      	If the <textfile> is of the form "@<filename>", then
      	AscToTab will read the file <filename> line-by-line
      	and convert the files listed in that file.

      and

      	<policyfile>	

      	Is a "policy" file used to customise the conversion see 6.1.

      As of V2.3, the command line interface is in fact shared with [AscToHTM],
      although not all qulifiers are relevant.  See the [A2hDoco] for more
      details.


4.2   Drag'n'Drop execution

      Create an Icon for AscToTab and simply drag'n'drop files onto it.
      The results will be identical to those obtained by typing in the
      filenames as described in 4.1.


4.3   Refining your results

      If all goes well the resultant HTML will be satisfactory.
      However, you can customize the conversion in two ways:-

      	- Use a policy file (see 6.1)

      	- Use pre-processor commands (see 6.2).


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

5.1   <TABLE> statement

5.1.1 BORDER=n attribute

      AscToTab will default to a BORDER=2 unless

      a) A BORDER preprocessor command is encountered (see 6.2.1)

      b) It determines that the user has added their own lines


5.1.2 CELLPADDING=n attribute

      AscToTab will only add CELLSPACING if a CELLSPACING
      preprocessor command is encountered (see 6.2.2).


5.1.3 CELLPADDING=n attribute

      AscToTab will add CELLPADDING if:-

      a) It enounters a CELLPADDING command  (see 6.2.2)

      b) A BORDER is present.  The default is CELLPADDING=4


5.1.4 BGCOLOR="colour" and BORDERCOLOR="colour" attributes

      AscToTab will add these attributes if it encounters BGCOLOR
      or BORDERCOLOR commands (see 6.2.3).


5.1.5 WIDTH=<pixel_size> or WIDTH=<percentage>

      AscToTab will add this attribute if it encounters a WIDTH command
      (see 6.2.7)


5.2   <CAPTION> statement

      AscToTab will add a caption if it encounters a CAPTION
      command (see 6.2.4)


5.3   <TH> statements

      AscToTab will use <TH>..</TH> markup whenever it determines that a
      cell forms part of the header.

      AscToTab will attempt to automatically detect headers by looking for
      a single separator line near the top of the file.

      Alternatively the HEADING_ROWS command (see 6.2.5) will be
      used to specify the number of header lines.

      AscToTab will set the ALIGN and COLSPAN attributes as best it can.


5.4   <TD> statements

      AscToTab will use <TD>..</TD> markup for most of the cells in
      the table.

      If the HEADING_COLS command (see 6.2.6) is encountered,
      the first few columns will additionally use <STRONG>...</STRONG> markup.

      AscToTab will set the ALIGN and COLSPAN attributes as best it can.


6     Customising your conversions
----------------------------------

6.1   Policy files

      Policy files are an [AscToHTM] feature that are supported as of V2.3.

      Not all of the policies recognised are relevant to AscToTab, but here's
      a list of some that are :-

	Descriptive text                 Values
	-----------------------------------------------------------------
	Active Link Colour               HTML Colour
	Background Colour                HTML Colour
	Background Image                 URL of image
	Default TABLE border colour      HTML Colour
	Default TABLE border size        Number. 0 = "automatic"
	Default TABLE caption            Text String
	Default TABLE cell padding       Number. 0 = "none"
	Default TABLE cell spacing       Number. 0 = "none"
	Default TABLE colour             HTML Colour
	Default TABLE header cols        Number. 0 = "automatic"
	Default TABLE header rows        Number. 0 = "none"
	Default TABLE width              Table width in pixels or as a
					 percentage of page width
	Document Style Sheet             URL of style sheet file
	Document description             Text string
	Document keywords                Comma-separated list
	Document title                   Text string
	HTML footer file                 File name.  File contains HTML commands
	HTML header file                 File name.  File contains HTML commands
	Text Colour                      HTML Colour
	Unvisited Link Colour            HTML Colour
	Use .HTM extension               Yes/No
	Visited Link Colour              HTML Colour

      Policy files are simply text files with a .pol extension by default.
      Each is placed on a separate line with the policy phrase, a colon (:)
      and the value.  The .pol file is then specified as an extra argument
      on the command line (see 4.1).

      An example policy file might look as follows:-

$_$_BEGIN_PRE
	Background Colour        	: CCDD00
	Default TABLE border size       : 3
	Default TABLE colour            : White
	Default TABLE width             : 75%
	Document title                  : This is a table I converted
	Document keywords               : Keywords, included, in, META, tag
$_$_END_PRE


6.2   Preprocessor commands
----------------------------

      The preprocessor is a feature shared with [AscToHTM].  Essentially you
      insert commands into your source file that tell AscToHTM how you
      want various aspects of your file converted.

      The preprocessor looks for lines that begin with a special character
      sequence "$_$_".  All the AscToTab commands add "TABLE_" to this, making
      the relevant prefix "$_$_TABLE_".  This sequence *must* appear at the
      start of the source line with no leading white space.  Each command
      must be wholly contained on a separate line.

      Commands are best placed at the top of the source file.

      See the [A2hDoco] for more details

6.2.1 The BORDER command

      $_$_TABLE_BORDER       5

      This command specifies the BORDER attribute.
      A value of 0 means "none".


6.2.2 The CELLSPACING and CELLPADDING commands

      $_$_TABLE_CELLSPACING       5
      $_$_TABLE_CELLPADDING       5

      These command specify the values of the CELLSPACING and CELLPADDING
      attribute.

      A value of 0 means "none".


6.2.3 The BGCOLOR and BORDERCOLOR commands

      $_$_TABLE_BGCOLOR		AntiqueWhite
      $_$_TABLE_BORDERCOLOR	#FF2345

      These commands specify the values of the BGCOLOR and BORDERCOLOR
      attributes.


6.2.4 The CAPTION command

      $_$_TABLE_CAPTION		Ooo! what a pretty table

      This command specifies the value of <CAPTION>...</CAPTION> markup to
      be added to the table.


6.2.5 The HEADING_ROWS command

      $_$_TABLE_HEADING_ROWS       4

      This command tells AscToTab how many lines of text are to be treated
      as part of the header.  This should be the number of lines as it
      appears in the source file, including any blank lines.


6.2.6 The HEADING_COLS command

      $_$_TABLE_HEADING_COLS       1

      This command tells AscToTab how many columns (if any) at the start of
      each line should be marked up in <STRONG>...</STRONG> markup.


6.2.7 The WIDTH command

      $_$_TABLE_WIDTH	500
      $_$_TABLE_WIDTH	75%

      This command specifies the value of the WIDTH attribute in pixels or
      as a percentage of screen width


6.2.8 The MIN_COLUMN_SEPARATION command

      $_$_TABLE_MIN_COLUMN_SEPARATION 2

      This command specifies the minimum number of spaces that may be
      interpreted as a column separator.  The default value is 1, but this
      occasionally gives rise to too many "columns" - particularly in short
      tables, or columsn whose data values are similar.

      A larger value will lead to fewer columns.


7     Purchasing AscToTab
-------------------------

7.1   How do I purchase AscToTab (trick question)?

      You can't.  It's free.  Or rather I'd like it to be postcardware, but I'm
      still waiting for the first card :(

      It you really like the program, send a postcard to

      	John A Fotheringham
        c/o Yezerski Roper
      	Applicon House
      	Exchange Street
      	Stockport
      	SK3 0ET

      	UK

      You could also look at [AscToHTM], which shares the same technology, and
      which includes AscToTab.  AscToHTM is shareware in the Windows version.


8     Contacts on the Web
-------------------------

8.1   The home page

      At time of writing [Yezerski Roper] (whom I work for) have graciously
      allowed me to give [AscToTab] and [AscToHTM] a home page.

      Yezerski Roper are the most intelligent software house it's
      ever been my privilege to be associated with.  We're based in the UK
      and offer OpenVMS and Windows NT systems, and are currently
      developing state-of-the-art products which will allow companies
      to exploit the full communications potential of the Internet.

      Oh yeah... and they pay me as well :)

      AscToTab and AscToHTM are "hobbies".

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

      		+"John A Fotheringham" +AscToTab

      to locate any new home page.


8.2   E-mail

      E-mail any feedback to jaf@yrl.co.uk.  Sadly, we cannot guarantee any
      replies.


8.3   Support

      A limited amount of support is available by emailing jaf@yrl.co.uk.
      Sadly, we cannot guarantee any replies, though we do try to be helpful.


9     Known problems
--------------------

      None.  (Ignorance is bliss)


10    Change History
--------------------

10.1  Version 1.00 (December '97)

      Initial release of command line version as postcardware.


10.2  Version 2.00 (February '98)

      AscToTab is now fully integrated into [AscToHTM], and the bug fixes
      and enhancements are released as V2.00 of AscToTab


10.3  Version 2.3 (April '98)

      AscToTab is now totally subsumed in [AscToHTM].  The command line
      interface is now the same, allowing wilcards and policy files to be
      used.

      New commands are added (see 6.2.7 and 6.2.8), and more improvements are
      made to the algorithms.

      From now on the AscToTab version numbers will indicate the release of
      AscToHTM they are a subset of.
