5 $_$_CHANGE_POLICY Convert TABLE X-refs to links : Yes  1     Introduction ------------------  I       [AscToTab] is a highly specific ASCII to HTML conversion tool.  It  H       converts plain text files to HTML tables.  That's all it does.  ItM       doesn't convert tab separated lists, or comma separated lists, although J       this may be added in the _very near future_ as it's *so* easy to do.  B       [AscToTab] evolved out of the development of [AscToHTM], theD       general-purpose text to HTML conversion utility.  AscToTab nowG       forms a subset of AscToHTM, and is offered as "as is" freeware.     I       As of V2.3, AscToTab now forms a complete subset of AscToHTM.  This K       includes the command line interface and the use of policy files.  For L       this reason, and to avoid duplication, reference is occasionally made        to the [A2hDoco].   B       From V2.3 onward, AscToTab version numbers simply match the G       AscToHTM release they are a subset of, regardless of whether the  F       AscToTab part of the functionality has advanced significantly orJ       not.  However only those releases of AscToTab that have significant C       new functionality will be announced separately (via USENET) .   C       This document describes AscToTab V3.0, which is available as  N       postcardware (a big thanks to those that have sent in postcards, they'reF       much appreciated) from August 1998.  [AscToHTM] is available as K       shareware, and has been awarded 5 stars by ZDNet, the *only* text to  2       HTML converter to attain this award to date.  M       The HTML version of this document has been produced using AscToHTM, and B       no post-processing has been done to the HTML pages produced.I       It has been generated from a single source document and a few small        configuration files.  K       If you encounter a RTF version of this document, that will have been  G       produced by a text-to-RTF converter which we are developing using        the same analysis engine.   C       AscToTab is made available for download via the Internet from #       [AscToTab download location].      2     Installation ------------------  P       AscToTab is downloadable as a .ZIP file from [AscToTab Download location].@       You should download the version best suited to your needs.  I       Once downloaded, simply unzip the files and move them to a suitable        location.   H       AscToTab V3.0 runs as a console application ("DOS program") under =       Windows 95/NT, and from the command line under OpenVMS.   M       Note: In the _very near future_ I plan to offer a full Windows version.      3     How AscToTab works ------------------------  J       AscToTab looks at the layout of your text file and tries to spot theM       column boundaries in your table.  It doesn't (yet) require or recognise .       comma-delimited or tab-delimited values.  J       Having detected your column positions, it attempts to detect if your       table has a header.   F       Finally it outputs your table, paying attention to the following  C       	- Data alignment.  The alignment of a column is checked, and =           where suitable, numerical values are right-aligned.   M         - Column-spanning.  Where a value appears to span two or more columns I           the COLSPAN attribute is used, and the alignment re-calculated. J       	  If too many values appear to span columns, the columns are liable           to be merged.   K         - Table headers.  Where the heading is underlined, this is detected @           and the header row(s) are marked up using <TH> markup.  I         - Cell entries that span multiple lines.  Where possible, this is J       	  detected and the entries are added together with <BR> inserted to'           preserve the original layout.   M         - Blank lines.  Usually omitted, unless they appear to be separators, L           in which case this information is fed back into the cell analysis.  L         - Border.  Added unless a number of user-supplied lines are detectedE           in which case these are shown, and the HTML border omitted.   K       In addition to it's automatic features, AscToTab can be customized 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   9         AscToTab <textfile> [<policy file>] [/qualifiers]          Where          	<textfile>   5       	Name of file to be converted.  The output will I       	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-line1       	and convert the files listed in that file.   	       and          	<policyfile>	  C       	Is a "policy" file used to customize the conversion see 6.1.   I       As of V2.3, the command line interface is in identical to that used L       by [AscToHTM], although virtually none of the qualifiers are relevant.    & 4.1.1 Processing several files at once   4.1.1.1 Using wildcards          *Section added in V3.0*   I       You can convert multiple files at one time by specifying a wildcard N       describing the files to be converted.  The wildcard has to be meaningfulD       to the operating system you are using, and will be expanded in       alphabetical order.   J       At present we recommend that wildcards are only used on the contents       of a single directory.  N       Note, the same policies will apply to all files being converted.  If youI       wish different policies to apply, use a steering command file (see         4.1.1.2)    % 4.1.1.2 Using a steering command file          *Section added in V3.0*   M       You can convert several files at the same time in the order and manner  3       of your choosing.  To do this use the command   2         AscToTab @List.file [rest of command line]  L       Where the file "list.file" is a steering file which contains a list ofN       AscToTab command arguments, 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 my first table... it's special$ 		Table1.txt      special_policy.pol 		# = 		# These are my other tables.  I don't want table2 converted  		table3.TXT 		table4.TXT $_$_END_PRE     H       Note the use of "!" or "#" at the start of a line signifies it's a!       comment line to be ignored.   G       Any qualifiers used on the original AscToTab line will be used as K       defaults for each conversion, but will be overridden by any listed in K       the list file.  In this way it would be possible to specify a default 5       policy file for a bunch of similar conversions.      4.2   Drag'n'Drop execution   G       Create an Icon for AscToTab and simply drag'n'drop files onto it. F       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  0       AscToTab will default to a BORDER=2 unless  A       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   9       AscToTab will only add CELLSPACING if a CELLSPACING 6       preprocessor command is encountered (see 6.2.2).     5.1.3 CELLPADDING=n attribute   (       AscToTab will add CELLPADDING if:-  9       a) It encounters 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  A       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>  H       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   H       AscToTab will use <TH>..</TH> markup whenever it determines that a$       cell forms part of the header.  J       AscToTab will attempt to automatically detect headers by looking for7       a single separator line near the top of the file.   @       Alternatively the HEADING_ROWS command (see 6.2.5) will be1       used to specify the number of header lines.   H       AscToTab will set the ALIGN and COLSPAN attributes as best it can.     5.4   <TD> statements   C       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, N       the first few columns will additionally use <STRONG>...</STRONG> markup.  H       AscToTab will set the ALIGN and COLSPAN attributes as best it can.    " 6     Customizing your conversions" ----------------------------------   6.1   Policy files  G       Policy files are an AscToHTM feature that are supported as of the A       integration between the two products that occurred in V2.3.   M       Not all of the policies recognised are relevant to AscToTab, but here's         a list of some that are :-  ( 	Descriptive text                 ValuesB 	------------------------------------------------------------------ 	Active Link Colour               HTML Colour - 	Background Colour                HTML Colour . 	Background Image                 URL of image/         Convert TABLE X-refs to links    Yes/No - 	Default TABLE border colour      HTML Colour 9 	Default TABLE border size        Number. 0 = "automatic" - 	Default TABLE caption            Text String 4 	Default TABLE cell padding       Number. 0 = "none"4 	Default TABLE cell spacing       Number. 0 = "none"- 	Default TABLE colour             HTML Colour 9 	Default TABLE header cols        Number. 0 = "automatic" 4 	Default TABLE header rows        Number. 0 = "none"@ 	Default TABLE width              Table width in pixels or as a  					 percentage of page width9 	Document Style Sheet             URL of style sheet file - 	Document description             Text string 6 	Document keywords                Comma-separated list- 	Document title                   Text string I 	HTML footer file                 File name.  File contains HTML commands I 	HTML header file                 File name.  File contains HTML commands ! 	Minimise HTML file size		 Yes/No 6 	TAB size                         Number of characters- 	Text Colour                      HTML Colour - 	Unvisited Link Colour            HTML Colour ( 	Use .HTM extension               Yes/No- 	Visited Link Colour              HTML Colour   L       Policy files are simply text files with a .pol extension by default.  K       Each is placed on a separate line with the policy phrase, a colon (:) J       and the value.  The .pol file is then specified as an extra argument$       on the command line (see 4.1).  4       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 convertedD 	Document keywords               : Keywords, included, in, META, tag $_$_END_PRE   N       Note, as of V3.0 it is possible to embed *any* policy line in the sourceN       document using the $_$_CHANGE_POLICY pre-processor command (see 6.2.11).     6.1.1 HTML Colours         *Section added in V3.0*   G       These policies identifies the colours to be placed in the various J       attributes of the <BODY> tag.  You can enter any value acceptable toL       HTML.  Normally a value is expressed as a 6-digit hexadecimal value inJ       the range 000000 (black) to FFFFFF (white), but certain colours suchM       as "white", "blue", "red" etc may also be recognised by HTML.  AscToTab 9       simply transcribes your value into the output file.   M       The various policies control the colours of the foreground Text (TEXT), O       the background (BGCOLOR), unvisited hyperlinks (LINK), visited hyperlinks ,       (VLINK) and active hyperlinks (ALINK).  H       A value of "none" signals the defaults are to be used.  By defaultK       AscToTab changes the background colour to be white, and omits all the "       other <BODY> tag attributes.     6.1.2 TABLE policies         *Section added in V3.0*   J       Most of the these policies are equivalent to pre-processor commands        described in section 6.2.   ' 	Default TABLE border colour      6.2.1 ' 	Default TABLE border size        6.2.1 ' 	Default TABLE cell padding       6.2.2 ' 	Default TABLE cell spacing       6.2.2 ' 	Default TABLE colour             6.2.3 ' 	Default TABLE caption            6.2.4 ( 	Default TABLE header rows        6.2.5 ( 	Default TABLE header cols        6.2.6 ' 	Default TABLE width              6.2.7 ' 	Minimum TABLE column separation	 6.2.8  	Expect Sparse tables		 6.2.9 /         Convert TABLE X-refs to links    6.2.10      6.1.3 Document policies    6.1.3.1 Document Style Sheet         *Section added in V3.0*   F       This policy allows you to specify the URL of a style sheet file,N       usually with a .css extension.  Style sheet files are a new HTML featureN       that allow you specify fonts and colours to be applied to your document.  J       The resulting HTML is inserted into the <HEAD> section of the output       page(s) as follows :-   9       	<LINK REL="STYLESHEET" HREF="URL" TYPE="text/css">      6.1.3.2 Document keywords          *Section added in V3.0*   D       This policy 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">   L       This tag is often used by search engines when indexing your HTML page.I       You should add here any relevant keywords possibly not contained in        the text itself.     6.1.3.3 Document description         *Section added in V3.0*   F       This policy allows you to specify a description of your documentI       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">   J       This tag is often used by search engines (e.g. AltaVista) as a briefI       description of the contents of your page.  If omitted the first few C       lines may be shown instead, which is often less satisfactory.      6.1.3.4 Document title         *Section added in V3.0*   J       AscToTab can calculate - or be told - the title of a document.  ThisJ       will be placed in <TITLE>...</TITLE> markup in the <HEAD> section of       each HTML page produced.  I       The Title is calculated as in the order shown below.  If the first	 A       algorithm returns a value, the subsequent ones are ignored.   >       1) If a $_$_TITLE pre-processor command is placed in the(          source text, that value is used  L       2) If the "Document title" policy is set (see 6.3.1.1) then this value          is used.   G       	 Note:  If this is the value you want, ensure the other policies &          	outlined above are disabled.  A       3) Finally, if none of the above result in a title the text ,       	 "Converted from <filename>" is used.     6.1.4 Other policies   6.1.4.1 HTML header          *Section added in V3.0*   L       This identifies the name of a text include file to be transcribed intoG       the HTML file at the top of the <BODY> ... </BODY> portion of the        generated HTML page.  K       This can be used to add standard headers, logos, contact addresses to J       your HTML pages, and is especially useful to give a consistent "look+       and feel" when converting many files.      6.1.4.2 HTML footer          *Section added in V3.0*   L       This identifies the name of a text include file to be transcribed intoJ       the HTML file at the bottom of the <BODY> ... </BODY> portion of the       generated HTML page.  F       This can be used to add "return to home page" links, and contactK       addresses to your HTML pages.  Again, this helps to give a consistenta1       "look and feel" when converting many files.a     6.1.4.3 TAB size         *New in V3.0*M  H       This value can be used to specify the size of TABs in your source M       document.  AscToTab converts all tabs to space assuming using this tab  N       size.  This becomes important only when comparing lines that use tabs toJ       lines that use spaces for alignment.  If problems occur you may findA       indentations appear strange, or tables are not quite right.m  J       Note, text that is all tabs or all spaces should experience no such        problems.   P       If you know your source file uses a different TAB size (e.g. Notepad files3       use a value of 4), try adjusting this policy.n     6.1.4.4 Minimise HTML file sizey         *New in V3.0*o  J       This policy may be used to reduce the size of the created HTML file.H       By default AscToTab attempts to layout the created HTML code in anL       easy-to-read manner.  This was done so that the created HTML would be -       easier to manually edit after creation.m  M       To make the code easier to read, AscToTab inserts white space to indent L       the code to match the output indentation levels.  It also outputs each&       cell of a TABLE on its own line.  D       All this white space adds up, particularly the indentation of I       largely-empty cells in TABLES.  If you select this option, all the a&       extra white space is eliminated.  O       Depending on the file contents, this can make the file 5-20% smaller (andh:       hence faster to download), at a cost of readability.     6.1.4.5 Use .HTM extension         *Section added in V3.0*a  O       This policy specifies whether or not the generated HTML files should havefJ       a .HTM extension.  The default is to use a ".html" extension, unless)       DOS-compatible files are requested.e     6.2   Preprocessor commandsw ----------------------------  L       The preprocessor is a feature shared with [AscToHTM].  Essentially youF       insert commands into your source file that tell AscToTab how you2       want various aspects of your file converted.  J       The preprocessor looks for lines that begin with a special characterN       sequence "$_$_".  All the AscToTab commands add "TABLE_" to this, makingK       the relevant prefix "$_$_TABLE_".  This sequence *must* appear at theTI       start of the source line with no leading white space.  Each commandu2       must be wholly contained on a separate line.  =       Commands are best placed at the top of the source file.      6.2.1 The BORDER command         $_$_TABLE_BORDER       5  2       This command specifies the BORDER attribute.        A value of 0 means "none".    . 6.2.2 The CELLSPACING and CELLPADDING commands  #       $_$_TABLE_CELLSPACING       5d#       $_$_TABLE_CELLPADDING       5e  I       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		AntiqueWhitep#       $_$_TABLE_BORDERCOLOR	#FF2345   F       These commands specify the values of the BGCOLOR and BORDERCOLOR       attributes.,     6.2.4 The CAPTION commandn  1       $_$_TABLE_CAPTION		Ooo! what a pretty table   J       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  J       This command tells AscToTab how many lines of text are to be treatedF       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  K       This command tells AscToTab how many columns (if any) at the start ofrC       each line should be marked up in <STRONG>...</STRONG> markup.e     6.2.7 The WIDTH command          $_$_TABLE_WIDTH	500-       $_$_TABLE_WIDTH	75%   J       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 2N  F       This command specifies the minimum number of spaces that may be J       interpreted as a column separator.  The default value is 1, but thisK       occasionally gives rise to too many "columns" - particularly in shorte7       tables, or columns whose data values are similar.n  0       A larger value will lead to fewer columns.    & 6.2.9 The TABLE_MAY_BE_SPARSE command          *New in V3.0*1         $_$_TABLE_MAY_BE_SPARSEn  K       This command specifies that the table may be sparse.  This fact will i7       then be used to adjust the analysis of the table.r  I       Columns which appear to have little or no data in them are usually aF       eliminated by merging them with their more populated neighbours.  P       If you use this command this process is relaxed, meaning that you will getA       more, emptier, columns rather than fewer, more filled ones.w    & 6.2.10 The TABLE_CONVERT_XREFS command         *New in V3.0*w  L       Although this affects table generation in AscToHTM, it's irrelevant in       AscToTab.o  P       This specifies whether numbers in tables should be converted to hyperlinksL       to numbered document sections.  Since AscToTab deals with single-tableI       files, there can be no numbered sections elsewhere in the document.0      6.2.11 The CHANGE_POLICY command         *New in V3.0*   D       This directive allows you set a policy in the document source.H       This allows you to effectively embed a policy file at the start of       your source file.   '       The syntax of the command line is   &       	$_$_CHANGE_POLICY <Policy Line>  O       where <Policy_line> is a policy line as it would appear in a policy file, )       and (usually) as it appears in 6.1.e  ;       For example the following would be a valid directives   
 $_$_BEGIN_PRE 0       	$_$_CHANGE_POLICY Background Colour : red<       	$_$_CHANGE_POLICY Document Title    : My pretty table $_$_END_PRE_          7     Purchasing AscToTabr -------------------------   2 7.1   How do I purchase AscToTab (trick question)?  L       You can't.  It's free.  Or rather its postcardware.  If you wish to beK       notified of updates or request support you have to send me a postcard L       with your email address.  I'll accept enquiries via email, but I still       want my postcard.   I       Thanks to all those that have sent cards to date.  Keep 'em coming.   8       It you really like the program, send a postcard to         	John A Fotheringham         c/o Yezerski Roper       	Applicon Housea       	Exchange Street       	Stockport       	SK3 0ET  	       	UKa  L       You could also look at [AscToHTM], which is a superset of the AscToTabH       functionality, i.e. it'll convert any document, using the AscToTab.       software to convert any tables it finds.  L       [AscToHTM] is shareware in the Windows version, but is free to OpenVMS        users and FAQ maintainers.     8     Contacts on the Web  -------------------------s   8.1   The home pager  K       At time of writing [Yezerski Roper] (whom I work for) have graciouslyh?       allowed me to give [AscToTab] and [AscToHTM] a home page.t  A       Yezerski Roper are the most intelligent software house it's J       ever been my privilege to be associated with.  We're based in the UKA       and offer OpenVMS and Windows NT systems, and are currentlyIE       developing state-of-the-art products which will allow companiessC       to exploit the full communications potential of the Internet.a  +       Oh yeah... and they pay me as well :)T  *       AscToTab and AscToHTM are "hobbies".  K       If you have problems locating the home page and suspect it has moved,s!       go to [AltaVista] and enter   (       		+"John A Fotheringham" +AscToTab  "       to locate any new home page.     8.2   E-mail  K       E-mail any feedback to jaf@yrl.co.uk.  Sadly, we cannot guarantee anyI       replies.    
 8.3   Support   I       A limited amount of support is available by emailing jaf@yrl.co.uk. M       Sadly, we cannot guarantee any replies, though we do try to be helpful.l     9     Known problems --------------------  !       None.  (Ignorance is bliss)n     10    Change History --------------------  ! 10.1  Version 1.00 (December '97).  J       Initial release of command line version as postcardware.  OriginallyM       the intention was to develope this as a separate shareware product, butaH       I've since decided to keep it postcardward (just so long as those        postcards keep coming).     ! 10.2  Version 2.00 (February '98)6  C       AscToTab is now integrated into [AscToHTM], and the bug fixesS8       and enhancements are released as V2.00 of AscToTab     10.3  Version 2.3 (April '98)t  J       AscToTab is now totally subsumed in [AscToHTM].  This allows it fullJ       access to the AscToHTM feature set.  In particular the command line J       interface is now the same, allowing wildcards and policy files to be       used.   M       New commands are added (see 6.2.7 and 6.2.8), and more improvements areh       made to the algorithms.a  K       From now on the AscToTab version numbers will indicate the release of-$       AscToHTM they are a subset of.     10.4  Version 3.0 (August '98)  8       Release synchronized with [AscToHTM] release V3.0.   10.4.1 Bug fixes  J       - The TABLE_HEADER_COLS directive only worked when there were header         rows as well.e  O       - Use of emphasis inside a TABLE cell was not being detected as all.  NowcM         it is detected if held on a single line.  Phrases that are emphasised I         over several lines inside a table cell may still not be detected.n   10.4.2 New functions  )       - New "TAB size" policy (see 6.1.4)a  O       - New "Expect sparse tables" policy and TABLE_MAY_BE_SPARSE pre-processor %         command (see 6.1.2 and 6.2.9)   8       - New "Minimise HTML file size" policy (see 6.1.4)  J       - New "Convert TABLE X-refs to links" policy and TABLE_CONVERT_XREFS4         pre-processor command (see 6.1.2 and 6.2.10)  <       - New CHANGE_POLICY pre-processor command (see 6.2.11)     10.4.3 Other changes  N       - Empty lines in a table cell now get an extra &nbsp; added, in additionL         to the <BR>.  This is to compensate for a bug in Internet Explorer 3K         which would ignore the <BR> otherwise, leading to alignment errors.c  M       - Improved handling of tables with long urls in them.  Previously these J         would not be recognised as part of a table.  Increased "long line"-         limit inside tables to 110 charactersy  H       - Improved detection of "mal-formed" tables.  Previously this was 2         over-cautious, especially on short tables.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          