is the name of
the document being converted.
5.6.2.3 Contents lists in conversions to multiple HTML files
AscToHTM can be made to split the output into many files. At present
this is only possible at detected section headings. Each generated
page usually has a navigation bar, which includes a hyperlink back
to the following section in any contents list.
The behaviour is identical to that in 5.6.2.2 expect that
a) the output is now split into several files.
b) the options to generate an external contents list in a separate
file are no longer available.
c) if the contents list is being generated, it is now placed at the
foot of the first document, rather than at the top (unless the
CONTENTS_LIST preprocessor command is used)
This is usually *before* the first heading (which now starts the
second document), and *after* any document preamble.
Note: Where the original contents list is used when splitting files
it is possible that not every file is directly accessible
from the contents list, and that the back links to the contents
list may not function as expected. In such cases you can
go from the contents list to a major section, and then use
the navigation bars to page through to the minor section.
5.6.2.4 Contents lists in conversions to frames
*New in version 4*
Contents list generation for the main document will proceed as described
in the previous sections.
When making a set of frames, you can elect to have a contents
frame generated (the default behaviour), and this will have a
generated list placed in a frame on the left. This can mean you
have a contents list in the contents frame on the left, and also
at the top of the first page in the main document. For this reason the
main frame often starts by displaying the second page.
The number of levels shown in the contents frame list can be controlled
by policy. Alternatively you can replace the whole contents of the
contents frame by defining a CONTENTS_FRAME [HTML fragment].
5.6.3 Directory page
When converting several files at once, AscToHTM can be made to generate
a "Directory Page". This is an HTML index of all the files converted
and their contents.
The policies available for controlling generation of a directory
page are explained in "[[GOTO Directory Page policies]]".
The directory page will consist of an entry for each file converted,
in the order that files are converted (usually alphabetic). Each entry
will (optionally) contain :-
- A link to the file being converted. The link will either be the
converted file's HTML title, or failing that, the filename itself.
- Links to each of the sections of the converted file as detected
by AscToHTM.
5.6.4 Headers, footers and JavaScript
AscToHTM can be made to add standard header, footers and JavaScript to
each page generated. It does this by allowing you to specify include
files to be copied into the generated HTML. These include files can
contain any valid HTML commands.
The program supports three types of such files :-
i) Header files. These contain any HTML you want placing immediately
after the output's tag.
A good example might be a standard header, with a logo and links
back to the home page.
ii) Footer files. These contain any HTML you want placing immediately
before the closing tag.
iii) Script files, These contain any HTML you want placing inside
the ... portion of the generated file. Such tags
are not usually visible.
You should place in here any JavaScript you want, although it
is difficult to make this apply to the converted text.
You can specify include files for the converted files, as well as for any
directory page (see 5.6.3) that you create. If you don't specify values
for the directory page, then it will use the same files as the generated
files.
HTML headers and footers can also be defined as [HTML fragments]
(see 5.6.5).
5.6.5 HTML fragments
*New in version 4*
The "HTML fragments" feature allows you to define a block of
HTML that you can elect to have used in place of the default HTML
that the program would generate.
Some reserved names are recognised by the software and used to
override the default HTML that is generated. For example the fragment
HORIZONTAL_RULE can be used to define a ![]()
tag that displays an
image and which will be used in a number of situations where a simple
tag would have been used otherwise.
They are described fully in the Tag Manual (see [HTML fragments]).
$_$_TABLE_WIDTH 60%
6 Using Document Policy files
---------------------------------
*This chapter has been largely superceded by the [Policy Manual]*
Document policy files are ordinary text files that list the "policies"
that AscToHTM should implement when converting your document. The
file can have added comment lines (starting with a "!" or "#" character)
and headings for clarity.
A summary of the recognised policy lines is given in the [Policy manual].
In most cases recognised policy lines are identical to those listed in
the generated policy file (see 4.1). This is usually a good place to
start when making your own policy.
Only those lines that are recognised policies are acted upon.
To use a policy file, simply list it on the command line after the
name of the file being converted (see 4.2.2.3).
Document policies have two main uses :
a) To correct any failure of analysis that AscToHTM makes. Hopefully
this won't be needed too much as the core analysis engine improves.
Examples include page width, whether or not underlined section
headings are expected etc.
b) To tell the program how to produce better HTML end product in ways
that couldn't possibly be inferred from the original text.
Examples include adding colour and titles to the page, as well
as requesting a large document is split into several pages, and
a contents list created.
The document sections in this chapter that described the policies in detail
have been moved to a standalone document called the "[Policy Manual]".
That document describes the scope, effect, location and default values
for all policies recognised by the program.
6.1 An example conversion
This documentation has itself been converted using AscToHTM. The
files used were
- a2hdoco.txt. This is the text version of the documentation. The
text version is kept as the master copy and updated as required.
It's then converted to HTML.
- ia2hdoco.pol. This is the policy file used to create the HTML version
of this document. Only those policies that differ from the defaults
have been added.
This policy file "includes" the link dictionary A2HLINKS.DAT.
- a2hlinks.dat. This is the link dictionary used for this document
and is used to add hyperlinks to the main text file.
- html_fragments.inc. This file contains the definitions of the
[HTML fragments] used in this conversion.
These files are included in the distribution kit as an example
set of documentation.
You can, of course, use AscToHTM to convert this doco into whatever
format, colour etc that you wish.
6.2 Analysis policies
These policies are used to control and correct the analysis of files
during conversion. Full descriptions of these policies can be
found in the [Policy Manual].
6.2.1 Overview ("look for") policies
The following analysis policies help give you an overview of what the
program is looking for, and to enable/disable what is being looked for.
[[HYPERLINK POLICY,"Look for indentation"]] [[BR]]
[[HYPERLINK POLICY,"Look for hanging paragraphs"]] [[BR]]
[[HYPERLINK POLICY,"Look for white space"]] [[BR]]
[[HYPERLINK POLICY,"Look for short lines"]] [[BR]]
[[HYPERLINK POLICY,"Look for horizontal rulers"]] [[BR]]
[[HYPERLINK POLICY,"Minimum ruler length"]] [[BR]]
[[HYPERLINK POLICY,"Look for bullets"]] [[BR]]
[[HYPERLINK POLICY,"Search for definitions]] [[BR]]
[[HYPERLINK POLICY,"Look for quoted text"]] [[BR]]
[[HYPERLINK POLICY,"Look for MAIL and USENET headers"]] [[BR]]
[[HYPERLINK POLICY,"Look for preformatted text"]] [[BR]]
[[HYPERLINK POLICY,"Attempt TABLE generation"]] [[BR]]
[[HYPERLINK POLICY,"Look for diagrams"]]
6.2.2 General Layout policies
The following analysis policies help control general layout parameters:-
[[HYPERLINK POLICY,"Page width"]] [[BR]]
[[HYPERLINK POLICY,"TAB size"]] [[BR]]
[[HYPERLINK POLICY,"Short line length"]] [[BR]]
[[HYPERLINK POLICY,"Min chapter size"]] [[BR]]
[[HYPERLINK POLICY,"Expect blank lines between paras"]] [[BR]]
[[HYPERLINK POLICY,"Hanging paragraph position(s)"]] [[BR]]
[[HYPERLINK POLICY,"Search for Definitions"]] [[BR]]
[[HYPERLINK POLICY,"New Paragraph Offset"]] [[BR]]
[[HYPERLINK POLICY,"Definition Char"]] [[BR]]
[[HYPERLINK POLICY,"Indent position(s)"]] [[BR]]
6.2.3 Bullet policies
AscToHTM has the following bullet point policies that will normally be
correctly calculated on the analysis pass :-
[[HYPERLINK POLICY,"Look for bullets"]]
[[HYPERLINK POLICY,"Expect alphabetic bullets"]] [[BR]]
[[HYPERLINK POLICY,"Expect numbered bullets"]] [[BR]]
[[HYPERLINK POLICY,"Expect roman numeral bullets"]]
[[HYPERLINK POLICY,"Recognise '-' as a bullet"]] [[BR]]
[[HYPERLINK POLICY,"Recognise 'o' as a bullet"]] [[BR]]
[[HYPERLINK POLICY,"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.4 Contents analysis policies
There is only one analysis contents policy:-
[[HYPERLINK POLICY,"Expect contents list"]]
This is described together with all the output contents list policies
in [[GOTO Contents generation policies]]
For more information on content list generation see 5.6.2.
6.2.5 File Structure policies
AscToHTM has the following file structure policies that will normally be
need to be set manually :-
[[HYPERLINK POLICY,"Keep it simple"]]
[[HYPERLINK POLICY,"Expect code samples"]] [[BR]]
[[HYPERLINK POLICY,"Input file contains DOS characters"]] [[BR]]
[[HYPERLINK POLICY,"Input file contains MIME encoding"]] [[BR]]
[[HYPERLINK POLICY,"Input file contains PCL codes"]] [[BR]]
[[HYPERLINK POLICY,"Input file contains Japanese characters"]] [[BR]]
[[HYPERLINK POLICY,"Input file has change bars"]] [[BR]]
[[HYPERLINK POLICY,"Input file has page markers"]] [[BR]]
[[HYPERLINK POLICY,"Page marker size (in lines)"]] [[BR]]
[[HYPERLINK POLICY,"Text Justification"]] [[BR]]
[[HYPERLINK POLICY,"Input file is double spaced"]]
6.2.6 Heading policies
AscToHTM has the following section heading policies that will normally be
correctly calculated on the analysis pass :-
[[HYPERLINK POLICY,"Expect Numbered Headings"]] [[BR]]
[[HYPERLINK POLICY,"Expect Underlined Headings"]] [[BR]]
[[HYPERLINK POLICY,"Expect Capitalised Headings"]] [[BR]]
[[HYPERLINK POLICY,"Expect Embedded Headings"]] [[BR]]
[[HYPERLINK POLICY,"Heading key phrases"]]
[[HYPERLINK POLICY,"Check indentation for consistency"]]
[[HYPERLINK POLICY,"Expect Second Word Headings"]] [[BR]]
[[HYPERLINK POLICY,"First Section Number"]] [[BR]]
[[HYPERLINK POLICY,"Smallest possible section number"]] [[BR]]
[[HYPERLINK POLICY,"Largest possible section number"]] [[BR]]
[[HYPERLINK POLICY,"Preserve underlining of headings"]]
Section headers are far and away the most complex things the analysis
pass has to detect, and the most likely area for errors to occur.
AscToHTM will also document to a policy file the headings it finds.
This is still to be finalised, but currently has the format
$_$_BEGIN_PRE
We have 4 recognised headings
Heading level 0 = "" N at indent 0
Heading level 1 = "" N.N at indent 0
Contents level 0 = "" N at indent 0
Contents level 1 = "" N.N at indent 2
$_$_END_PRE
AscToHTM will read in such lines from a policy text file, but does not
yet fully supported editing these via the Windows interface.
The syntax is explained below, but this will probably change in future
releases. You can edit these lines in your policy file, and through
the policy options in Windows.
The lines are currently structured as follows
$_$_BEGIN_TABLE
Line component Value
--------------------------------------------
xxxx Either "Heading" or "Contents" according
to the part of the policy being described
Level n Level number, starting at 0 for chapters
1 for level 1 headings etc.
"Some_word" Any text that may be expected to occur before
the heading number. E.g. "Chapter" or "Section"
or "[". The case is unimportant.
N.Nx The style of the heading number. This will
ultimately (in later versions) be read
as a series of number/separator pairs.
The proposed format is
"N" = number
"i" / "I" = lower/upper case roman numeral
with an 'x' at the end signalling that trailing
letters may be expected (e.g. 5.6a, 5.6b)
at indent n The indentation that this heading is expected
at. This is important in helping to eliminate
false candidates.
$_$_END_TABLE
6.2.7 Pre-formatted text policies
AscToHTM has the following section heading policies that will normally be
correctly calculated on the analysis pass :-
[[HYPERLINK POLICY,"Minimum automatic size"]]
6.2.8 Table analysis policies
*New in version 4*
AscToHTM uses the following policies to control the detection and
analysis of tables :-
[[HYPERLINK POLICY,"Attempt TABLE generation"]]
[[HYPERLINK POLICY,"Table extending factor"]]
[[HYPERLINK POLICY,"Expect sparse tables"]] [[BR]]
[[HYPERLINK POLICY,"Ignore table header during analysis"]] [[BR]]
[[HYPERLINK POLICY,"Column merging factor"]] [[BR]]
[[HYPERLINK POLICY,"Minimum TABLE column separation"]]
[[HYPERLINK POLICY,"Default TABLE layout"]] [[BR]]
[[HYPERLINK POLICY,"Tables could be blank line separated"]]
6.3 Output policies
These policies are used to output and generation of files
during conversion. Full descriptions of these policies can be
found in the [Policy Manual].
6.3.1 Added HTML policies
AscToHTM has the following HTML policies that will only ever take effect
if supplied in a user policy file :-
[[HYPERLINK POLICY,"Use first heading as title"]] [[BR]]
[[HYPERLINK POLICY,"Use first line as title"]] [[BR]]
[[HYPERLINK POLICY,"Document title"]]
[[HYPERLINK POLICY,"Document description"]] [[BR]]
[[HYPERLINK POLICY,"Document keywords"]] [[BR]]
[[HYPERLINK POLICY,"Background Image"]] [[BR]]
[[HYPERLINK POLICY,"HTML header file"]] [[BR]]
[[HYPERLINK POLICY,"HTML footer file"]] [[BR]]
[[HYPERLINK POLICY,"HTML Script file"]]
[[HYPERLINK POLICY,"Omit and from output"]] [[BR]]
[[HYPERLINK POLICY,"Document Base URL"]] [[BR]]
[[HYPERLINK POLICY,"Comment generation code"]] [[BR]]
[[HYPERLINK POLICY,"HTML fragments file"]]
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.1)
6.3.2 Cascading Style sheet policies (CSS)
*New in version 4*
AscToHTM has the following HTML policies that influence the use
of CSS in the HTML generated :-
[[HYPERLINK POLICY,"Document Style Sheet"]]
Not visible in the user interface is :-
[[HYPERLINK POLICY,"Create embedded style sheet"]] [[BR]]
6.3.3 Contents generation policies
AscToHTM has the following HTML policies that influence the detection
and generation of contents lists :-
[[HYPERLINK POLICY,"Expect Contents List"]] [[BR]]
[[HYPERLINK POLICY,"Add contents list"]] [[BR]]
[[HYPERLINK POLICY,"Maximum level to show in contents"]]
[[HYPERLINK POLICY,"Use any existing contents list"]]
[[HYPERLINK POLICY,"Generate external contents file"]] [[BR]]
[[HYPERLINK POLICY,"External contents list filename"]]
[[HYPERLINK POLICY,"Hyperlinks on numbers"]] [[BR]]
See also the discussion in 5.6.2
6.3.4 Document Colour policies
*New in version 4*
AscToHTM has a large number of HTML policies that can control the
colouring of the files. These policies are spread across a number
of areas of functionality.
_General_
[[HYPERLINK POLICY,"Suppress all colour markup"]]
[[HYPERLINK POLICY,"Active Link Colour"]] [[BR]]
[[HYPERLINK POLICY,"Background Colour"]] [[BR]]
[[HYPERLINK POLICY,"Text Colour"]] [[BR]]
[[HYPERLINK POLICY,"Unvisited Link Colour"]] [[BR]]
[[HYPERLINK POLICY,"Visited Link Colour"]]
_Frames_
[[HYPERLINK POLICY,"Header frame background colour"]] [[BR]]
[[HYPERLINK POLICY,"Header frame text colour"]] [[BR]]
[[HYPERLINK POLICY,"Contents frame background colour"]] [[BR]]
[[HYPERLINK POLICY,"Contents frame text colour"]] [[BR]]
[[HYPERLINK POLICY,"Footer frame background colour"]] [[BR]]
[[HYPERLINK POLICY,"Footer frame text colour"]]
_Tables_
[[HYPERLINK POLICY,"Colour data rows"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE border colour"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE colour"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE even row colour"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE odd row colour"]]
6.3.5 Directory Page policies
AscToHTM has the following policies that can be used to influence
whether or not AscToHTM will attempt to generate a Directory page
for the files being converted. This is really only appropriate when
converting more that one file at once (see 4.3.3)
The Directory Page will consist of entries for each file being
converted (in order of conversion), and can have hyperlinks to the
files, and to recognised headings in the files. This makes it suitable
for use as a master index to a set of files converted in a single
directory.
[[HYPERLINK POLICY,"Make Directory"]] [[BR]]
[[HYPERLINK POLICY,"Indent headings in Directory"]] [[BR]]
[[HYPERLINK POLICY,"Show file titles in Directory"]] [[BR]]
[[HYPERLINK POLICY,"Directory filename"]]
[[HYPERLINK POLICY,"Directory title"]] [[BR]]
[[HYPERLINK POLICY,"Directory description"]] [[BR]]
[[HYPERLINK POLICY,"Directory keywords"]] [[BR]]
[[HYPERLINK POLICY,"Directory return hyperlink text"]]
[[HYPERLINK POLICY,"Directory header file"]] [[BR]]
[[HYPERLINK POLICY,"Directory footer file"]] [[BR]]
[[HYPERLINK POLICY,"Directory script file"]]
6.3.6 File generation policies
AscToHTM has the following HTML policies that affect the file generation
process :-
[[HYPERLINK POLICY,"Input directory"]] [[BR]]
[[HYPERLINK POLICY,"Output directory"]] [[BR]]
[[HYPERLINK POLICY,"Use .HTM extension"]] [[BR]]
[[HYPERLINK POLICY,"Output file extension"]]
[[HYPERLINK POLICY,"Preserve file structure using "]] [[BR]]
[[HYPERLINK POLICY,"Preserve line structure"]] [[BR]]
[[HYPERLINK POLICY,"Treat each line as a paragraph"]]
[[HYPERLINK POLICY,"Generate diagnostics files"]] [[BR]]
[[HYPERLINK POLICY,"Output policy file"]] [[BR]]
[[HYPERLINK POLICY,"Output policy filename"]] [[BR]]
[[HYPERLINK POLICY,"DOS filename root"]] [[BR]]
[[HYPERLINK POLICY,"Use DOS filenames"]] [[BR]]
[[HYPERLINK POLICY,"Split level"]] [[BR]]
[[HYPERLINK POLICY,"Min HTML File size"]] [[BR]]
[[HYPERLINK POLICY,"Add navigation bar"]] [[BR]]
[[HYPERLINK POLICY,"Minimise HTML file size"]] [[BR]]
[[HYPERLINK POLICY,"Break up long HTML lines"]] [[BR]]
These policies specify how your document is divided into one or more HTML
files, and how those files are to be named and linked together with
hyperlinks.
6.3.7 Font policies
AscToHTM supports the implementation of fonts via either Cascading
style sheets (CSS) or via the tag.
Related policies are :-
[[HYPERLINK POLICY,"Use CSS to implement fonts"]] [[BR]]
[[HYPERLINK POLICY,"Default font"]]
6.3.8 Frames policies
*New in version 4*
From version [[TEXT 4]] onwards AscToHTM will support the output of HTML
as a set of HTML FRAMES. A large number of policies support this
process.
_General_
[[HYPERLINK POLICY,"Place document in frames"]]
[[HYPERLINK POLICY,"Output frame name"]]
[[HYPERLINK POLICY,"Add Frame border"]]
[[HYPERLINK POLICY,"Open frame links in new window"]] [[BR]]
[[HYPERLINK POLICY,"New frame link window name"]]
[[HYPERLINK POLICY,"Add NOFRAMES links"]] [[BR]]
[[HYPERLINK POLICY,"NOFRAMES link URL"]]
_Header and Footer frame policies_
[[HYPERLINK POLICY,"Use main header in header frame"]] [[BR]]
[[HYPERLINK POLICY,"Header Frame depth"]]
[[HYPERLINK POLICY,"Use main footer in footer frame"]] [[BR]]
[[HYPERLINK POLICY,"Footer Frame depth"]]
_Contents frame_
[[HYPERLINK POLICY,"Add contents frame if possible"]] [[BR]]
[[HYPERLINK POLICY,"Contents Frame width"]] [[BR]]
[[HYPERLINK POLICY,"Number of levels in contents frame"]]
_Main Frame_
[[HYPERLINK POLICY,"Split level"]] [[BR]]
[[HYPERLINK POLICY,"Min HTML File size"]] [[BR]]
[[HYPERLINK POLICY,"First frame page number"]]
_Frame colours_
[[HYPERLINK POLICY,"Header frame background colour"]] [[BR]]
[[HYPERLINK POLICY,"Header frame text colour"]] [[BR]]
[[HYPERLINK POLICY,"Contents frame background colour"]] [[BR]]
[[HYPERLINK POLICY,"Contents frame text colour"]] [[BR]]
[[HYPERLINK POLICY,"Footer frame background colour"]] [[BR]]
[[HYPERLINK POLICY,"Footer frame text colour"]]
6.3.9 Hyperlink policies
AscToHTM has the following hyperlink policies set as defaults :-
[[HYPERLINK POLICY,"Create hyperlinks"]] [[BR]]
[[HYPERLINK POLICY,"Create mailto links"]] [[BR]]
[[HYPERLINK POLICY,"Allow email beginning with numbers"]] [[BR]]
[[HYPERLINK POLICY,"Check domain name syntax"]]
[[HYPERLINK POLICY,"Create gopher links"]] [[BR]]
[[HYPERLINK POLICY,"Create FTP links"]] [[BR]]
[[HYPERLINK POLICY,"Only allow explicit FTP links"]]
[[HYPERLINK POLICY,"Create NEWS links"]] [[BR]]
[[HYPERLINK POLICY,"Only use known groups"]] [[BR]]
[[HYPERLINK POLICY,"Recognised USENET groups"]]
[[HYPERLINK POLICY,"Add
to lines with URLs"]]
[[HYPERLINK POLICY,"Cross-refs at level"]]
[[HYPERLINK POLICY,"Open link in new browser window"]] [[BR]]
[[HYPERLINK POLICY,"new browser window name"]]
Hyperlinks can also be added by using a link dictionary (see 4.3.2.2
and 4.4.2).
6.3.10 Link Dictionary policies
Link definitions appear in a policy file as follows :-
$_$_BEGIN_PRE
[Link Dictionary]
-----------------
Link definition : "a2hdoco.txt" = "Source text" + "/~jaf/A2HDOCO
$_$_END_PRE
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.11 Preprocessor policies
AscToHTM has the following policies that can be used to influence
the preprocessor (see [[GOTO Using the preprocessor]]), and hence the HTML output :-
[[HYPERLINK POLICY,"Use Preprocessor"]] [[BR]]
[[HYPERLINK POLICY,"Include document section(s)"]]
[[HYPERLINK POLICY,"Allow definitions inside PRE"]]
6.3.12 HTML styling policies
AscToHTM has the following "styling" that can be used to influence
the HTML output :-
[[HYPERLINK POLICY,"Allow automatic centring"]] [[BR]]
[[HYPERLINK POLICY,"Automatic centring tolerance"]] [[BR]]
[[HYPERLINK POLICY,"Ignore multiple blank lines"]] [[BR]]
[[HYPERLINK POLICY,"Highlight definition text"]] [[BR]]
[[HYPERLINK POLICY,"Use markup for defn. paras"]] [[BR]]
[[HYPERLINK POLICY,"Largest allowed tag"]] [[BR]]
[[HYPERLINK POLICY,"Smallest allowed tag"]] [[BR]]
[[HYPERLINK POLICY,"Headings colour"]] [[BR]]
[[HYPERLINK POLICY,"Preserve underlining of headings"]]
[[HYPERLINK POLICY,"Search for emphasis"]]
[[HYPERLINK POLICY,"Use and markup"]]
[[HYPERLINK POLICY,"Preserve New Paragraph Offset"]]
Also, not available in the user interface is :-
[[HYPERLINK POLICY,"First line indentation (in blocks)"]]
6.3.13 Table Generation policies
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.1.4)
[[HYPERLINK POLICY,"Attempt TABLE generation"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE cell spacing"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE cell padding"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE border size"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE width"]]
[[HYPERLINK POLICY,"Default TABLE colour"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE border colour"]] [[BR]]
[[HYPERLINK POLICY,"Colour data rows"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE even row colour"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE odd row colour"]]
[[HYPERLINK POLICY,"Default TABLE alignment"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE cell alignment"]]
[[HYPERLINK POLICY,"Convert TABLE X-refs to links"]]
The following policies can only be changed through policy file, but are
probably best not used in favour of the their equivalent preprocessor
tags.
[[HYPERLINK POLICY,"Default TABLE caption"]]
[[HYPERLINK POLICY,"Default TABLE header rows"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE header cols"]]
[[HYPERLINK POLICY,"Column boundaries have zero width"]]
[[HYPERLINK POLICY,"Use .. markup"]]
6.3.14 Miscellaneous policies
AscToHTM supports the following policies which currently can only
be added by editing the .policy file
_Contents List_
[[HYPERLINK POLICY,"Add mail headers to contents list"]]
_CSS_
[[HYPERLINK POLICY,"Create embedded style sheet"]]
_File generation_
[[HYPERLINK POLICY,"Break up long HTML lines"]] [[BR]]
[[HYPERLINK POLICY,"HTML version to be targeted"]] [[BR]]
[[HYPERLINK POLICY,"Lines to ignore at end of file"]] [[BR]]
[[HYPERLINK POLICY,"Lines to ignore at start of file"]]
_Fonts_
[[HYPERLINK POLICY,"Suppress all font markup"]]
_Headings_
[[HYPERLINK POLICY,"Expect Second Word Headings"]]
[[HYPERLINK POLICY,"First Section Number"]]
[[HYPERLINK POLICY,"Number of words to include in filename"]]
_HTML Generation_
[[HYPERLINK POLICY,"HTML version to be targeted"]]
_Style_
[[HYPERLINK POLICY,"First line indentation (in blocks)"]]
_Tables_
[[HYPERLINK POLICY,"Default TABLE caption"]]
[[HYPERLINK POLICY,"Default TABLE header rows"]] [[BR]]
[[HYPERLINK POLICY,"Default TABLE header cols"]]
[[HYPERLINK POLICY,"Column boundaries have zero width"]]
[[HYPERLINK POLICY,"Use .. markup"]]
6.4 Settings policies
*New in version 4*
These policies are used to control the behaviour of the program during
the conversion process. Most program setting are not available as
policies, but those that are are listed here. Full descriptions of
these policies can be found in the [Policy Manual].
6.4.1 Error reporting
The following policies can be used to tailor the number and type of
messages displayed during conversion.
[[HYPERLINK POLICY,"Error reporting level"]]
[[HYPERLINK POLICY,"Suppress INFO messages"]],
[[HYPERLINK POLICY,"Suppress TAG ERROR messages"]]
[[HYPERLINK POLICY,"Suppress URL messages"]]
[[HYPERLINK POLICY,"Suppress WARNING messages"]]
[[HYPERLINK POLICY,"Suppress program ERROR messages"]]
6.5 Saving and loading policy files
This section has been copied into the Policy manual section on
[[HYPERLINK URL,"policy_manual_3.html#Section_3.1","placing policies in a file"]]
6.5.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.5.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.5.2.1 and 6.5.2.2).
Alternatively, you can set the [[HYPERLINK POLICY,"Output policy file"]] policy
which will generate a full policy file resulting from the analysis
of the converted document.
Once a file is generated you can either edit them in a text editor -
deleting policies that are of little interest to you, and editing those
that are - or reload them into the program, change them and save them
again.
6.5.2.1 Partial policy files
Partial policy files are files which have values for some, not all,
policies.
These are recommended, because the it leaves AscToHTM free to adjust
all the other policies not set in the file, 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.5.2.2 Full policy files
A "full" policy file contains a value for almost 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.5.3 Naming policy files
Whenever the [[HYPERLINK POLICY,"Output policy file"]] policy is set 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 was introduced to allow users more flexibility in
the HTML they generate. As such it allows AscToHTM to be used
as a HTML authoring tool, as opposed to a simple text conversion or
migration tool.
The preprocessor looks for
i) "Directives". These are lines that begin with a special character
sequence. Presently this is "$_$_".
ii) "Tags" that are enclosed in "[[OT]]" and "[[CT]]".
A separate document - the [Tag Manual] - has been produced to describe
the pre-processor commands in detail. That document replaces much of
the contents that were originally in this section and the next.
Some commands may be either tags or directives, this is explained more
in the tag manual.
7.1 Directives
7.1.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.
These include :-
[[HYPERLINK TAGGING,"BEGIN/END_CODE"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_CONTENTS"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_DIAGRAM"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_HTML"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_IGNORE"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_PRE"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_TABLE"]] [[BR]]
[[HYPERLINK TAGGING,"SECTION"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_COMMA_DELIMITED_TABLE"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_DELIMITED_TABLE"]] [[BR]]
7.1.2 Commands that influence the .. of a file
Some commands can be used to control the contents of the HTML
section. These attributes are largely non-visual, but may influence
how the document is indexed (e.g. by search engines).
Commands include :-
[[HYPERLINK TAGGING,"TITLE"]] [[BR]]
[[HYPERLINK TAGGING,"DESCRIPTION"]] [[BR]]
[[HYPERLINK TAGGING,"KEYWORDS"]] [[BR]]
[[HYPERLINK TAGGING,"STYLE_SHEET"]] [[BR]]
[[HYPERLINK TAGGING,"BASEHREF"]]
To fully understand how titles are calculated, see the discussion in 5.6.1
7.1.3 One line pre-processor commands
These commands exist on a line by themselves. They either cause
something to be executed at the point they occur, or are used to mark
that location in the file in some way.
The commands include :-
[[HYPERLINK TAGGING,"CONTENTS_LIST"]] [[BR]]
[[HYPERLINK TAGGING,"HTML_LINE"]] [[BR]]
[[HYPERLINK TAGGING,"INCLUDE"]] [[BR]]
[[HYPERLINK TAGGING,"LINERULE"]] [[BR]]
[[HYPERLINK TAGGING,"NAVIGATION_BAR"]] [[BR]]
[[HYPERLINK TAGGING,"TOC"]] [[BR]]
7.1.4 The TABLE commands
A large number of delimiters influence the detection, analysis and
generation of tables. These are discussed in the [Tag manual] in the
[[HYPERLINK URL,"tag_manual_2.html#Section_2.5","The TABLE commands"]] section.
The table commands include :-
[[HYPERLINK TAGGING,"BEGIN/END_TABLE"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_BGCOLOR"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_BORDER"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_BORDERCOLOR"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_CAPTION"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_CELLPADDING"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_CELLSPACING"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_CELL_ALIGN"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_COLO(U)R_ROWS"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_CONVERT_XREFS"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_EVEN_ROW_COLO(U)R"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_HEADER_COLS"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_HEADER_ROWS"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_MAY_BE_SPARSE"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_MIN_COLUMN_SEPARATION"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_ODD_ROW_COLO(U)R"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_COMMA_DELIMITED_TABLE"]] [[BR]]
[[HYPERLINK TAGGING,"BEGIN/END_DELIMITED_TABLE"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_ALIGN"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_IGNORE_HEADER"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_LAYOUT"]] [[BR]]
7.1.5 The CHANGE_POLICY command
The CHANGE_POLICY command allows policies as described in the
[Policy Manual]. You can read more about this in the Tag Manual
under [[HYPERLINK URL,"tag_manual_2.html#Section_2.6","The CHANGE_POLICY command"]]
7.1.6 Block definition
The programs allows you to define "blocks" of text that can later
be inserted or embedded wherever you want in the text. For more
details read the Tag Manual section [[HYPERLINK URL,"tag_manual_2.html#Section_2.7","Definition blocks and variables"]]
Commands include :-
[[HYPERLINK TAGGING,"DEFINE/END_BLOCK and RESET_BLOCK"]] [[BR]]
[[HYPERLINK TAGGING,"DEFINE_VARIABLE"]] [[BR]]
[[HYPERLINK TAGGING,"EMBED_BLOCK"]] [[BR]]
[[HYPERLINK TAGGING,"INSERT_BLOCK"]] [[BR]]
[[HYPERLINK TAGGING,"SAVE_CONTEXT...RESTORE_CONTEXT"]] [[BR]]
7.1.7 HTML Fragments
*New in version 4*
It is possible to define blocks of HTML that the program will use
instead of the HTML it normally produces in certain circumstances.
These blocks of HTML can themselves contain special HTML fragment tags
to allow the HTML to be customized. For example the block
HORIZONTAL_RULE can be used to replace the
tag produced wherever
lines are detected by a .gif of your choice. If you want this .gif
to adopt suitable length and alignment (to match those in the original
text) you can use the HTML fragment tags RULEWIDTH and RULEALIGN.
A full description of [HTML fragments] can be found in the [Tag Manual].
7.2 In-line tags
In-line tags are introduced in version [[TEXT 3.2]]. They allow you
to place special codes in your source text to achieve effects that
couldn't be done by converting plain text alone. As such they greatly
enhance AscToHTM's ability to be used as a web authoring tool.
7.2.1 Format of in-line tags
In-line tags are an extension of the preprocessor tags introduced in
earlier versions. As the name implies, in-line tags may be placed
"in line" with the source tag, giving greater flexibility for their use.
In-line tags are signified by the start and end delimiters "[[OT]]" and
"[[CT]]", for example :-
[[OT]]HTML_COMMENT this will become an HTML comment[[CT]]
The whole tag must be contained within a single line of the source file,
that is there cannot be any newline characters in the middle of a tag.
You can have as many tags as you like on any given line, but they may
not be nested.
In-line tags are fully documented in the [Tag Manual]. A summary
of some of the in-line tags available is given in 7.2.2.
7.2.2 Summary of in-line tags
This is a brief list of the available in-line tags. A fuller
description of using in-line tags is available in the [tag manual]
Tags include :-
[[HYPERLINK TAGGING,"BR (line break)"]] [[BR]]
[[HYPERLINK TAGGING,"COLO(U)R"]] [[BR]]
[[HYPERLINK TAGGING,"CONTENTS_LIST"]] [[BR]]
[[HYPERLINK TAGGING,"ENTITY"]] [[BR]]
[[HYPERLINK TAGGING,"FONT"]] [[BR]]
[[HYPERLINK TAGGING,"GOTO"]] [[BR]]
[[HYPERLINK TAGGING,"HTML"]] [[BR]]
[[HYPERLINK TAGGING,"HTML_COMMENT"]] [[BR]]
[[HYPERLINK TAGGING,"HYPERLINK"]] [[BR]]
[[HYPERLINK TAGGING,"LINKPOINT"]] [[BR]]
[[HYPERLINK TAGGING,"SPACES"]] [[BR]]
[[HYPERLINK TAGGING,"NB ""non-breaking spaces"""]] [[BR]]
[[HYPERLINK TAGGING,"SUPER and SUB"]] [[BR]]
[[HYPERLINK TAGGING,"TEXT"]] [[BR]]
[[HYPERLINK TAGGING,"TIMESTAMP"]] [[BR]]
[[HYPERLINK TAGGING,"TABLE_LAYOUT"]] [[BR]]
[[HYPERLINK TAGGING,"FILENAME"]] [[BR]]
[[HYPERLINK TAGGING,"FRACTION"]] [[BR]]
[[HYPERLINK TAGGING,"IGNORE_THIS"]] [[BR]]
[[HYPERLINK TAGGING,"VARIABLE"]] [[BR]]
[[HYPERLINK TAGGING,"VERSION"]] [[BR]]
8 Frames
------------
8.1 Overview
*New in version 4*
New in version 4 is the ability to have the program generate a set
of frames from your source file. The program works to a model set
of frames as shown below, but you have a great degree of control
over how the frames are laid out, and what their contents are.
$_$_BEGIN_DIAGRAM
+------------------------------------------------------------+
| Header frame |
| (optional) |
+-------------+----------------------------------------------+
| NOFRAMES | |
| link | |
| | |
| | |
| | |
| Contents | Main |
| Frame | Frame |
| (optional) | |
| | |
| | |
| | |
| | |
| | |
+-------------+----------------------------------------------+
| Footer frame |
| (optional) |
+------------------------------------------------------------+
$_$_END_DIAGRAM
8.2 The frames generated
8.2.1 The master