size" (see 6.2.4.1) 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.
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
...
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 - ...
- ...
- ...
- ...
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
- ...
- ...
tag at the end of such lines to preserve the line structure of the original. 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. The emphasised word or phrase should span no more than a few lines. 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 later releases. 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 is 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 6.3.2.4) c) specifying the newsgroup hierarchy as recognised via a policy (see 6.3.2.5) 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 headers. Where headers 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
). Form feeds or page breaks also become
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 [section 7]). 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 chunks 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 (see 6.2.4.1). 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). 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). Of you can suppress the whole thing altogether (see 6.3.7.1). 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 6.3.6.11). Of you can suppress the whole thing altogether (see 6.2.1.13). 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
added to each line. 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
to any line it deems to be short. If omitted, a "short" line is determined as some fraction of the calculated page width. The fraction varies from 50-75% according to the conversion type being carried out. 6.2.1.13 "Expect code samples" This policy indicates that the document is liable to contain sections of programming code. AscToHTM will attempt to detect such code fragments, and preserve their layout so that the code remains comprehensible. Pre-processor commands now allow you to mark up sections of your document as code samples (see 7.1.5). You can choose how code fragments are marked up by using the "Use
.. markup" policy (see 6.3.6.11)
6.2.2 Bullet policies
AscToHTM has the following bullet point policies that will normally be
correctly calculated on the analysis pass :-
[Bullets]
---------
Expect Numbered bullets Yes
Expect alphabetic bullets No
Expect Roman Numeral bullets No
Bullet Char '-'
Bullet Char 'o'
Bullet Char '*'
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.2.1 "Expect Numbered bullets"
This indicates that numerical bullets are expected (but you probably
guessed that).
6.2.2.2 "Expect alphabetic bullets"
This does likewise for alphabetic bullet points.
AscToHTM recognises (and distinguishes between) upper and lower case
variants.
6.2.2.3 "Expect Roman Numeral bullets"
This does likewise for roman numerals. Again upper and lower case
variants are recognised.
6.2.2.4 "Bullet Char"
These policy lines indicate character(s) that can occur at the start of
a line to represent a bullet point. Special attention is paid to
'-' and 'o' characters, but any character will do.
Use one line per bullet char.
6.2.3 Headings
AscToHTM has the following section heading policies that will normally be
correctly calculated on the analysis pass :-
[Headings]
----------
First Section Number 1
Expect Numbered Headings No
Expect Underlined Headings Yes
Expect Capitalised Headings No
Expect Second Word Headings No
Smallest possible section number 1.1.0
Largest possible section number 2.4.9
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 in 6.2.3.8, but this will probably change in future
releases.
6.2.3.1 "First Section Number"
This policy indicates what the first section number is.
Normally this starts at 1, but if it starts higher, then AscToHTM may
reject headers as being out of sequence, and fail to detect to presence
or absence of contents lists correctly.
6.2.3.2 "Expect Numbered Headings"
This indicates whether or not numbered sections are to be expected.
6.2.3.3 "Expect Underlined Headings"
This indicates whether or not underlined headers are to be expected.
AscToHTM normally promotes any underlined lines to section headers.
This policy can be used to switch that behaviour off.
6.2.3.4 "Expect Capitalised Headings"
This indicates whether or not a line that is wholly capitalised should
be regarded as a section heading.
6.2.3.5 "Expect Second Word Headings"
*Reserved*
6.2.3.6 "Smallest possible section number"
*Reserved*
6.2.3.7 "Largest possible section number"
*Reserved*
6.2.3.8 "xxxx level 1 = "" N.N at indent 2"
*Note, this is not finalised yet*
These lines describe in readable text form part of the headings policy.
You can edit these lines in your policy file, but not yet 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.4 Pre-formatted text
AscToHTM has the following section heading policies that will normally be
correctly calculated on the analysis pass :-
[Pre-formatted text]
-------------------------------------
Minimum automatic size (none)
6.2.4.1 "Minimum automatic size"
This policy specifies the minimum number of lines that must appear
pre-formatted before they can be placed in their own ...
sections.
This is sometimes desirable, so is set to 1 by default. For example
if you have lines with page numbers at the top of each page in your
document. Of course... this makes no sense in an HTML document.
Note: Only values in the range 1-20 are likely to have an effect.
Values above 20 are likely to simply disable this feature
entirely. This limitation is due to the size of the
readahead buffer AscToHTM uses.
6.2.4.2 "Minimum TABLE column separation"
This policy specifies the minimum number of spaces that may be interpreted
as a column separator in a table.
The default value is 1, but in small tables this can lead to too many
"columns" being detected. If you experience this problem increase this
value to 2 or higher.
Note, if the value becomes too large, you may experience the opposite
problem, i.e. too *few* columns being detected.
6.2.4.3 "Expect sparse tables"
*New in V3.0*
This policy specifies that tables within the source document may be
sparse. This fact will then be used to adjust the analysis of any tables
detected
Columns which appear to have little or no data in them are usually
eliminated by merging them with their more populated neighbours.
If you set this policy, this process is relaxed, meaning that you will get
more, emptier, columns rather than fewer, more filled ones.
This policy can be toggled for individual tables via the pre-processor
command TABLE_MAY_BE_SPARSE (see 7.4).
6.2.5 Contents List policies
There is only one analysis contents policy ("Expect contents list"
see 6.3.4.2).
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
These policies allow you to fine tune the conversion, and are used
during the output to HTML.
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 :-
[Added HTML]
------------
Document title AscToHTM user documentation
Use first heading as title No
Use first line as title No
Document keywords text, html, conversion
Document description Part of the AscToHTM user documentation
HTML Script file a2hdocos.txt
HTML header file a2hdocoh.txt
HTML footer file a2hdocof.txt
Background Image (none)
Background Colour E0D0E0
Text Colour Red
Unvisited Link Colour (none)
Visited Link Colour (none)
Active Link Colour (none)
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.1.1 "Document Title"
This identifies the text to be placed in the ... markup
in the document header.
If omitted, the default title will be "Converted from ".
We did consider defaulting to the first line of text, but that rarely
works.
The title can also be specified via a preprocessor command (see 7.2.1)
placed in the source document, which will override this policy when
present.
To fully understand how titles are calculated, see the discussion in 5.6.1
6.3.1.2 "Use first heading as title"
This policy specifies that the first heading in the document may be
considered as a candidate for the document title.
In the current version (V2.3) there may be implementation problems that
cause the wrong line to occasionally be selected as the first heading.
To fully understand how titles are calculated, see the discussion in 5.6.1
6.3.1.3 "Use first line as title"
This policy specifies that the first meaningful line in the document may
be considered as a candidate for the document title. "Meaningful"
in this context means more that 2 characters long once trimmed of all
leading and trailing white space.
To fully understand how titles are calculated, see the discussion in 5.6.1
6.3.1.4 "Document keywords"
This policy allows you to specify keywords that are added to a
META tag inserted into the section of the output
page(s) as follows :-
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 will overrides this
policy (see 7.2.3).
6.3.1.5 "Document description"
This policy allows you to specify a description of your document
that is added to a META tag inserted into the section of the
output page(s) as follows :-
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 will override any
description specified in a policy file (see 7.2.2).
6.3.1.6 "HTML Script file"
This identifies the name of a text include file to be transcribed into
the ... portion of the generated HTML page.
This allows you to place JavaScript in your pages (though you'll be a
little limited as to what it can act on).
Recently HTML has introduced style sheets (see 6.3.6.1 and 7.2.4).
6.3.1.7 "HTML header"
This identifies the name of a text include file to be transcribed into
the HTML file at the top of the ... portion of the
generated HTML page.
This can be used to add standard headers, logos, contact addresses to
your HTML pages, and is especially useful to give a consistent "look
and feel" when breaking your document up into a number of smaller
HTML files.
6.3.1.8 "HTML footer"
This identifies the name of a text include file to be transcribed into
the HTML file at the bottom of the ... portion of the
generated HTML page.
This can be used to add "return to home page" links, and contact
addresses to your HTML pages. Again, this helps to give a consistent
"look and feel" when breaking your document up into a number of smaller
HTML files.
6.3.1.9 "Background Image"
This identifies the URL of any image to be placed in the BACKGROUND
attribute of the tag.
6.3.1.10 Various colour policies
These policies identifies the colours to be placed in the various
attributes of the tag. You can enter any value acceptable to
HTML. Normally a value is expressed as 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.
The various policies control the colours of the foreground Text (TEXT),
the background (BGCOLOR), unvisited hyperlinks (LINK), visited hyperlinks
(VLINK) and active hyperlinks (ALINK).
A value of "none" signals the defaults are to be used. By default
AscToHTM changes the background colour to be white, and omits all the
other tag attributes.
6.3.2 Hyperlinks
AscToHTM has the following hyperlink policies set as defaults :-
[Hyperlinks]
------------
Create hyperlinks No
Create mailto links Yes
Create NEWS links Yes
Only use known groups Yes
Recognised USENET groups uk demon
Cross-refs at level 2
Hyperlinks can also be added by using a link dictionary (see 4.3.2.2
and 4.4.2).
6.3.2.1 "Create hyperlinks"
This policy really means that all http, www and ftp URLs will
get converted to hyperlinks.
6.3.2.2 "Create mailto links"
This indicates that probable email addresses such as jaf@yrl.co.uk
are to be converted into mailto hyperlinks.
6.3.2.3 "Create NEWS links"
This indicates that probable newsgroup references such as
alt.games.mornington.cresent (sic) are to be converted.
6.3.2.4 "Only use known groups"
This indicates whether or not only newsgroups from known hierarchies
should be converted into news: hyperlinks.
AscToHTM can detect possible newsgroups by looking for words like
"something.like.this" and "news.answers". However assuming these
are newsgroups often leads to errors.
Consequently if this policy is set to "Yes" then candidate newsgroups
have to belong to either a standard USENET hierarchy such as "alt",
"comp", "sci" etc, or to a user-specified USENET hierarchy (see 6.3.2.5)
If set to no, then "something.like.this" will be turned into a
news: hyperlink.
This policy only takes effect if conversion of news hyperlinks is
selected.
The defaults is "Yes"
6.3.2.5 "Recognised USENET groups"
This policy allows you to specify USENET hierarchies that you wish to
recognise in addition to the standard hierarchies. The value is a space
separated list of the top level hierarchy names. So, for example, to
ensure that uk.telecom and demon.ip.support are recognised as
valid newsgroup hyperlinks, set the policy value as follows:-
Recognised USENET groups : uk demon
This has, of course, been used on the HTML version of this file to get
the above links to work :-)
6.3.2.6 "Cross-refs at level"
This indicates the section level at which and above which all
cross-references are to be converted to hyperlinks.
For example a value of 2 means all n.n, n.n.n etc references are
converted. A value of "1" might seem desirable, but is liable to
give many false references (see 5.3.2).
This behaviour may be improved in later versions.
6.3.2.7 "Add
to lines with URLs"
*New in V3.0*
This policy indicates that lines that are detected as having URLs in them
should have
markup added to the end. This is useful in documents
that have a list of URLs, one per line, as the URLs usually make the
lines quite long (avoiding short line detection), and you would want to
preserve the line structure.
However, this is less useful where URLs occur in the middle of a
paragraph of text, as it inserts a
, and breaks the paragraph.
Prior to V3.0 this was default behaviour, but now it is switched off by
default.
In later versions we may attempt to make this policy auto-detected.
6.3.3 File generation
AscToHTM has the following HTML policies that will only ever take effect
if supplied in a user policy file :-
[File generation]
-----------------
Input directory (none)
Output directory (none)
Use .HTM extension No
Output file extension (none)
Use DOS filenames No
DOS filename root (none)
Split level (none)
Min HTML File size (none)
Minimise HTML file size No
Add navigation bar No
Output policy file Yes
Output policy filename (none)
Generate diagnostics files No
Error reporting level 5
These policies 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.3.1 "Input directory"
*Reserved for future use*
This policy will allow the source directory to be specified. It is
not yet implemented, but currently the input directory is written to
any output policy file created, indicating where the source files
where found relative to the run location.
A value of blank indicates the current directory.
6.3.3.2 "Output directory"
*Not available in the shareware version*
This policy allows you to specify which directory you want your files
output to.
If an output policy file is created, this indicates where the generated
files where placed relative to the run location.
A value of blank indicates the current directory.
6.3.3.3 "Use .HTM extension"
This policy specifies whether or not the generated HTML files should have
a .HTM extension. The default is to use a ".html" extension, unless
DOS-compatible files are requested.
6.3.3.4 "Output file extension"
*New in V3.0*
This policy specifies an alternative extension to be used for the created
files. For example you may want the program to create ".shtml" files.
If present, this policy overrides that in 6.3.3.3
6.3.3.5 "Use DOS filenames"
This policy allows you to specify that the HTML file names must be
DOS compatible.
If selected the filenames will all have a ".HTM" extension, and be
given upper case names.
Any file name whose root exceeds 8 character will be shortened by
keeping the first 3 characters, and adding a unique 5-digit number
derived from the longer name.
See the discussion in 4.2.2.4.
6.3.3.6 "DOS filename root"
Where DOS filenames are used this allows you to specify an up-to-5
character root to which any section numbers will be appended
(see 6.3.3.8).
If splitting a document at 2 levels we normally recommend a 3-character
filename root.
Thus MYDOC.TXT given a root of MYD would produce MYD.HTM, MTD_1.HTM
MYD_1_1.HTM etc... which are all less than 8 characters and thus
maintain some readability.
If no root were specified, MYDOC_1_1.HTM would be renamed to
MYDnnnnn.HTM where "nnnnn" would be a generated 5-digit code.
See the discussion in 4.2.2.4.
6.3.3.7 "Minimise HTML file size"
*New in V3.0*
This policy may be used to reduce the size of the created HTML file.
By default AscToHTM attempts to layout the created HTML code in an
easy-to-read manner. This was done so that the created HTML would be
easier to manually edit after creation.
To make the code easier to read, AscToHTM inserts white space to indent
the code to match the output indentation levels. It also outputs each
cell of a TABLE on its own line.
All this white space adds up, particularly the indentation of
largely-empty cells in TABLES. If you select this option, all the
extra white space is eliminated.
Depending on the file contents, this can make the file 5-20% smaller (and
hence faster to download), at a cost of readability.
6.3.3.8 "Split level"
This identifies the heading level at which the generated HTML should
be split into smaller files.
A value of "none" will put all the HTML into one file.
A value of "1" will create a new HTML file for each new major section.
A value of "2" will create a new HTML file for each new n.n section,
whilst "3" creates a new document for each n.n.n section, and so on.
The first file created normally has a name that matches the source file.
Subsequent files append the section number, separated by underscores.
This a file called MYDOC.TXT, will generate MYDOC.HTML, MYDOC_1.HTML,
MYDOC_1_1.HTML etc...
6.3.3.9 "Min HTML File size"
This policy is only relevant when splitting the document into small
output files, i.e. a "split level" is specified (see 6.3.3.8).
This policy specifies a minimum output HTML size in lines (although
this is only approximate).
This can be useful for documents that have chapters where all the
content is in the sub-sections. In such documents you'd end up
with a virtually empty chapter heading file if this policy is not
used.
6.3.3.10 "Add navigation bar"
This policy is only relevant if you have elected to split your document
into a number of smaller HTML files (see 6.3.3.8).
In such cases this policy allows you have a navigation bar inserted at
the foot of each HTML page, before any standard footer is added.
The navigation bar consists of
- A "Previous" link, to take to the previous HTML page.
- A "Next" link, to take to the next HTML page.
- A "Contents" link, to take to the start of the next section in the
contents list.
6.3.3.11 "Output policy file"
This policy allows you to specify that you want AscToHTM to output the
file policy that is being used. This will be a combination of the
policy calculated by AscToHTM during the analysis pass, and any
user-supplied policy lines.
The output policy file will have a .pol extension in the output
directory.
Note_1: In earlier versions of AscToHTM the creation of an output
policy file was the default, now it is not.
Note_2: This policy has the same effect as the command line qualifier
/POLICY (see 4.2.2.5). An output file will be create when
either that qualifier is used, or this policy is set to
yes.
6.3.3.12 "Output policy filename"
**** not supported in this release ****
6.3.3.13 "Generate diagnostics files"
This policy specifies whether or not diagnostics files should be
produced. This has exactly the same effect as the /DEBUG qualifier
has in command line versions (see 4.2.2.2).
6.3.3.14 "Error reporting level"
*New in V3.0*
This policy specifies the level of reporting you want during the
conversion. AscToHTM can generate a variety of messages of varying
severity to inform you of the decisions it's made. These messages
can be useful in explaining why a conversion has gone wrong, but are
less interesting at other times.
Whilst all of these messages are copied into any .lis files created
(see 6.3.3.13 and 4.2.2.2) regardless of severity, you can use this
policy to choose the level of reporting you want to see on your screen.
The value is nominally in the range 1-10 with a value of 1 showing almost
all messages, and 10 showing almost none. The default value is 5.
6.3.4 Contents
AscToHTM has the following HTML policies that influence the detection
and generation of contents lists :-
[Contents]
----------
Add contents list No
Expect Contents List No
Use any existing contents list No
Generate external contents file No
External contents list filename (none)
Hyperlinks on numbers No
See also the discussion in 5.6.2
6.3.4.1 "Add contents list"
This policy specifies that AscToHTM should generate a contents list
to match all the section heading that it marks up. This contents
list will consist of hyperlinks to take you to the corresponding
section and HTML file.
The placement of the contents list depends on how you have decided to
split up your output HTML (see 6.3.3.8).
If you decide to convert MYDOC.TXT to a single HTML file MYDOC.HTML,
AscToHTM will create a separate file called CONTENTS_MYDOC.HTML and
add a link to this file at the top of MYDOC.HTML. You can, if you
wish, simply cut and paste this file into MYDOC.HTML.
If you decide to convert MYDOC.TXT into several files, then the
contents list is placed at the bottom of MYDOC.HTML, and points to
all the newly created files. Any text before the first section
in your document will be placed before the contents list in MYDOC.HTML.
Whenever you elect to have a contents list generated, and lines perceived
by AscToHTM as being part of a contents list in the original document
will be discarded.
You can enable this option from the command line by using the
/CONTENTS qualifier (see 4.2.2.1)
6.3.4.2 "Expect contents list"
This is an analysis policy that indicates whether or not the source file
contains an existing contents list.
This should be detected automatically, but sometimes the analysis fails
in which case you should either set this manually, or mark up
the contents list using pre-processor commands (see 7.1.3)
See the discussion in 5.6.2.
6.3.4.3 "Use any existing contents list"
This policy specifies whether or not you wish to use any existing contents
list found in the source document. If you disable this option, any
contents found will be discarded. A contents list will only be added
if you select the "add contents list" policy (see 6.3.4.1).
See the discussion in 5.6.2.
6.3.4.4 "Generate external contents file"
This policy specifies whether any generated contents list should be placed
in a separate file, as opposed to at the top of the output file.
This option is not always possible, specifically when an existing
contents list is being used, or when the source is being split into
many files.
See the discussion in 5.6.2.
6.3.4.5 "External contents list filename"
This is the name of the external content file generated by AscToHTM
should such a file be wanted.
By default the file will be called contents_.html.
The contents file should be in the same directory as the created
HTML files.
See the discussion in 5.6.2.
6.3.4.6 "Hyperlinks on numbers"
This policy specifies that where a file has numbered sections, and
a contents list is being created, whether the hyperlink taking you
to the section should be on the number or the section title.
The default is to place the hyperlink on the section title.
6.3.5 Preprocessor policies
AscToHTM has the following policies that can be used to influence
the preprocessor (see [section 7]), and hence the HTML output :-
[Preprocessor]
--------------
Use Preprocessor Yes
Include document section(s) Public_part
6.3.5.1 "Use Preprocessor"
This policy tells AscToHTM whether or not the preprocessor should be
used. If it isn't used, then all preprocessor directives are ignored
and a straight conversion from input to output files occurs.
Note: If this policy is set to "no", all related preprocessor
policies will have no effect.
6.3.5.2 "Include document section(s)"
*Changed in V2.3*
This policy tells AscToHTM which section types are to be included
in the conversion (see 7.1.1). The name(s) supplied should match that
in the SECTION directive.
A value of "all" indicates that all section types should be converted.
The value may be a space-separated list of section names. Each section
name must be a single word (underscores are allowed though).
6.3.6 Style
AscToHTM has the following "styling" that can be used to influence
the HTML output :-
[Style]
-------
Document Style Sheet text.css
Highlight Definition Text No
Allow automatic centring No
Automatic centring tolerance 2
Smallest allowed tag 5
Largest allowed tag 2
Headings colour #ABABAB
Ignore multiple blank lines No
Search for emphasis Yes
Allow definitions inside PRE Yes
Use markup for defn. paras Yes
Use .. markup No
6.3.6.1 "Document style sheet"
This policy 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 section of the output
page(s) as follows :-
The presence of a STYLE_SHEET pre-processor command will overrides any
style sheet specified in a policy file (see 7.2.4).
6.3.6.2 "Highlight definition text"
This policy specifies whether or not the definition
term (the part marked up in - ...
) should be placed in bold
for greater emphasis (see 5.1.5).
6.3.6.3 "Use markup for defn. paras"
This policy specifies whether or not definition paragraphs should
be marked up using - ..
-
- ..
markup.
See the discussion in 5.1.5.2
6.3.6.4 "Allow automatic centring"
This policy allows automatic detection of centred text to be performed.
This is normally left switched off, as it is prone to give errors. This
algorithm may be refined in later versions.
6.3.6.5 "Automatic centring tolerance"
This policy specifies the tolerance used (expressed as a number of
characters offset) when detecting centred text.
Given that the detection of centred text depends on its position relative
to the calculated page width, which itself may not be accurate, increasing
this value may give better results. Equally, if may wrongly detect more
text as centred.
The default value is 2, which is also used as a minimum regardless of
the value you enter.
6.3.6.6 "Largest allowed tag" and "Smallest allowed tag"
These policies control the output heading sizes. By default is
used for main level headings, with each subsequent heading level being
one size smaller, down to (normal text size).
In the contents list, entries are shown down to .
The software will ignore these values if out of range, or if the largest
value represents a smaller heading (larger Hn) that the "smallest" value.
6.3.6.7 "Headings colour"
*New in V3.0*
This policy tells AscToHTM what colour to use for all the Headers.
Not all browsers support this.
The value must be a proper HTML colour (see discussion in 6.3.1.10)
6.3.6.8 "Ignore multiple blank lines"
This policy specifies whether or not multiple white lines should be
ignored.
Normally HTML ignores white space, but if this policy is selected then
additional blank lines will be marked us as
If you wish to eliminate white space from your output, switch this
off. You should also review the "Use
markup for paragraphs" policy
(see 6.3.6.12).
This policy is switched on by default.
6.3.6.9 "Search for emphasis"
This policy specifies whether or not AscToHTM should look for emphasised
text. Text can be emphasised by placing asterisks (*) either side
of it, or underscores (_). AscToHTM will convert the enclosed text
to bold and italic respectively.
6.3.6.10 "Allow definitions inside PRE"
This policy specifies whether or not AscToHTM should detect definition
terms inside a pre-formatted section of text. Only really relevant
if the "Highlight definition text" policy is selected (6.3.6.2).
6.3.6.11 "Use .. markup"
This policy specifies that where a code fragment has been detected or
marked up, what sort of HTML markup should be used.
HTML provides a special .. markup that is suited to
variables being quoted in text, but is not well suited for marking up
several lines. In particular, you have to add non-breaking spaces
and
markup if you wish to correctly lay out several lines. This
makes the resultant HTML harder to read and much larger.
For this reason, AscToHTM defaults to
..
markup for code
fragments. The only reason for reversing this might be if you needed
the tag for a particular style sheet to take effect.
6.3.6.12 "Use markup for paragraphs"
This policy specifies whether
or
markup should be used for
paragraphs. In most browsers
markup produces more white space
with apparently a "blank line" placed between paragraphs. A
doesn't have this effect.
You should use this policy if you wish to reduce the amount of white
space in your output document, in which case you should also review
the "ignore multiple blank lines" policy (see 6.3.6.8).
This policy is switched on by default.
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)
[Table generation]
-------------------------------------
Attempt TABLE generation Yes
Default TABLE border size 2
Default TABLE header rows (none)
Default TABLE header cols (none)
Default TABLE cell spacing 2
Default TABLE cell padding 2
Default TABLE colour (none)
Default TABLE border colour Blue
Default TABLE caption (none)
Convert TABLE X-refs to links No
6.3.7.1 "Attempt TABLE generation"
This policy disables automatic table generation. AscToHTM will still
look for pre-formatted text, but will default to outputting it in
...
markup as it did prior to v2.2.
6.3.7.2 "Default TABLE border size"
This policy sets the default value for the BORDER attribute. A value of
0 means "no border".
6.3.7.3 "Default TABLE header rows"
This policy tells AscToHTM how many lines should be treated as header
lines and placed in .. markup.
AscToHTM will a small number of lines of text above a line as header
automatically.
If set, this value will apply to *all* tables.
6.3.7.4 "Default TABLE header cols"
This policy tells AscToHTM how many columns in each table should be
highlighted as "header" columns using ... markup inside the
table cells.
6.3.7.5 "Default TABLE cell spacing"
This policy tells AscToHTM what value to use for the CELLSPACING attribute
of the table. Browsers that support this will add space *between* each
cell.
A value of "0" means "none".
6.3.7.6 "Default TABLE cell padding"
This policy tells AscToHTM what value to use for the CELLPADDING attribute
of the table. Browsers that support this will add space *inside* each
cell.
A value of "0" means "none".
6.3.7.7 "Default TABLE colour"
This policy tells AscToHTM what colour to use for the background to each
cell. Not all browsers support this.
The value must be a proper HTML colour (see 6.3.1.10)
6.3.7.8 "Default TABLE border colour"
This policy tells AscToHTM what colour to use for the table border.
Not all browsers support this.
The value must be a proper HTML colour (see 6.3.1.10)
6.3.7.9 "Default TABLE caption"
*Reserved*
6.3.7.10 "Default TABLE width"
This policy tells AscToHTM what value to use for the WIDTH attribute
of the table.
The WIDTH is specified either as a number (of pixels) or as a percentage
(of screen width). Thus "400" and "75%" are both valid values (without
the quotes)
Note: If you use this policy, *all* your tables will be the
same width. If you wish to switch it on for individual
tables, place $_$_TABLE_WIDTH commands (see 7.4) in your
source file instead.
6.3.7.11 "Convert TABLE X-refs to links"
*New in V3.0*
AscToHTM can convert cross-references to numbered sections into hyperlinks
to those sections. Unfortunately, the program cannot differentiate
between section references and ordinary numbers in the source text. This
leads to occasional errors.
This problem proved to be particularly acute inside tables of numbers.
For that reason this policy was introduced to allow the conversion of
section numbers to hyperlinks inside a TABLE to be switched off
independently form the rest of the document.
By default this policy is disabled. Users should only switch this
behaviour on if they have a table of section numbers (such as this
document has in 11.1 and 11.2).
6.3.7.12 Other table related policies
Also relevant to table production are policies which influence the
detection of pre-formatted text :-
- "Minimum automatic size" (see 6.2.4.1)
- "Minimum TABLE column separation" (see 6.2.4.2 and 7.4)
- "Expect sparse tables" (see 6.2.4.3 and 7.4)
6.3.8 Link Dictionary
Link definitions appear as follows :-
[Link Dictionary]
-----------------
Link definition : "A2HDOCO.TXT" = "Source text" + "/~jaf/A2HDOCO.TXT"
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.
[Directory]
---------------------------------------------------
Make Directory Yes
Directory filename (none)
Show file titles in Directory Yes
Indent headings in Directory Yes
Directory title List of files
Directory keywords (none)
Directory description Directory index of my files
Directory return hyperlink text Return to index
Directory Script file (none)
Directory header file (none)
Directory footer file (none)
6.3.9.1 "Make Directory"
This policy specifies whether or not you want a Directory page built.
6.3.9.2 "Directory filename"
This policy specifies the name of the Directory page html file to be
created.
If omitted, this will default to "index.html" in the output directory
6.3.9.3 "Show file titles in Directory"
This policy specifies whether or not there should be a hyperlink to
the top of each file converted (as opposed to just their contents).
If selected, the HTML file's title (see 5.6.1) will be shown as a
hyperlink. If the file has no title, then the original filename is
shown instead.
6.3.9.4 "Indent headings in Directory"
This policy specifies whether or not the contents lists of each file
should be shown at multiple indent levels, with sub-sections indented
relative to sections etc.
If disabled, all the contents hyperlinks will be at the same indentation
level, one level in from any file titles shown.
6.3.9.5 "Directory title"
This specifies the text to be used as the HTML title of the Directory
page.
6.3.9.6 "Directory keywords"
This policy allows you to specify keywords that are added to a
META tag inserted into the section of the Directory page
as follows :-
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.
6.3.9.7 "Directory description"
This policy allows you to specify a description of your document
that is added to a META tag inserted into the section of the
Directory page(s) as follows :-
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.
6.3.9.8 "Directory return hyperlink text"
This policy specifies the text to be shown on the hyperlink linking
each HTML page back to the Directory page.
The default value is "Directory"
6.3.9.9 "Directory Script file"
This identifies the name of a text include file to be transcribed into
the ... portion of the generated HTML page.
This allows you to place JavaScript in your pages (though you'll be a
little limited as to what it can act on).
If omitted, this will default to any script file used in the rest of
the HTML pages as set by the "HTML Script file" policy (see 6.3.1.6).
6.3.9.10 "Directory header file"
This identifies the name of a text include file to be transcribed into
the HTML file at the top of the ... portion of the
Directory page.
If omitted, this will default to any header file used in the rest of
the HTML pages as set by the "HTML header file" policy (see 6.3.1.7).
6.3.9.11 "Directory footer file"
This identifies the name of a text include file to be transcribed into
the HTML file at the bottom of the ... portion of the
generated HTML page.
This can be used to add "return to home page" links, and contact
addresses to your HTML pages.
If omitted, this will default to any header file used in the rest of
the HTML pages as set by the "HTML header file" policy (see 6.3.1.8).
6.4 Saving and loading policy files
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 "Output policy file" policy (see 6.3.3.11)
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 "Output policy file" policy is set (see 6.3.3.11), the
generated "full" policy file is usually called
.pol
where 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_.pol or i.pol
or place your input policies in a different directory and ensure they
are backed up.
$_$_TABLE_WIDTH
7 Using the preprocessor
----------------------------
The preprocessor is introduced in version V1.05. It is intended to
allow users more flexibility in the HTML they generate, and as such
moves AscToHTM towards being a HTML authoring tool, as opposed to a
simple text conversion or migration tool. This wasn't AscToHTM's
original purpose, and so - as yet - it's a little functionally poor
in this area.
Likely future additions include the insertion of embedded HTML in the
output code. This would allow pictures to be embedded.
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 such 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.
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 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).
The presence of this directive overrides any value set in the
"Attempt table generation" policy (see 6.3.7.1)
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
$_$_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.
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 ...
markup or
... markup (see 6.3.6.11). For reasons discussed
in 6.3.6.11 the former is 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 ...
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.2 Commands that influence the .. of a file
7.2.1 The TITLE command
This directive allows you to specify the ... to be inserted
into the 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.1, 6.3.1.2 and 6.3.1.3).
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 section of the
output page(s) as follows :-
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 in a policy file (see 6.3.1.5).
7.2.3 The KEYWORDS command
This directive allows you to specify keywords that are added to a
META tag inserted into the section of the output
page(s) as follows :-
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 in a policy file (see 6.3.1.4).
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 section of the output
page(s) as follows :-
The presence of a STYLE_SHEET pre-processor command will overrides any
style sheet specified in a policy file (see 6.3.6.1).
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.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_BORDER Number Size of border. 0 = None
TABLE_BORDERCOLOR Colour Colour of border
TABLE_BGCOLOR Colour Colour of background
TABLE_CAPTION Text Table caption. Added centred at
the top
TABLE_CELLSPACING Number Spacing between cells.
TABLE_CELLPADDING Number Padding inside each cell
TABLE_CONVERT_XREFS (none) If present, indicates that any section
cross-references in the table may
be converted to hyperlinks
(see 6.3.7.11)
TABLE_HEADER_ROWS Number Number of header rows. These
will be placed in .. 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 6.2.4.3)
TABLE_MIN_COLUMN_SEPARATION Number Number of spaces to be taken as a
column separator when analysing the
table (see 6.2.4.2).
TABLE_WIDTH Text The width of the table (see 6.3.7.10)
$_$_END_TABLE
Colours must be in the HTML accepted format (see 6.3.1.10).
7.5 The CHANGE_POLICY command
*New in V3.0*
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
where is a policy line as it would appear in a policy file,
and (usually) as it appears in sections 11.1 and 11.2 of this document.
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).
8 Purchasing AscToHTM
-------------------------
8.1 Why should I purchase AscToHTM?
You need a reason? What kind of a skinflint are you?
Oh well... here are some reasons to register :-
- 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.
- 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
8.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 random 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.
8.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.
**
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.
* *
If you really want a free copy, buy an OpenVMS system :) If you find
any for less than $35, let me know :)
8.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 jaf@yrl.co.uk with
details. Currently most registrations result in an email from Jaf
anyway.
9 Contacts on the Web
-------------------------
9.1 The home page
At time of writing [Yezerski Roper] (whom I work for) have graciously
allowed me to give 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 :)
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 E-mail
E-mail any feedback to jaf@yrl.co.uk. Sadly, we cannot guarantee any
replies. OTOH, no-one who has ever emailed us has ever waited more than
a day for a response (no holidays, you see :)
9.3 Support
A limited amount of support is available to registered users by
emailing jaf@yrl.co.uk. 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.
Over time a user's FAQ may appear. This will only be available to
registered users.
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 jaf@yrl.co.uk. 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.
- If the program gets confused when splitting a large file, it may
accidentally use the same output file name twice, possibly losing
your data.
- 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
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 Policy Dictionary
--------------------
Here is a complete list of all the policy phrases that may occur in policy
files, and links to their explanations :-
11.1 Analysis policies
These policies influence AscToHTM's analysis. Usually AscToHTM will calculate
values for each of these policies, or use sensible defaults. Should the
analysis be wrong for any reason, you can change these policy values to correct
the conversion.
Descriptive text Reference Values
-----------------------------------------------------------------
Bullet Char 5.1.3.1 and 6.2.2.4 '-' (one entry per
character)
Definition Char 5.1.5 and 6.2.1.3 '-' (strong)
Expect alphabetic bullets 5.1.3.3 and 6.2.2.2 Yes/No
Expect blank lines between paras 6.2.1.8 Yes/No
Expect Capitalised Headings 5.4.2 and 6.2.3.4 Yes/No
Expect code samples 6.2.1.13, 6.3.6.11 Yes/No
and 7.1.5
Expect Contents List 3.3.2, 4.2.2.1, Yes/No
4.4.3 and 6.3.4.2
Expect Numbered bullets 5.1.3.2 and 6.2.2.1 Yes/No
Expect Numbered Headings 5.4.1 and 6.2.3.2 Yes/No
Expect Roman Numeral bullets 5.1.3.4 and 6.2.2.3 Yes/No
Expect Second Word Headings - Yes/No
Expect sparse tables 6.2.4.3 and 7.4 Yes/No
Expect Underlined Headings 5.4.3 and 6.2.3.3 Yes/No
Hanging paragraph position(s) 5.1.2 and 6.2.1.4 List of ascending
space-separated numbers
Indent position(s) 6.2.1.1 List of ascending
space-separated numbers
Keep it simple 4.2.2.4 and 6.2.1.10 Yes/No
Min chapter size 6.2.1.11 Number of lines
Minimum automatic size 5.5.3 and 6.2.4.1 Number of lines
Minimum TABLE column separation 6.2.4.2 and 7.4 Number of spaces
Search for Definitions 6.2.1.2 Yes/No
Search for emphasis 6.3.6.9 Yes/No
Short line length 6.2.1.12 Number of characters
TAB size 6.2.1.6 Number of characters
Text Justification 6.2.1.7 left/right/centre
11.2 Output policies
These policies are used to shape the HTML generated. You can change these
policies to get the HTML generated looking like you want it to.
Descriptive text Reference Values
-----------------------------------------------------------------
Active Link Colour 6.3.1.10 HTML Colour
Add
to lines with URLs 6.3.2.7 Yes/No
Add contents list 3.3.2, 4.2.2.1 Yes/No
4.4.3 and 6.3.4
Add navigation bar 6.3.3.10 Yes/No
Allow automatic centring 5.3.9 and 6.3.6.4 Yes/No
Allow definitions inside PRE 5.1.5 and 6.3.6.10 Yes/No
Attempt TABLE generation 6.3.7.1 Yes/No
Automatic centring tolerance 6.3.6.5 Number of characters
Background Colour 6.3.1.10 HTML Colour
Background Image 6.3.1.9 URL of image
Convert TABLE X-refs to links 6.3.7.11 and 7.4 Yes/No
Create NEWS links 5.3.4 and 6.3.2.3 Yes/No
Create hyperlinks 5.3.3 and 6.3.2.1 Yes/No
Create mailto links 5.3.5 and 6.3.2.2 Yes/No
Cross-refs at level 5.3.2 and 6.3.2.6 Number. 0 = "none"
DOS filename root 4.2.2.3, 4.3.2.4 up-to-5 character name
and 6.3.3.5
Default TABLE border colour 6.3.7.8 and 7.4 HTML Colour
Default TABLE border size 6.3.7.2 and 7.4 Number. 0 = "automatic"
Default TABLE caption 6.3.7.9 and 7.4 Text String
Default TABLE cell padding 6.3.7.6 and 7.4 Number. 0 = "none"
Default TABLE cell spacing 6.3.7.5 and 7.4 Number. 0 = "none"
Default TABLE colour 6.3.7.7 and 7.4 HTML Colour
Default TABLE header cols 6.3.7.4 and 7.4 Number. 0 = "automatic"
Default TABLE header rows 6.3.7.5 and 7.4 Number. 0 = "none"
Default TABLE width 6.3.7.10 and 7.4 Table width in pixels
or as a percentage of page
width
Directory description 6.3.9.7 Text String
Directory filename 6.3.9.2 Output filename
Directory footer file 6.3.9.11 File name. File contains
HTML commands
Directory keywords 6.3.9.6 Text String
Directory header file 6.3.9.10 File name. File contains
HTML commands
Directory return hyperlink text 6.3.9.8 Text String
Directory Script file 6.3.9.9 File name. File contains
HTML commands
Directory title 6.3.9.5 Text String
Document Style Sheet 6.3.6.1 and 7.2.4 URL of style sheet file
Document description 6.3.1.5 and 7.2.2 Text string
Document keywords 6.3.1.4 and 7.2.3 Comma-separated list
Document title 6.3.1.1 and 7.2.1 Text string
Error reporting level 6.3.3.14 Number in range 1-10
External contents list filename 6.3.4.5 File name
Generate diagnostics files 4.2.2.2 and 6.3.3.13 Yes/No
Generate external contents file 6.3.4.4 Yes/No
Headings colour 6.3.6.7 HTML Colour
HTML Script file 6.3.1.6 File name. File contains
HTML commands
HTML footer file 6.3.1.8 File name. File contains
HTML commands
HTML header file 6.3.1.9 File name. File contains
HTML commands
Highlight Definition Text 5.1.5.1 and 6.3.6.2 Yes/No
Hyperlinks on numbers 5.3.1 and 6.3.4.6 Yes/No
Ignore multiple blank lines 6.3.6.8 Yes/No
Include file 4.3.2.3 Name of a policy file
to be included
Include document section 6.3.5.2 and 7.1.1 Space-separated list of
section names
Indent headings in Directory 6.3.9.4 Yes/No
Input directory 6.3.3.1 Directory name
Make Directory 6.3.9.1 and 4.2.2.6 Yes/No
Min HTML File size 6.3.3.9 Number of lines
Minimise HTML file size 6.3.3.7 Yes/No
Only use known groups 5.3.4 and 6.3.2.4 Yes/No
Output directory 6.3.3.2 Directory name
Output file extension 6.3.3.4 Text String
Output policy file 4.2.2.5 and 6.3.3.11 Yes/No
Output policy filename 6.3.3.12 File name
Recognised USENET groups 6.3.2.5 space-separated list of
USENET hierarchies
Search for emphasis 6.3.6.9 Yes/No
Show file titles in Directory 6.3.9.3 Yes/No
Split level 3.3.3 and 6.3.3.8 Number
Text Colour 6.3.1.10 HTML Colour
Unvisited Link Colour 6.3.1.10 HTML Colour
Use .HTM extension 6.3.3.3 Yes/No
Use .. markup 6.2.1.13, 6.3.6.11 Yes/No
and 7.1.5
Use
markup for defn. paras 5.1.5.2 and 6.3.6.3 Yes/No
Use markup for paragraphs 6.3.6.12 Yes/No
Use any existing contents list 6.3.4.3 Yes/No
Use DOS filenames 4.3.2.4 and 6.3.3.5 Yes/No
Use first heading as title 6.3.1.2 Yes/No
Use first line as title 6.3.1.3 Yes/No
Use Preprocessor 6.3.5.1 and Yes/No
[Section 7]
Visited Link Colour 6.3.1.10 HTML Colour
12 Change History
--------------------
12.1 Version 1.01 (April '97)
New functions
- Added the /CONTENTS qualifiers (see 4.2.2.1).
- Added the /SIMPLE qualifier (see 4.2.2.4).
12.2 Version 1.04 (early July '97)
12.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.
12.2.2 New functions
- Added policy "Minimum automatic
size" (see 6.2.4.1). This
replaces the policy "Allow automatic 1-line "
- Added policies "Largest allowed tag" and "Smallest allowed
tag" (see 6.3.6.6) to allow control over generated heading
sizes.
- Added policy "Short line length" (see 6.2.1.12)
- Added Batch processing to allow multiple files to be converted at
the same time. (see 4.3.3.2)
12.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)
12.3 Version 1.05 (late July '97)
12.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.
12.3.2 New functions
- Added an "Output directory" policy (see 6.3.3.2). 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 "Output policy" policy (see 6.3.3.11). This allows the
suppression of output policy files where not wanted.
- Added a "Expect code samples" policy (see 6.2.1.13). 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 [section 7])
12.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
's forced on the end.
Lines with http, ftp and news links still do. This will become
fully configurable in later versions.
12.4 Version 1.1 (August '97)
12.4.1 Bug fixes
- Several hyperlink parsing errors fixed. Previously there were
problems with punctuation around links, email addresses with
protocols (e.g. MX%"jaf@yrl.co.uk") 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.
12.4.2 New functions
- Added a "Only use known groups" policy (see 6.3.2.4) to improve accuracy
of newsgroup hyperlink detection.
- Added more document colour policies (see 6.3.1.10)
- Added a /POLICY and "Output Policy file" option (see 6.3.3.11
and 4.2.2.5) to make the generation of an output policy file optional
- Added preprocessor support for user-formatted sections (see 7.1.7)
12.4.3 Other changes
- Indentation is now done using markup.
- Changed default background colour to white (see 6.3.1.10).
- Generation of a .pol file is no longer default (see 6.3.3.11
and 4.2.2.5)
- The use of ...
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.2) now has error and information messages
included in it.
12.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.
12.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
12.5.2 New functions
- New "Output policy filename" policy (see 6.3.3.1)
- New "Use .HTM extension" policy (see 6.3.3.3)
- New "Generate diagnostics files" policy (see 6.3.3.13)
- New "External contents list filename" policy (see 6.3.4.5)
- New "Use markup for defn. paras" policy (see 6.3.6.3)
- New "Ignore multiple blank lines" policy (6.3.6.8)
- New "Search for emphasis" policy (see 6.3.6.9)
- New "Allow definitions inside PRE" policy (see 6.3.6.10)
- 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)
12.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.
12.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).
12.6.1 Bug fixes
- Fixed "Minimum automatic 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 missing.
- Fixed occasional "Invalid indent -1" error
12.6.2 New functions
- New "Document keywords" policy (see 6.3.1.4) and pre-processor KEYWORDS
command (see 7.2.3).
- New "Document description" policy (see 6.3.1.5) and pre-processor
DESCRIPTION command (see 7.2.2).
- New "Hyperlinks on Numbers" contents policy (see 6.3.4.6)
- New "Document style sheet" policy (see 6.3.6.1) and pre-processor
STYLE_SHEET command (see 7.2.4).
12.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 .. 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.
12.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.
12.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.
12.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 Description
-------------------------------------------
Attempt TABLE generation 6.3.7.1
Default TABLE border size 6.3.7.2
Default TABLE header rows 6.3.7.3
Default TABLE header cols 6.3.7.4
Default TABLE cell spacing 6.3.7.5
Default TABLE cell padding 6.3.7.6
Default TABLE colour 6.3.7.7
Default TABLE border colour 6.3.7.8
Default TABLE caption 6.3.7.9
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 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)
12.7.3 Other changes
_Documentation_
- Added the [PolDict], 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.
12.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.
12.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. 12.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.
12.8.2 New functions
_Windows Version_
- Added a "Preform simple conversion" tick box on the front panel.
This does exactly the same as the "Keep it simple" policy (see 6.2.1.10)
- 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.3.2).
Includes new "Use any existing contents list" and "Generate external
contents file" (see 6.3.4.4 and 6.3.4.3). More changes are expected
here in later versions.
- New Directory Page feature (see 6.3.9)
New Policies Description
-------------------------------------------
Make Directory 6.3.9.1
Directory filename 6.3.9.2
Show file titles in Directory 6.3.9.3
Indent headings in Directory 6.3.9.4
Directory title 6.3.9.5
Directory keywords 6.3.9.6
Directory description 6.3.9.7
Directory return hyperlink text 6.3.9.8
Directory Script file 6.3.9.9
Directory header file 6.3.9.10
Directory footer file 6.3.9.11
- New "Minimum TABLE column separation" policy and
TABLE_MIN_COLUMN_SEPARATION pre-processor command (see 6.2.4.2 and 7.4)
to allow some tuning of table analysis.
- New "Use first heading as title" policy (see 6.3.1.2)
- New "Use first line as title" policy (see 6.3.1.3)
- New "Recognised USENET groups" policy (see 6.3.2.5)
- New "Automatic centring tolerance" policy (see 6.3.6.5)
- New "Use markup for paragraphs" policy (see 6.3.6.12), to allow
choice of either
or
markup to be used for paragraphs.
- New "Default table width" policy and TABLE_WIDTH pre-processor
command (see 6.3.7.10 and 7.4) to allow table widths to be specified
- New pre-processor command HTML_LINE (see 7.3.2)
12.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 (see 6.3.5.2) 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 [section 5] 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 :^)
12.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 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 a little details. 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.
12.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
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.
- "Expect code samples" policy (see 6.2.1.13) 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 as 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 s being
spilt when they're near the natural break.
- Pre-processor command $_$_TITLE was being ignored if the "Use
first heading as title" policy was set.
12.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 "Search for Definitions" policy (see 6.2.1.2)
- New "TAB size" policy (see 6.2.1.6)
- New "Expect sparse tables" policy and TABLE_MAY_BE_SPARSE pre-processor
command (see 6.2.4.3 and 7.4)
- New "Add
to lines with URLs" policy (see 6.3.2.7)
- New "Output file extension" policy (see 6.3.3.4)
- New "Minimise HTML file size" policy (see 6.3.3.7)
- New "Headings colour" policy (see 6.3.6.7). Eventually I hope to add
a whole suite of heading styling options, as these have been requested
by a number of people.
- New "Convert TABLE X-refs to links" policy and TABLE_CONVERT_XREFS
pre-processor command (see 6.3.7.11 and 7.4)
- New CHANGE_POLICY pre-processor command (see 7.5)
- New "Error reporting level" policy (see 6.3.3.14)
12.9.3 Other changes
- Improved Windows interface
- Empty lines in a table cell now get an extra added, in addition
to the
. This is to compensate for a bug in Internet Explorer 3
which would ignore the
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.yrl.co.uk). 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
$_$_END_PRE
- With the introduction of the "Add
to lines with URLs" policy
(see 6.3.2.7), this behaviour is no longer default. That is, if you
*do* want
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 "Convert TABLE X-refs to links" policy
(see 6.3.7.11), 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 "Use DOS
filenames" policy selected (see 6.3.3.5)