section]]
See the section on [[goto pre-formatted text]] for more details.
Minimum size of automatic section
.......................................
$_$_HELP_TOPIC_ID ID_MINPRESIZE
This policy specifies the minimum number of consecutive
pre-formatted lines that must be detected before the text is
placed in fixed width font.
AscToRTF detects heavily formatted lines, and then looks at
their neighbours to see if they too could be part of a
pre-formatted text.
Once a group of lines is identifies, it will only be marked
up as pre-formatted if the minimum is exceeded.
The default value is 0. Set this value larger if AscToRTF is
marking text as pre-formatted when it shouldn't do.
Note: The is a reference to the shared ancestry of this
software with the text to HTML converter from which it evolved.
$_$_HELP_CHAPTER 3,"Table analysis policies"
Table analysis policies
-----------------------
$_$_HELP_TOPIC_ID HIDD_TABANAL
These policies specify how AscToRTF detects possible tables and
analyses the data in them into columns and rows.
- [[popup Attempt TABLE generation]]
*Detection*
- [[popup Table extending factor, Extend preformatted regions]]
*Analysing rows*
- [[popup Could be blank line separated,Could table have blank lines between rows]]
*Analysing columns*
- [[popup Default table layout, Table Layout]]
- [[popup Expect sparse tables,Is the table expected to have sparse columns]]
- [[popup Ignore table header during analysis,Ignore table header when analysing columns]]
- [[popup Column merging factor, Merge together "poor" columns]]
- [[popup Minimum TABLE column separation, Minimum number of spaces between table columns]]
See the section on [[goto pre-formatted text]] for more details.
Attempt TABLE generation
........................
$_$_HELP_TOPIC_ID ID_ATTEMPT_TABLE
This policy specifies whether or not you want RTF table
generation attempted for regions of apparently pre-formatted
text. AscToRTF will attempt to analyse such regions, preferring
to fit them into a RTF table. However, if this is not possible,
or if AscToRTF decides the pre-formatted region is something
else (like a diagram or a piece of code) then a RTF table will
not be generated.
Disabling this policy tells AscToRTF not to attempt this
analysis, usually leading to pre-formatted text being placed
in simple fixed width font markup instead.
Table extending factor
......................
$_$_HELP_TOPIC_ID ID_EXTEND_TABLE
When the program encounters a strongly formatted line, it examines
the adjacent lines to see if they too could form part of the
same preformatted region.
This policy specifies the extend to which strongly preformatted
lines should be used to "extend" to include adjacent lines as
part of the same preformatted regions. If set to 10, then all
adjacent lines up to the next page break or section heading will
be treated as part of the same region. When set to 1 only those
lines that are clearly heavily formatted themselves will be
included.
This policy appears on-screen as "Extend preformatted regions"
Could be blank line separated
.............................
*New in version 2.0*
This option specifies whether or not tables are expected to have blank
lines between rows. If they are, the software will be more likely to merge
the text for adjacent source lines into a single row in the output table.
Default Table Layout
....................
*New in version 2.0*
This option allows you to specify the default table layout for *all*
tables in the document. The layout specifies the number of columns
and their end positions.
This is the default layout and will normally be applied to *all*
tables the document. If a document has multiple tables you are
better off either using the preprocessor to mark up the source text
and supplying TABLE_LAYOUT commands, or supplying a "Layout" component
in a _Table Definition File_.
The format of the *Table Layout* policy is the same as that described in the
discussion of the [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] pre-processor
command.
See also [[goto TDF line: Layout]]
Expect sparse tables
....................
$_$_HELP_TOPIC_ID ID_TABLE_SPARSE
This policy is used to tell AscToRTF that you expect your tables
to be quite sparse in places. This can affect AscToRTF's analysis,
as the algorithms are liable to merge "empty" columns with their
less empty neighbours.
Enabling this policy will usually result in your tables having
more, emptier, columns.
See also the [[popup Pre-processor command: TABLE_MAY_BE_SPARSE]].
Ignore table header during analysis
...................................
$_$_HELP_TOPIC_ID ID_IGNORE_HEADER
This policy specifies that the table header should be ignored when
analysing the column structure of the table.
In some tables (usually "reports") the header can be quite complex,
with titles spanning multiple columns, whereas the body of the
table is much more structured.
In such cases including the table header in the analysis can lead
to errors, so enabling this policy can simplify the analysis giving
better chances of success.
This policy appears on-screen as "Ignore table header when analysing columns"
Column merging factor
.....................
$_$_HELP_TOPIC_ID ID_MERGE_POOR
Once the program has detected the column layout of a table, it
reviews how well the data can be fitted into these columns. If
too many cells in a column are empty, or if too many cells
"span" multiple columns, then the columns are deemed to be
"poor", and may be merged together to form fewer, wider columns.
This factor determines the extent to which columns should be merged.
A value of 10 means columns should be merged together whenever
there is any doubt. Use this if you are getting too many columns.
A value of 1 means columns should never be merged. Use this if
you are getting too few columns.
This policy appears on-screen as "Merge together "poor" columns".
Note, this policy can't guarantee you will the correct column
structure, but it does give you a chance to influence the logic.
Minimum TABLE column separation
...............................
$_$_HELP_TOPIC_ID ID_MIN_TABLE_SEP
This policy specifies the minimum number of spaces that should be
interpreted as a gap between columns in a potential table. The
default value is 1, but this value can sometimes lead to too many
columns, especially in small tables. Larger values may lead to
columns being merged together.
This policy appears on-screen as "Minimum number of spaces between table columns"
$_$_HELP_CHAPTER 2,"Output policies"
$_$_HELP_SUBJECT "Introduction"
Output policies
===============
$_$_HELP_TOPIC_ID ID_OUTPUT_POLICIES
These policies are used to control the output to RTF. Generally
these policies allow you to decide how the resulting RTF should
look in a manner that cannot be inferred from the original document.
- [[goto File Structure policies,File generation]]
- [[goto Document details]]
- [[goto Formatting policies,Formatting]]
- [[goto RTF settings]]
- [[goto Make Windows Help file policies,Make Windows Help File]]
- [[goto Hyperlinks policies,Hyperlinks]]
- [[goto Preprocessor policies,Preprocessor]]
- [[goto Font policies,Fonts]]
- [[goto Link Dictionary Edit Dialog,Link Dictionary]]
$_$_HELP_CHAPTER 3,"File generating policies"
File generating policies
------------------------
$_$_HELP_TOPIC_ID HIDD_FILESPLIT
$_$_HELP_TOPIC_ID HIDD_FILESPLIT_RTF
_Line and file structures_
- [[popup Preserve file structure using ]]
- [[popup Preserve line structure]]
- [[popup Treat each line as a paragraph]]
_Diagnostics Files_
- [[popup Generate diagnostics files, Generate log files]]
- [[popup Generate sample policy file]]
Preserve file structure using
...................................
$_$_HELP_TOPIC_ID ID_PRESERVEFILE
This policy can be used to place the whole file inside ...
markup. This will use a mono spaced font that preserves the line
structure and the relative spacing of characters.
When this is enabled almost all of the program's other conversions
will be disabled. You should only really use this if your document
has a lot of formatting that the program is failing to understand.
This policy needs to be set manually where wanted.
Preserve Line structure
.......................
$_$_HELP_TOPIC_ID ID_PRESERVELINES
This policy specifies that the line structure of the original
document should be preserved, rather than just the paragraph
structure.
If enabled the lines in the output document will match those of
the original document, and the text will not automatically be
adjusted if you widen your window. On large monitors this will
give the text an "A4" look and feel.
This policy needs to be set manually where wanted.
Treat each line as a paragraph
..............................
$_$_HELP_TOPIC_ID ID_TREATLINESASPARAS
Some files do not break large paragraphs into smaller lines, but
instead place the whole paragraph on a single line. This is
especially true if the source file was created by a text editor
that relied on word wrap (such as Notepad or Word).
These files often have no blank lines between paragraphs, which
makes detecting where paragraphs begin and end more difficult.
In such files this policy can be enabled so that each "line of
text" in the source file will be treated as a separate paragraph.
This policy cannot be automatically detected, and so needs to
be set manually where wanted.
Generate diagnostics files
..........................
$_$_HELP_TOPIC_ID ID_GENLOGS
This policy allows you to specify the generation of some
diagnostics files. AscToRTF will generate 3 files with the
following extensions:
$_$_BEGIN_TABLE
.lis1 A line-by-line summary of how AscToRTF analysed the source file
during the analysis pass
.lis A line-by-line summary of how AscToRTF analysed the source file
during the output pass
.stats A statistics file
$_$_END_TABLE
The .lis file will give the best description of how the source
file has been converted. The differences between the .lis1 and
.lis files can be slight, and are down to fact that on the output
pass more rigorous attention is applied to the policies.
Any error messages generated during the conversion are inserted
into the .lis file at the offending line. This will help you
determine how relevant they are.
This policy appears on-screen as "Generate log files"
Generate sample policy file
...........................
$_$_HELP_TOPIC_ID ID_GENSAMPLE
This policy allows you to generate a policy file containing all
the policies used during the output pass. This will help you
understand how AscToRTF has interpreted your document, and may
help in determining where the analysis may have gone wrong and
need correcting.
Note, this file will contain all the policies used, and as such
is probably not suited for use as an input policy.
This option is equivalent to the policies "Output policy file" and
"Output policy filename".
See the discussion in the [[goto Documentation available]]
$_$_HELP_CHAPTER 3,"Document details"
Document details
----------------
$_$_HELP_TOPIC_ID HIDD_RTF_DOCUMENT
These document details are placed in the "information" section
of the generated RTF document. Depending on your RTF client
these details may, or may not be visible, for example in Word
for Windows you can view these details under the
File -> Properties menu.
On some systems search programs can use this information to
help locate your documents. The details that can be set include
- Title. You have three options
- [[popup use first line as title]]
- [[popup use first heading as title]]
- set a default [[popup title]]
- Subject
- Author
- Manager
- Company Name
- Category
- Keywords
- Comments
Use first line as title
.......................
*New in version 2.0*
When this option is selected, the first line in the document will be
treated as the document title, and will be copied across to the
document properties part of the output file. This can be a useful
option to select when the first line of your document is a document
title line.
If you also want the first line to appear in the output as a heading,
select the [[goto use first line as heading]] option
Use first heading as title
..........................
*New in version 2.0*
When this option is selected, the first heading detected in the document
will also be used as the document's title, and copied across to the
properties section of the output document. Note, this relies on the
program correctly detecting headings, and in particular the first heading.
If the first heading is also the first line, you may want to instead
just consider using the [[goto use first line as heading]] and/or
[[goto use first heading as title]] policies.
Title
.....
This is the document title to be copied across into the properties section
of the output document. The default value is
Converted from [[OT]]filename[[CT]]
where *[[OT]]filename[[CT]]* gets replaced by the original filename
(see [[goto Pre-processor command: filename]]).
See also:
- [[goto use first heading as title]]
- [[goto use first line as title]]
$_$_HELP_CHAPTER 3,"Formatting"
Formatting Policies
-------------------
$_$_HELP_TOPIC_ID HIDD_RTF_FORMAT
*New in version 2.0*
These options offer settings that allow you to control some of
the formatting applied to the RTF output. Options exits for
each of the following areas :-
*Automatic centring*
These options control the any detected [[goto centred text detection,centred text]].
- [[popup Allow automatic centring, Enable automatic centring]]
- [[popup Automatic centring tolerance]]
*Paragraphs*
These options control the formatting of paragraphs.
- [[popup Preserve new paragraph offset, Preserve first line indentation]]
- [[popup First line indentation (in blocks)]]
*Headings*
These options control the formatting of headings.
- [[popup preserve underlining of headings]]
*Bullets*
These options control the formatting of bullets and lists.
- [[popup Use original bullet text]]
- [[popup Characters to use for bullets]]
*Tables*
These options control the formatting [[goto table detection,tables]].
- [[popup Default TABLE cell alignment, table cell alignment]]
- [[popup Default TABLE alignment, table alignment]]
- [[popup Default TABLE header rows, number of header rows]]
*Miscellaneous formatting options*
- [[popup ignore multiple blank lines]]
Allow automatic centring
........................
*New in version 2.0*
When enabled the software will attempt [[goto centred text detection]].
This policy appears on-screen as "Enable automatic centring"
Automatic centring tolerance
............................
*New in version 2.0*
When [[goto centred text detection]] is enabled, this specifies how much
off-centre text can be and still be considered as centred text. Text is
compared to the [[goto page width]], taking into account any left hand
indentation.
If you make this value larger, more text will be considered to be centred
and will be centred in the output, although only blocks of text that are
wholly centred (all lines fall within the specified tolerance) will be
regarded as centred text in the output.
Preserve new paragraph offset
.............................
*New in version 2.0*
When enabled, any first-line indentation detected for paragraphs will be
preserved. Often paragraphs indent the first line by a few spaces. Where
the software detects this you have the choice as to whether an indentation
should be preserved in the output.
This policy appears on-screen as "Preserve first line indentation"
See also [[goto First line indentation (in blocks)]]
First line indentation (in blocks)
..................................
*New in version 2.0*
When set to a non-zero value, paragraphs will be set so that the first line
in each paragraph is indented relative to the remainder of the paragraph.
the indentation is set as a number of tab stop positions.
See also [[goto Preserve new paragraph offset]]
Preserve underlining of headings
................................
*New in version 2.0*
When enabled any detected underlined headings will be underlined in the
output. Headings may be underlined in the source text to make it clear
what they are. When detected by the program these are output using heading
styles which tend to make the text bigger and bolder. that being the case
you may want to lose the underlining of such headings by switching them
off using this policy.
Use original bullet text
........................
*New in version 2.0*
By default the software will replace bullets in the original text by bullet
point characters in the output document. However this isn't always ideal,
especially if the text is to be re-exported or emailed to various computer
systems. When this policy is enabled the bullet text is left unchanged.
Note, you can choose the bullet text that is used via the policy
[[goto characters to use for bullets]]
Characters to use for bullets
.............................
*New in version 2.0*
By default the software will replace bullets in the original text by bullet
point characters in the output document. However this isn't always ideal,
especially if the text is to be re-exported or emailed to various computer
systems. You can use the policy [[goto use original bullet text]] to preserve
the originals, or you can use this policy to choose your own, alternative, text
markers.
The value should be a string whose first character will be used for level
1 bullets, second for level 2 etc, etc. All levels deeper than the last
character will use the last character supplied. So for example the value
+o-
Would use '+' for level 1 bullets, 'o' for level 2 bullets and '-' for
level 3 and beyond.
Default TABLE cell alignment
............................
*New in version 2.0*
By default the software will attempt to automatically calculate the alignment
of data inside each cell of a table. This will look at the placement of the
data, and the type of data (e.g. numerical data is right justified).
This policy can be used to overrule that process and force a particular alignment.
When set it will apply to *all* cells in all detected tables.
To exert more control over particular columns in particular tables you should
consider using a [[goto Using Table Definition Files (TDF),Table definition file]]
Default TABLE alignment
.......................
*New in version 2.0*
By default the software will attempt to automatically calculate the alignment
of a table within a document, and in most cases will simply left align the table,
possibly with a margin where one is detected.
This policy can be used to overrule that process and set the alignment for
all tables in the document (e.g. to centre all tables).
To exert more control over particular columns in particular tables you should
consider using a [[goto Using Table Definition Files (TDF),Table definition file]]
Default TABLE header rows
.........................
$_$_HELP_TOPIC_ID ID_TAB_HEADER
This policy specifies how many lines should be regarded as the
header of a table. AscToRTF can attempt to detect this, and
it may not be the case that all tables in the same file have
the same header size.
This policy appears on-screen as "Number of header rows"
Ignore multiple blank lines
...........................
*New in version 2.0*
When enabled multiple blank lines in the input will not be converted to multiple
blank lines in the output. This can be desirable when converting a document
that has been "paged" and so had extra blank lines added to space out the
sections, and this spacing makes no sense and is unwanted in the RTF.
$_$_HELP_CHAPTER 3,"RTF settings"
RTF settings
------------
$_$_HELP_TOPIC_ID HIDD_RTF_SETTINGS
These options offer settings that would normally be set by
your RTF viewer.
[[popup Language (for proofing), Document language]]
[[popup Paper size]]
[[popup Use Landscape mode, Paper Orientation]]
[[popup Margin sizes]]
[[popup Mirror margins]]
[[popup Character Encoding]]
Depending on the application you use to view the RTF file
created these settings may affect the spell checking, grammar
checking, paging and printing of the generated document.
Language (for proofing)
.......................
$_$_HELP_TOPIC_ID ID_DOCUMENT_LANG
This specifies the language the document is written in.
Depending on the application you use to view the RTF files,
this setting may be used by spell checkers and the like
when checking the document.
This policy appears on-screen as "Document language".
Paper size
..........
$_$_HELP_TOPIC_ID ID_PAPER_SIZE
This specifies the paper size. Depending on the application
you use to view the RTF files, this may be used when printing
the document, and the value selected will affect the paging
of the document.
Use Landscape mode
..................
$_$_HELP_TOPIC_ID ID_ORIENTATION
This specifies the paper orientation (portrait or landscape
mode). Depending on the application you use to view the RTF
files, this may be used when printing the document, and the
value selected will affect the paging of the document.
This policy is offered on-screen as the "Paper orientation" option.
Margin sizes
............
$_$_HELP_TOPIC_ID ID_MARGINS
This specifies the margin sizes. Depending on the application
you use to view the RTF files, these may be used when printing
the document, and the value selected will affect the paging
of the document.
The selected margin sizes are saved in any policy file under
the following names
- Top margin (in cm)
- Bottom margin (in cm)
- margin (in cm)
- margin (in cm)
Mirror Margins
..............
$_$_HELP_TOPIC_ID ID_MIRROR_MARGINS
This specifies that margins should be mirrored, i.e. that odd
and even pages should reverse margin sizes so that they can be
placed facing each other when printed and bound together
Character Encoding
..................
$_$_HELP_TOPIC_ID ID_CHARACTER_ENCODING
This allows the character encoding to be set. Although designed
to convert documents that use the ASCII character set, the software has
some ability to convert Japanese and Cyrillic files amongst others. For
such files to display correctly, the character encoding has to be set up
correctly.
Note, RTF doesn't support all possible languages, and the Arabic conversion
may be a little suspect :-)
$_$_HELP_CHAPTER 3,"Make Windows Help File policies"
Make Windows Help file policies
-------------------------------
$_$_HELP_TOPIC_ID HIDD_MAKEHELP
*New in version 2.0*
AscToRTF can now be used to create RTF files suitable for use as
source files when making a WinHelp help file. You can also get
AscToRTF to create a Help Compiler project file (.hpj) for you, and
tell it some of the things to put in that file. The policies available
are
- [[goto Generate WinHelp project file]]
- [[goto WinHelp Resource File]]
- [[goto Help file citation]]
- [[goto Help file copyright notice]]
- [[goto Help title background colour]]
- [[goto Help body background colour]]
For more information see [[goto Creating WinHelp files]]
Generate WinHelp project file
.............................
*New in version 2.0*
When selected, AscToRTF will create a new Help Compiler project file
for you. This file will have the same name as your source file but with
a .hpj extension. If this option is selected it will overwrite any
existing project file, so take care in using it.
You will need a copy of the Help Compiler Workshop (HCW.EXE) from Microsoft
in order to load and execute the created project file.
WinHelp Resource File
.....................
*New in version 2.0*
If you are attempting to create a WinHelp file for one of your own software
applications you will need to supply the name of the .hm resource file from
your project that defines the topic IDs that your software will want to
be defined in the help file. This .hm file will be added to your project file
and is a crucial link between IDs used in your software, and topics defined
in your help file.
See also the discussion in [[goto Resource file (.hm)]]
Help file citation
..................
*New in version 2.0*
This is the "citation" text added to your help file. This text is displayed
anytime someone prints or pastes topics from your WinHelp file.
Help file copyright notice
..........................
*New in version 2.0*
This is the copyright notice attached to your help file.
Help title background colour
............................
*New in version 2.0*
This is the background colour used for the title text of each topic. This
is the non-scrolling section at the top of each topic page.
NOTE: The colours you specify will only be visible to users running a default
Windows colour scheme. If users change this at all, then these colours
may have no effect.
See also [[popup help body background colour]]
Help body background colour
...........................
*New in version 2.0*
This is the background colour used for the main body of each topic. This
is the scrolling section that makes up the majority of the topic window.
NOTE: The colours you specify will only be visible to users running a default
Windows colour scheme. If users change this at all, then these colours
may have no effect.
See also [[popup help title background colour]]
$_$_HELP_CHAPTER 3,"Hyperlinks policies"
Hyperlinks policies
-------------------
$_$_HELP_TOPIC_ID HIDD_HYPERLINKS
_Add hyperlinks_
- [[popup Create hyperlinks,http:// and www references]]
- [[popup Create mailto links, Convert Email references]]
- [[popup Allow email beginning with numbers, Allow email addresses that begin with a number]]
- [[popup Create Gopher links, Convert Gopher references]]
- [[popup Create Telnet links, Convert Telnet references]]
- [[popup Create FTP links, Convert FTP references]]
- [[popup Only allow explicit FTP links, Convert "weak" ftp references]]
- [[popup Create NEWS links, Convert USENET newsgroup references]]
- [[popup Only use known groups, Convert only recognised USENET newsgroups]]
- [[popup Recognised USENET groups, Additional hierarchies to recognize]]
- [[popup Check domain name syntax]]
_Hyperlinks to other section numbers_
- [[popup Convert cross-references to other sections]]
See also the comments in the [[goto adding hyperlinks]] section.
Create hyperlinks
.................
$_$_HELP_TOPIC_ID ID_CONVERTHTTP
This specifies that all valid "http" and www references that
are found should be turned into active hyperlinks.
Such hyperlinks may sometimes get confused by surrounding
punctuation characters.
This policy is shown on-screen as "http:// and www references"
Create mailto links
...................
$_$_HELP_TOPIC_ID ID_CONVERTEMAIL
This specifies that all valid email addresses that are found
should be turned into active "mailto" hyperlinks.
AscToRTF has no way of checking email addresses, so "made up"
addresses will also get converted, although the domain name
will be validated.
An extra option allows email addresses beginning with a number to
be accepted. Often USENET message IDs have an email format, but
start with a number, so by Default these are not converted to
email hyperlinks.
This policy is shown on-screen as "Convert email references"
Allow email beginning with numbers
..................................
$_$_HELP_TOPIC_ID ID_EMAILNUMBERS
This specifies whether or not email addresses that begin with
numbers are allowed or now.
The program has no way of validating email addresses. Often
documents - especially Usenet posts and the like - contain message
Ids that look like email addresses but aren't. These usually
become with a number, and so by default the program will
ignore "addresses" in this form.
On the other hand some ISPs (e.g. older Compuserve accounts)
allow email addresses that start with numbers. You should toggle
this policy according to which is more appropriate for your
documents.
This policy appears on-screen as "Allow email addresses that begin with
a number"
Create FTP links
................
$_$_HELP_TOPIC_ID ID_CONVERTFTP
This specifies that all FTP addresses that are found should be
turned into active hyperlinks.
These will usually start with "ftp://" or be a domain name
starting "ftp.".
However quite often FTP sites have domain names that don't start
with "ftp." But do end in a recognised domain type such as ".com".
An extra option allows the program to convert such "weak" or
implicit FTP references into FTP links. See [[popup Only allow explicit FTP links]]
This policy appears on-screen as "Convert FTP references"
Only allow explicit FTP links
.............................
$_$_HELP_TOPIC_ID ID_FTPWEAK
This specifies that all "internet" addresses which don't start
with "www." or "ftp." Should be regarded as FTP sites.
Often FTP sites have domain names that don't start with "ftp."
But do end in a recognised domain type such as ".com". For
example rtfm.mit.edu is a well known archive.
This policy appears on-screen as "Convert "weak" FTP references"
Create Gopher links
...................
$_$_HELP_TOPIC_ID ID_CONVERTGOPHER
_New in version 2.0_
This specifies that all gopher addresses that are found should
be turned into active hyperlinks.
These will usually start with "gopher://".
This policy appears on-screen as "Convert Gopher references"
Create Telnet links
...................
$_$_HELP_TOPIC_ID ID_CONVERTTELNET
_New in version 2.0_
This specifies that all telnet addresses that are found should
be turned into active hyperlinks.
These will usually start with "telnet://".
This policy appears on-screen as "Convert Telnet references"
Check domain name syntax
........................
$_$_HELP_TOPIC_ID ID_CHECKSYNTAX
_New in version 2.0_
This specifies whether or not potential URLs should have their "domain name"
checked against the known domain name structures, (i.e. ends in .com, .org,
.co.uk etc). Having this switched on reduces the likelyhood of invalid
URLs being turned into clickable links that don't go anywhere. Note,
the software doesn't check the domain *exists*, only that the domain name
obeys the known rules.
You might want to switch this off if your document contains URLs that
don't use standard domain names (e.g. they are inside an Intranet).
Create NEWS links
.................
$_$_HELP_TOPIC_ID ID_CONVERTNEWS
This specifies that AscToRTF should attempt to identify Usenet
newsgroup names and turn them into active "news" hyperlinks.
AscToRTF has no way of checking newsgroup names, so by default
it will only convert names in recognised hierarchies such as
alt.,comp.,rec. etc.
This policy appears on-screen as "Convert USENET newsgroup references"
Only use known groups
.....................
$_$_HELP_TOPIC_ID ID_KNOWNONLY
This specifies that when detecting Usenet newsgroup names,
AscToRTF should only convert names in recognised hierarchies
such as alt.,comp.,rec. etc.. You can get the program to
recognize additional hierarchies.
This policy is shown on-screen as "Convert only recognised USENET newsgroups"
Recognised USENET groups
........................
$_$_HELP_TOPIC_ID ID_OTHERGROUPS
This specifies that when detecting Usenet newsgroup names,
AscToRTF should additionally allow "newsgroups" in these
hierarchies in addition to the standard hierarchies such
as alt.,comp.,rec. etc.
This policy is shown on-screen as "Additional hierarchies to recognize"
Convert cross-references to other sections
..........................................
$_$_HELP_TOPIC_ID ID_CONVERTXREF
This specifies whether or not AscToRTF should turn references
to section numbers in the main text to hyperlinks to those
sections.
This is only possible for numbered sections.
If selected, you should specify the level at which such
cross-references should start. A value of "1" will attempt to
convert all numbers N, N.N... to hyperlinks. A value of two
will attempt to convert N.N, N.N.N... etc.
This policy is quite prone to error (e.g. Windows 3.1 often
becomes a hyperlink to section 3.1). Consequently lower values
are more error prone. A value of "2" is set by default.
Later versions may address this problem.
This option is saved in the policy file as the "Convert TABLE X-refs to links"
and "Cross-refs at level" policies.
$_$_HELP_CHAPTER 3,"Preprocessor policies"
Preprocessor policies
---------------------
$_$_HELP_TOPIC_ID HIDD_PREPROCESSOR
These options allow various aspects of the pre-processor to
be controlled
- [[goto Use Preprocessor]]
- [[goto Include document section(s)]]
Use Preprocessor
................
*New in version 2.0*
When enabled the pre-processor is activated. You would only ever
want to de-activate it to see what difference not processing
an pre-processor commands would make.
Include document section(s)
...........................
*New in version 2.0*
This is a comma-separated list of which SECTION's you want included
in your document. This only applies if you've made use of the
[[goto Pre-processor command: SECTION, SECTION]] command to mark up parts of
your document to be conditionally output during the conversion.
$_$_HELP_CHAPTER 3,"Font policies"
Font policies
-------------
$_$_HELP_TOPIC_ID HIDD_FONTS
Fonts
Normal text [[popup Default font]]
Headings [[popup Heading Font]]
Text in tables [[popup Table font]]
Table of contents [[popup Table of contents Font, TOC Font]]
Fixed-pitch text [[popup Fixed font]]
Default font
............
$_$_HELP_TOPIC_ID ID_DEFAULTFONT
This specifies the default font to be used. It may be edited
via a normal Windows Font selection dialog.
Heading font
............
$_$_HELP_TOPIC_ID ID_HEADINGFONT
_New in version 2.0_
This specifies the default font to be used for headings.
The actual headings will be based on this font family, but
will be made larger and or italic according to the level of
heading applied to a given heading.
It may be edited via [[popup the Font selection dialog]].
Table font
..........
$_$_HELP_TOPIC_ID ID_TABLEFONT
_New in version 2.0_
This specifies the default font to be used inside tables.
This will default to the [[popup Default Font]], but you may want
to set it smaller in order to fit wide tables on the page.
It may be edited via [[popup the Font selection dialog]].
Table of contents Font
......................
$_$_HELP_TOPIC_ID ID_TOCFONT
_New in version 2.0_
This specifies the default font used in any generated Table
of Contents. The font family specified will be used, but the
different levels of heading in the list will be given different
sizes and italics, just as in a default Word document.
It may be edited via [[popup the Font selection dialog]].
This policy is shown on-screen as "TOC font"
Fixed font
..........
$_$_HELP_TOPIC_ID ID_FIXEDFONT
_New in version 2.0_
This specifies the default font to be used for ASCII art and
diagrams and other portions of text where the spacing is to be
preserved. For this a mono-spaced font such as Courier is usually
used. The Font size is also usually set a bit smaller at 8pt.
This is to ensure that an 80-character "line" in the original
document will fit on a page in the output document.
It may be edited via [[popup the Font selection dialog]].
The Font Selection Dialog
.........................
Each of the font values may be chosen using the font selection
dialog. The selected font is shown as a comma-separated list containing :-
- The font name
- The font characteristics ("Regular", "bold", "italic" or "bold italic")
- The font size (in pts)
$_$_HELP_CHAPTER 3,"Link Dictionary"
Link Dictionary Edit Dialog
---------------------------
$_$_HELP_TOPIC_ID HIDD_LINK_DICTIONARY
See also [[goto Using link dictionary files]]
The Link Dictionary allows you to convert text in your files
into hyperlinks. For fuller details see [[goto Using link dictionary files]]
This dialog allows you to edit the links in your link dictionary, although
if you take care you can do this more easily by opening up you dictionary
file in a text editor such as NotePad.
To enter a new link
1. Click on "Add a new link definition"
2. Enter the definition details in the edit boxes, replacing
the demonstration text
3. Press the "Add link" button.
To update or remove a link
1. Click on the desired link on the list on the left.
2. Edit the details of the link in the edit boxes on the right
3. Press the "Update link" or "Remove Link" buttons
Each link definition consists of three parts :-
*Text to be matched*
This is the text as it will appear in your source file. The
text must be contained on a single line of the input file.
Care should be taken to avoid using substrings of other matched
text. For this reason it is a good idea to edit your source
files to put brackets round the links your want [like this]
and then only match the text including the brackets.
*Replacement text*
This is the text that will appear as the hyperlink text.
Normally this is very similar to the matched text.
*Hyperlink URL*
This is the hyperlink's URL. It can be absolute or relative
or even local to the current page. Just ensure it is correct
for where your pages are going to end up.
$_$_HELP_CHAPTER 3,"Other policies"
Other policies
---------------
Other policies can be set as follows:
*On the Style Definition File selection dialog*
- [[goto Scope for font tags]]
Scope for font tags
...................
*New in version 2.0*
When using an external _Style Definition File_ together with FO tags
to control the fonts in your document, this policy controls the scope
of the font tag introduced by each new FO tag. The options are
- Scope to the end of the file. If this is selected, the associated
font will apply until the end of the document, or until another
FO tag is encountered
- Scope to the next paragraph/table/heading. If this is selected, the
associated font will apply until a major new typographical feature
is encountered, or a new FO tag is detected.
- Scope to the end of the input line. If this is selected, the FO tag
will only apply on the rest of the text on the same input line, or
until a new FO tag is encountered.
See also
- [[goto Using Style Definition Files (SDF)]]
- [[goto Pre-processor command: FO]]
$_$_HELP_CHAPTER 1,"Using the pre-processor"
$_$_HELP_SUBJECT "Introduction to the pre-processor"
Using the pre-processor
***********************
$_$_HELP_TOPIC_ID ID_PREPROCESSOR
The pre-processor allows authors to add special lines to the
source document to customise the conversion. This is usually
used where someone intends regularly generating RTF from a
master text document.
The Pre-processor is described more fully in the separate
document the [Tag Manual].
The pre-processor works by giving the software hints and instructions
on how to process the text. During the analysis process the software
reads the source files line-by-line. The pre-processor recognises
special keywords in two ways
- [[goto pre-processor directives,Directives]] are placed on a line by themselves. They
usually instruct the software to do something, but don't usually
appear directly in the output themselves. Often directives occur
in pairs, marking up a section of text between them as having a
special significance (e.g. to say it's a comma-delimited table)
- [[goto pre-processor in-line tags,In-line tags]] can be placed anywhere in a line of input text.
Usually they are substituted by some special text. For example
a [[goto Pre-processor command: GOTO,GOTO]] tag becomes a hyperlink to a section elsewhere,
while a [[goto Pre-processor command: BR,BR]] tag forces a line break at that point.
In both cases the tag or directive cannot be split over multiple lines,
that is directives must be on a line by themselves, and in-line tags must
be wholly contained on a single line.
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION MAKINGRTF
Pre-processor commands come in several types:-
$_$_BEGIN_DELIMITED_TABLE
[[goto Document commands]] Commands that change the document title and keywords etc
[[goto Section delimiters]] Commands that delimit sections in the source text
[[goto Table modifier commands]] Commands that delimit and control table generation
[[goto Other commands]] Other miscellaneous commands
$_$_END_TABLE
$_$_SECTION ALL
Pre-processor Directives
------------------------
"Directives" consist of a single line in the source file beginning with
the string "$_$_" followed by a recognised keyword and any additional
"attributes" that the directive supports.
Pre-processor In-line tags
--------------------------
In-line tags, as the name implies, can occur anywhere in the source lines.
They are enclosed between the special strings "[[OT]]" and "[[CT]]". Between
these strings the tag consists of a keyword and then any attributes that
tag supports.
Useful in-line tags include
- [[goto Pre-processor command: GOTO,GOTO]]
- [[goto Pre-processor command: BR,BR]]
- [[goto Pre-processor command: FRACTION,FRACTION]]
- [[goto Pre-processor command: SUPER and SUB,SUPER and SUB]]
$_$_HELP_CHAPTER 2,"Document commands"
Document commands
=================
$_$_HELP_TOPIC_ID ID_PRE_DOCUMENT
These commands are used to control tags placed in the document
information section of the created RTF page(s).
Not yet implemented in this release.
$_$_BEGIN_DELIMITED_TABLE
[[popup Pre-processor command: DESCRIPTION, DESCRIPTION]] Add a description in the document properties
[[popup Pre-processor command: KEYWORDS, KEYWORDS]] Add keywords to the document properties
[[popup Pre-processor command: TITLE, TITLE]] Add a Title to the RTF pages
$_$_END_DELIMITED_TABLE
Pre-processor command: DESCRIPTION
----------------------------------
$_$_HELP_TOPIC_ID ID_PRE_DESCRIPTION
You can specify a description of your page to be added as a to
the document information portion of your page by adding a line
of the form
$_$_BEGIN_PRE
$_$_DESCRIPTION
$_$_END_PRE
This takes precedence over any description added via a policy file.
Not yet implemented
Pre-processor command: KEYWORDS
-------------------------------
$_$_HELP_TOPIC_ID ID_PRE_KEYWORDS
You can specify keywords that describe the contents of your
page to be added to the document information section of your
file by adding a line of the form
$_$_BEGIN_PRE
$_$_KEYWORDS
$_$_END_PRE
This takes precedence over any keywords added via a policy file.
Not yet implemented
Pre-processor command: TITLE
----------------------------
$_$_HELP_TOPIC_ID ID_PRE_TITLE
You can specify the TITLE to be added to your RTF page in the
document information section, by adding a line of the form
$_$_BEGIN_PRE
$_$_TITLE
$_$_END_PRE
This title takes precedence over any title added via a policy file.
Not yet implemented
$_$_HELP_CHAPTER 2,"Section delimiters"
Section delimiters
==================
$_$_HELP_TOPIC_ID ID_PRE_SECTION
These commands mark the start and end of various sections in
your document
$_$_BEGIN_DELIMITED_TABLE
[[popup Pre-processor command: ALLOW and DISALLOW,ALLOW and DISALLOW]] Enable and disable certain types of detection.
[[popup Pre-processor command: ASCII,ASCII]] Mark a section of text for utility A2HDETAG.
[[popup Pre-processor command: CONTENTS,CONTENTS]] Mark a section as the contents list.
[[popup Pre-processor command: CODE,CODE]] Mark a section as C-like code sample
[[popup Pre-processor command: DIAGRAM,DIAGRAM]] Mark a section as a diagram or ASCII Art
[[popup Pre-processor command: IGNORE,IGNORE]] Ignore a section of the document
[[popup Pre-processor command: PRE,PRE]] Mark a section as pre-formatted text.
[[popup Pre-processor command: TABLE,TABLE]] Mark a section as a table.
[[popup Pre-processor command: COMMA_DELIMITED_TABLE,COMMA_DELIMITED_TABLE]] Mark a section as comma-delimited data table.
[[popup Pre-processor command: DELIMITED_TABLE,DELIMITED_TABLE]] Mark a section as a tab-delimited data table.
[[popup Pre-processor command: SECTION,SECTION]] Mark the start of a user-specified section.
$_$_END_TABLE
Pre-processor command: ALLOW and DISALLOW
-----------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_ALLOW_AND_DISALLOW
*New in version 2.0*
AscToRTF will automatically try to detect various typographical features. You
can turn this behaviour on and off in different sections by using the ALLOW and
DISALLOW. This can be used, for example, to prevent a numbered list being
wrongly detected as a numbered heading and vice versa.
The syntax for both commands is the same, namely
$_$_BEGIN_PRE
ALLOW/DISALLOW
$_$_END_PRE
Where the recognised keywords are as follows
Headings This enables/disable the search for lines that could be
treated as headings.
Lists This enables/disables the search for lines that could
be regarded as list items (either unordered bullets, or
alphabetic or numeric list points)
All Set (enable) all of the above
Reset Reset (disable) all of the above
In each case the tag will simply add or subtract from the current
list of allowable features. To aid control, two special keywords
"all" and "reset" are available for inclusion in the list. "Reset"
will disable all options, thus
$_$_BEGIN_PRE
$_$_ALLOW reset, Headings
$_$_END_PRE
will have the effect of disabling everything (the "reset") and
then adding "Headings" to the allowed list. In this respect
"ALLOW all" and "DISALLOW reset" are identical commands.
Below is an example in which the DISALLOW tag is used to prevent numbered lines
being regarded as lists or headings. The ALLOW tag at the end switched back to
default behaviour,, so if there are any lists of numbered headings elsewhere
in the document they will still be detected.
$_$_BEGIN_PRE
$_$_DISALLOW headings
...
1. Whatever this line is, it isn't a heading
...
$_$_DISALLOW headings,lists
...
2. Whatever this line is, it isn't a heading *or* a list item
...
$_$_ALLOW reset
$_$_END_PRE
Pre-processor command: ASCII
----------------------------
*New in version 2.0*
As of version 2.0, the separate utility [[goto new utility a2hdetag,A2HDETAG]] is available to create
a plain ASCII file, by removing all pre-processor tags from your source
file. In this was a source file designed for conversion to RTF by AscToRTF
can be "cleaned up" and posted as plain text elsewhere.
To support this, the BEGIN_ASCII and END_ASCII tags can be used to delimit
a section of text that will only appear in the version created by A2HDETAG.
This allows you to add comments to the "plain text" version, that won't
appear in the RTF conversion. Use these commands as follows
$_$_BEGIN_PRE
$_$_BEGIN_ASCII
You are reading this text in a "cleaned up" version of the
source file. This text won't get copied across when this
file is converted to either RTF or HTML
$_$_END_ASCII
$_$_END_PRE
Pre-processor command: CONTENTS
-------------------------------
$_$_HELP_TOPIC_ID ID_PRE_CONTENTS
You can mark up a section of your document as a contents list.
To do this use matching BEGIN_CONTENTS and END_CONTENTS command
as follows:
$_$_BEGIN_PRE
$_$_BEGIN_CONTENTS
...
$_$_END_CONTENTS
$_$_END_PRE
AscToRTF will then attempt to treat the enclosed text as a contents list.
See comments on [[goto contents policies]]
Pre-processor command: CODE
---------------------------
$_$_HELP_TOPIC_ID ID_PRE_CODE
You can mark up a section of your document as being a piece of
sample C-like code. To do this use matching BEGIN_CODE and
END_CODE command as follows:
$_$_BEGIN_PRE
$_$_BEGIN_CODE
...
$_$_END_CODE
$_$_END_PRE
AscToRTF will then mark up the enclosed text in fixed width fonts.
See comments on [[goto pre-formatted text]]
Pre-processor command: COMMA_DELIMITED_TABLE
--------------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_COMMA_TABLE
_New in version 2.0_
These commands delimit a table of comma-delimited data
Syntax:
$_$_BEGIN_PRE
$_$_BEGIN_COMMA_DELIMITED_TABLE
...
(lines of comma-delimited data)
...
$_$_END_COMMA_DELIMITED_TABLE
$_$_END_PRE
The BEGIN_COMMA_DELIMITED_TABLE ... END_COMMA_DELIMITED_TABLE directives
can be used to delimit a series of comma-delimited data values that should
be interpreted as a table (e.g. data originally exported from a
spreadsheet such as Excel)
See comments in [[goto Pre-processor command: TABLE]]
Pre-processor command: DELIMITED_TABLE
--------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_DELIMITED_TABLE
These directives delimit a table of delimited data
Syntax:
$_$_BEGIN_PRE
$_$_BEGIN_DELIMITED_TABLE []
...
(lines of delimited data)
...
$_$_END_DELIMITED_TABLE
$_$_END_PRE
where
The delimiter character to use. If omitted
the default is tab-delimited. The delimiter
can be any character except a comma. For
comma-delimited tables use the
[[goto Pre-processor command: COMMA_DELIMITED_TABLE,COMMA_DELIMITED_TABLE]] Command instead
The BEGIN_DELIMITED_TABLE ... END_DELIMITED_TABLE directives
can be used to delimit a series of delimited data values that should
be interpreted as a table (e.g. data originally exported from a
spreadsheet such as Excel)
See comments in [[goto Pre-processor command: TABLE]]
Pre-processor command: DIAGRAM
------------------------------
$_$_HELP_TOPIC_ID ID_PRE_DIAGRAM
You can mark up a section of your document as being a diagram
or a piece of ASCII art. To do this use matching BEGIN_DIAGRAM
and END_DIAGRAM commands as follows:
$_$_BEGIN_PRE
$_$_BEGIN_DIAGRAM
...
$_$_END_DIAGRAM
$_$_END_PRE
AscToRTF will then mark up the enclosed text in fixed width fonts.
See comments on [[goto pre-formatted text]]
Pre-processor command: IGNORE
-----------------------------
$_$_HELP_TOPIC_ID ID_PRE_IGNORE
You can mark up a section in your document that you want ignored
in the output. This can be used to store change history information
or whatever you want.
Syntax:
$_$_BEGIN_PRE
$_$_BEGIN_IGNORE
...
(text to be ignored)
...
$_$_END_IGNORE
$_$_END_PRE
This markup can be used to delimit a section to be wholly ignored. Any
markup and tags in the ignored section will have no effect.
Pre-processor command: PRE
--------------------------
$_$_HELP_TOPIC_ID ID_PRE_PRE
You can mark up a section of your document as being
pre-formatted text. To do this use matching BEGIN_PRE and
END_PRE commands as follows:
$_$_BEGIN_PRE
$_$_BEGIN_PRE
...
$_$_END_PRE
$_$_END_PRE
AscToRTF will then mark up the enclosed text in fixed width fonts.
See comments on [[goto pre-formatted text]]
Pre-processor command: TABLE
----------------------------
$_$_HELP_TOPIC_ID ID_PRE_TAB_TABLE
You can mark up a section of your document as being a text table.
To do this use matching BEGIN_TABLE and END_TABLE Commands as
follows:
$_$_BEGIN_PRE
$_$_BEGIN_TABLE
...
$_$_END_TABLE
$_$_END_PRE
AscToRTF will then analyse the enclosed text to determine the
table layout and will generate a proper RTF table.
*General comments on marking up tables*
AscToRTF has some ability to auto-detect tables (see comments
on [[goto pre-formatted text]]), but this can be error prone.
Marking up tables removes a lot of the ambiguity and so can
give better results*
For tables of delimited data (as opposed to plain text tables)
you should use the [[goto Pre-processor command: DELIMITED_TABLE,DELIMITED_TABLE]] and [[goto Pre-processor command: COMMA_DELIMITED_TABLE, COMMA_DELIMITED_TABLE]] commands.
Note in each case the presence of these directives overrides any
value set in the [[goto Attempt table generation]] policy, as that
only refers to the auto-detection of tables. Placing markup in
the source *forces* the text to be treated as tables.
Within each marked-up table other pre-processor commands may be
used to customise the table as follows:
- [[popup Pre-processor command: TABLE_HEADER_ROWS,TABLE_HEADER_ROWS]]
- [[popup Pre-processor command: TABLE_MAY_BE_SPARSE,TABLE_MAY_BE_SPARSE]]
- [[popup Pre-processor command: TABLE_MIN_COLUMN_SEPARATION,TABLE_MIN_COLUMN_SEPARATION]]
For a full list see [[goto Table modifier commands]]
Pre-processor command: SECTION
------------------------------
$_$_HELP_TOPIC_ID ID_PRE_NAMED_SECTION
You can mark up sections of your document as being named
sections. By default text belongs to a section called "all".
To do so insert SECTION command at the start of each section
as follows:
$_$_BEGIN_PRE
$_$_SECTION
...
$_$_END_PRE
All following text will be marked as belonging to the named
section until another SECTION command is encountered. AscToRTF
will only copy across those sections named in the allowable
sections policy, and any text in "all" sections. In this way
you can generate variants of your document for different
audiences (e.g. Internet and Intranet).
If you want the rest of your document to be included in all
conversions, insert an "all" SECTION command as follows:
$_$_BEGIN_PRE
$_$_SECTION all
...
$_$_END_PRE
$_$_HELP_CHAPTER 2,"Tagged Table commands"
Tagged Table commands
=====================
*New in version 2.0*
In addition to converting plain text files, and sets of delimited data
into tables, the software also supports a method of explicitly tagging the
input as to how it should be placed in a table.
This may seem extreme, as the point of the converters is to generate the
desired markup as save work, but there are a couple of situations in which
this approach can be useful.
- If you are converting the source to both RTF and HTML, the same input
file can be used to generate the desired output format
- If the file you are converting is being generated by some software
it may be easy to add the required tags, and by so doing get the
required output with minimal changes and maximum accuracy.
Here's a sample of a user-tagged table (with blank lines added for clarity) :-
$_$_BEGIN_PRE
$_$_BEGIN_USER_TABLE C,1 in
$_$_COLUMN_DETAILS 1,,,L, 2 in
$_$_COLUMN_DETAILS 2,,,C, 1 ins
$_$_TABLE_BORDER 1
$_$_NEW_ROW HEAD
$_$_NEW_CELL
Substance (units)
$_$_NEW_CELL
Year
Sampled
$_$_NEW_ROW DATA
$_$_NEW_CELL
Alpha emitters (pCi/L)
$_$_NEW_CELL
1999
$_$_NEW_ROW DATA
$_$_NEW_CELL
Asbestos (MFL)
$_$_NEW_CELL
1993
$_$_END_TABLE
$_$_END_PRE
Here's how this table appears when converted into the current format
$_$_BEGIN_USER_TABLE C,1 in
$_$_COLUMN_DETAILS 1,,,L, 2 in
$_$_COLUMN_DETAILS 2,,,C, 1 ins
$_$_TABLE_BORDER 1
$_$_NEW_ROW HEAD
$_$_NEW_CELL
Substance (units)
$_$_NEW_CELL
Year
Sampled
$_$_NEW_ROW DATA
$_$_NEW_CELL
Alpha emitters (pCi/L)
$_$_NEW_CELL
1999
$_$_NEW_ROW DATA
$_$_NEW_CELL
Asbestos (MFL)
$_$_NEW_CELL
1993
$_$_END_TABLE
See also
- [[goto Tagged table command: BEGIN_USER_TABLE, BEGIN_USER_TABLE]]
- [[goto Tagged table command: COLUMN_DETAILS, COLUMN_DETAILS]]
- [[goto Tagged table command: NEW_ROW, NEW_ROW]]
- [[goto Tagged table command: NEW_CELL, NEW_CELL]]
- [[goto Tagged table: cell contents, Table cell contents]]
Tagged table command: BEGIN_USER_TABLE
--------------------------------------
To identify a section of a source file as a user table, it must be enclosed
in the BEGIN_USER_TABLE ... END_TABLE commands as follows
$_$_BEGIN_PRE
$_$_BEGIN_USER_TABLE
...
...
$_$_END_TABLE
$_$_END_PRE
The command line can take arguments as follows
$_$_BEGIN_PRE
$_$_BEGIN_USER_TABLE ,
$_$_END_PRE
where
$_$_BEGIN_TABLE
The alignment of the table. This can be
L(eft), R(ight) or C(enter)
The margin to be applied to the table. This
consists of a number and a unit. Recognised
units include points ("pts" or "pt"), inches
("ins" or "in") and centimetres ("cm"). In HTML
generation these margins will be approximate only
$_$_END_TABLE
Tagged table command: COLUMN_DETAILS
------------------------------------
After the BEGIN_USER_TABLE line will appear a number of COLUMN_DETAILS
lines. These are optional, but if present they give details of the
characteristics of each column in the table as follows :-
$_$_BEGIN_PRE
$_$_COLUMN_DETAILS ,,
$_$_END_PRE
where
$_$_BEGIN_TABLE
This is the column number, starting at 1
This is the alignment of data in this column.
If omitted this will be auto-detected, but you can
choose to set it to L(eft), R(ight) or C(enter)
The width of the column. If omitted the width will
be calculated. As with the on the table
the width can be specified in points, inches or
centimetres. If a width is set too narrow, it may
be ignored.
$_$_END_TABLE
Tagged table command: NEW_ROW
-----------------------------
Each new row is identifies by the present of a NEW_ROW command on a line
by itself. The format is
$_$_BEGIN_PRE
$_$_NEW_ROW
$_$_END_PRE
where
$_$_BEGIN_TABLE
$_$_TABLE_MIN_COLUMN_SEPARATION 2
This is the row type. Options include
HEAD This is a header row
DATA This is a data row
LINE This is a line in the table
The type may be omitted, in which case the default
is "DATA"
$_$_END_TABLE
except when the NEW_ROW is a "LINE", this command should be followed by
a series of NEW_CELL commands and their matching cell data - normally
one per column.
Tagged table command: NEW_CELL
------------------------------
Except for "LINE" rows, each new cell in a row identifies by the present of
a NEW_CELL command on a line by itself. The contents of the cell follow
on subsequent lines until either another NEW_CELL, NEW_ROW or END_TABLE
command is encountered.
The format of the NEW_CELL command is
$_$_BEGIN_PRE
$_$_NEW_CELL
$_$_END_PRE
At present the NEW_CELL command doesn't take any arguments.
Tagged table: Cell contents
---------------------------
Anything following a NEW_CELL command up until the next NEW_CELL, NEW_ROW or
END_TABLE commands will be added into the current cell. The line structure
will be preserved, so that if you have three lines of text following a NEW_CELL
command, this will appear as a cell in the table with three lines of data in it.
The alignment of the cell will normally be that of the column the cell is
in. This will either have been calculated automatically for the column as
a whole, or will be value passed in via the matching [[goto Tagged table command: COLUMN_DETAILS, COLUMN_DETAILS]] line,
earlier in the table definition.
$_$_HELP_CHAPTER 2,"Table modifier commands"
Table modifier commands
=======================
$_$_HELP_TOPIC_ID ID_PRE_TABLE
These commands can be used to tailor the appearance of a table.
They're usually placed between the BEGIN_TABLE ... END_TABLE for
the table they will affect, but they can also be placed at the
top of the document to define defaults for all tables.
- [[popup Pre-processor command: TABLE_HEADER_ROWS,TABLE_HEADER_ROWS]]
- [[popup Pre-processor command: TABLE_MIN_COLUMN_SEPARATION,TABLE_MIN_COLUMN_SEPARATION]]
- [[popup Pre-processor command: TABLE_MAY_BE_SPARSE,TABLE_MAY_BE_SPARSE]]
- [[popup Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]]
- [[popup Pre-processor command: TABLE_IGNORE_HEADER,TABLE_IGNORE_HEADER]]
Pre-processor command: TABLE_HEADER_ROWS
----------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_TAB_HEADER
This specifies how many rows in the table should be regarded
as the table header.
Pre-processor command: TABLE_IGNORE_HEADER
------------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_TAB_IGNORE_HEADER
_New in version 2.0_
This directive specifies that a table header should be ignored during
the column analysis
Syntax:
$_$_BEGIN_PRE
$_$_TABLE_IGNORE_HEADER
$_$_END_PRE
This tag has no attributes.
If present, indicates that the first few lines of the table - assumed to
be the header - should be ignored when calculating the table's column
structure.
This should be enabled if the table has a particularly complex header that
may confuse the program.
This command has the same effect as the policy [[goto Ignore table header during analysis,Ignore table header when analysing columns]],
but can be applied on a table-by-table basis when enclosed between
[[goto Pre-processor command: TABLE, TABLE]] command markers.
Pre-processor command: TABLE_LAYOUT
-----------------------------------
$_$_HELP_TOPIC_ID ID_PRE_TAB_LAYOUT
_New in version 2.0_
This directive allows you to specify the column structure of
a table
Syntax:
$_$_BEGIN_PRE
$_$_TABLE_LAYOUT ,"","",.....
$_$_END_PRE
where,
$_$_BEGIN_TABLE
Integer number of columns
Specification of the nth column. The
specification must be contained in quote.
Currently the specification consists of
just the end position of the column.
More may be added in later versions
$_$_END_TABLE
An example would be
$_$_BEGIN_PRE
$_$_TABLE_LAYOUT 3,"6","21","32"
$_$_END_PRE
which describes a 3-column table with column boundaries at the 6th, 21st
and 32nd character positions.
Normally this directive should be placed between the BEGIN_TABLE...END_TABLE
directives for the table it applies to, thereby overriding the "intelligent"
analysis the program would otherwise attempt for a plain text table.
Pre-processor command: TABLE_MAY_BE_SPARSE
------------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_TAB_SPARSE
This specifies that the table may be sparse, i.e. largely empty
in places. There is no data value required on this command.
See also [[popup expect sparse tables]] policy
Pre-processor command: TABLE_MIN_COLUMN_SEPARATION
--------------------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_TAB_MINCOLSEP
This specifies the minimum number of spaces to be regarded as
a column separator. The default value is 1, but occasionally
this gives too many columns, especially in short tables. Increasing
this value will reduce the number of columns calculated.
$_$_HELP_CHAPTER 2,"Other commands"
Other commands
==============
$_$_BEGIN_DELIMITED_TABLE
[[popup Pre-processor command: BR,BR]] Insert a line break
[[popup Pre-processor command: CHANGE_POLICY,CHANGE_POLICY]] Dynamically vary policies through the input file
[[popup Pre-processor command: FILENAME,FILENAME]] Output the original filename
[[popup Pre-processor command: FO,FO]] Change the prevailing font
[[popup Pre-processor command: FRACTION,FRACTION]] Output a fraction
[[popup Pre-processor command: GOTO,GOTO]] Add a hyperlink to a section title
[[popup Pre-processor command: IGNORE_THIS,IGNORE_THIS]] Ignore some text in the source
[[popup Pre-processor command: INCLUDE,INCLUDE]] Include an external file into the source
[[popup Pre-processor command: PAGE,PAGE]] Create a page boundary at this location
[[popup Pre-processor command: POPUP,POPUP]] Add a hyperlink to a section title
[[popup Pre-processor command: SUPER and SUB,SUPER and SUB]] Add superscripts and subscripts
[[popup Pre-processor command: VERSION,VERSION]] Output the program version used in this conversion
$_$_END_DELIMITED_TABLE
Pre-processor command: BR
-------------------------
This command tells the software to output a line break at this
point. Usually the default is to let all lines flow together to
form a paragraph. This commands can be used (e.g. in address lines
to make sure lines are correctly placed on new lines).
Pre-processor command: CHANGE_POLICY
------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_CHANGEPOLICY
This option allows you to embed policy lines in the source
document. This can be used to avoid the need for separate
policy files, or to change the policy at different locations
within the document (although the effects can sometimes be
unpredictable).
The syntax is
$_$_BEGIN_PRE
$_$_CHANGE_POLICY
$_$_END_PRE
For example placing
$_$_BEGIN_PRE
$_$_CHANGE_POLICY Convert mailto links : yes
$_$_END_PRE
would make all subsequent email addresses be converted into
working hyperlinks. By adding several lines of this type you
can toggle this behaviour on and off, controlling which email
links become hyperlinks and which do not.
Pre-processor command: FILENAME
-------------------------------
This in-line tag substitutes the name of the files being converted
Syntax:
[[OT]]FILENAME[[CT]]
The tag will be replaced by the name of the file being converted. This
facilitates the construction of sentences like
"This file was converted from *[[OT]]FILENAME[[CT]]* at *[[OT]]TIMESTAMP[[CT]]*"
which becomes
"This file was converted from *[[FILENAME]]* at *[[TIMESTAMP]]*"
Pre-processor command: FO
-------------------------
*New in version 2.0*
NOTE: The FO tag is only currently supported in RTF generation.
This in-line tag allows the font used in a document to be changed, either
locally within some text, or from this point onwards.
The FO tag should be used in conjunction with a [[goto Using Style Definition Files (SDF),Style Definition File (SDF)]], which can be
used to define the "font id"s that are used
Syntax:
FO [],[],[]
where
$_$_BEGIN_TABLE
$_$_TABLE_LAYOUT 2,24,132
Identifies the font to be used. This must match the
name of a font in the SDF file. If no name is given then
the prevailing font will be used.
The font size in pts. Only needed if the default
value in the font table is to be overridden.
The size can be supplied as an absolute value or - if a plus or
minus sign is present - as a relative size. So for example
"4" means 4pt, whereas "+4" means 4pt larger than the
surrounding text.
A value of "-" will be taken as a reset to the prevailing
default font size.
The font weight. Only needed if the default value
in the font table is to be overridden. Possible values
are
it (Italic)
bo (Bold)
bi (Bold Italic)
no (Normal)
- (Reset)
The "reset" will cause the weight to be reset to the
prevailing default, i.e. no longer override the
prevailing font.
$_$_END_TABLE
Example:
$_$_BEGIN_PRE
"This text is [[ot]]fo ,+6,bo[[ct]]big and bold,[[ot]]fo ,-,-[[ct]] but this text is
normal again"
$_$_END_PRE
becomes
"This text is [[fo ,+6,bo]]big and bold,[[fo ,-,-]] but this text is
normal again"
(this may only work in the RTF version of this document)
See also [[goto Scope for font tags]]
Pre-processor command: FRACTION
-------------------------------
This in-line tag implements a fraction
Syntax:
[[OT]]FRACTION [[CT]]
where
$_$_BEGIN_TABLE
This is the fraction expression which should contain
a slash ("/") separating the numerator and denominator
Both values must be present.
$_$_END_TABLE
So for example
The fractions [[OT]]FRACTION 5/16[[CT]] and 1[[OT]]FRACTION 1/2[[CT]].
becomes
The fractions [[FRACTION 5/16]] and 1[[FRACTION 1/2]].
Pre-processor command: GOTO
---------------------------
_New in version 2.0_
This in-line tag adds a hyperlink to the named section heading.
Syntax:
[[OT]]GOTO [[CT]]
where
Name of a heading else where in the file.
The text used must match exactly for this tag
to work (case insensitive though)
It creates a hyperlink to the named section heading. The heading must match
the text exactly, and be in the same file. It must also have been recognised
by AscToRTF as a heading.
If making RTF Winhelp source files, see also the [[POPUP Pre-processor command: POPUP,POPUP]] command.
Pre-processor command: POPUP
----------------------------
_New in version 2.0_
This in-line tag adds a hyperlink to the named section heading.
Syntax:
[[OT]]POPUP [[CT]]
This behaves in an identical manner to the [[goto Pre-processor command: GOTO,GOTO]] unless
you are creating an RTF file for use as a Windows Help file, in which
case the hyperlink link becomes a pop-up link, instead of a full "go to" link.
Pre-processor command: SUPER and SUB
------------------------------------
These in-line tags implement superscripts and subscripts
Syntax:
[[OT]]SUPER [[CT]]
[[OT]]SUB [[CT]]
So for example
$_$_BEGIN_PRE
This[[OT]]SUPER superscript[[CT]] and that[[OT]]SUB subscript[[CT]]
$_$_END_PRE
becomes
This[[SUPER superscript]] and that[[SUB subscript]]
Pre-processor command: IGNORE_THIS
----------------------------------
This is an in-line tag whose contents are ignored. Could be
used for comments
Syntax:
[[OT]]IGNORE_THIS [[CT]]
This tag is ignored. It is replaced by a single space in the output stream.
It could be used to add a brief comment to your source that would not appear
in the output.
See also the [[goto Pre-processor command: IGNORE,IGNORE]] command
Pre-processor command: INCLUDE
------------------------------
$_$_HELP_TOPIC_ID ID_PRE_INCLUDE
You can include one source file in another by using the include
command as follows:-
$_$_BEGIN_PRE
$_$_INCLUDE filename
$_$_END_PRE
Make sure the file is accessible from wherever AscToRTF is run,
or in the same directory as the original source file. AscToRTF
will read the file on each pass, treating its contents as part
of the main file for both analysis and conversion purposes.
Note, the include file should be plain text, which will be
converted as normal for the document. It may include other
pre-processor commands including further INCLUDE commands up to
a limit of 9 levels. Be careful not to set up include loops
(i.e. a includes b include c includes a etc).
Include files like this can be a useful way of embedding standard
disclaimers etc, and compliment the use of header and footers.
Pre-processor command: PAGE
---------------------------
_New in version 2.0_
The syntax is
$_$_PAGE
This signals a page boundary. In RTF generation a page break will be generated
at this point. In HTML the concept of page boundaries isn't really supported,
so a horizontal rule
is put out instead.
Pre-processor command: VERSION
------------------------------
This in-line tag adds a description of the program name/version used to
convert the files (e.g. "AscToRTF 2.1")
Syntax:
[[OT]]VERSION[[CT]]
Outputs the version name of the conversion into the output file. For example
"[[VERSION]]".
$_$_HELP_CHAPTER 1,"Using Table definitions Files to improve table handling"
$_$_HELP_SUBJECT "Overview of Table Definition Files (TDF)"
Using Table Definition Files (TDF)
**********************************
$_$_HELP_TOPIC_ID HIDD_TDF_FILE
AscToRTF has the ability to detect and analyse tables. However, if you
want to convert a file containing multiple tables, or to convert
multiple files containing a variety of tables, it may be useful to create
a "Table Definition File" (TDF). In this file you can define multiple table
types, and each type can be associated with a particular structure and
a particular format.
By associating a table type with a structure, you are telling the software
how the table is laid out, thereby simplifying it's task, and reducing
the likelihood of analysis errors.
By associating a table type with a format, you can control various aspects
of how the final table looks. This feature was mainly added for HTML conversion
where, for example, you can associate CSS styles with columns, allowing tables
of a known type to have their columns formatted through an external stylesheet.
In RTF conversion there are far fewer formatting options available.
The use of TDFs was added for a future version of [AscToHTM], and they
allow you to define features that fine tune the HTML created by AscToHTM.
These features are not described here, but will be described in full in
the appropriate section of the [Table Manual]
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION MAKINGRTF
See
- [[goto Loading the Table Definition File]]
and
- [[goto Defining a table type]]
- [[goto Defining a table structure]]
- [[goto Defining a table format]]
$_$_SECTION ALL
Loading the Table Definition File
=================================
All the table definition information should be placed in a "Table Definitions File"
(TDF). By convention this file should have a ".inc" extension, but this
isn't a requirement.
To have the file loaded, you will need to set a policy line in your policy
file of the form
$_$_BEGIN_PRE
[config files]
Definitions file : table_definitions.inc
$_$_END_PRE
This will normally appear in the "[config files]" section of your policy
file, but again this isn't strictly necessary.
Once this option appears in your policy file, the table definitions file
will be loaded before the conversion process starts. During the conversion
each table that is found will be tested against the known table types, and
if a match is made, any associated structure and formatting will be applied.
You can select the Style Definition File that you want from the
_Config File locations_ menu option.
Sample Table Definition File
============================
Here is a sample Table Definition File (TDF). This example is primarily geared
towards creating a HTML table with coloured alarm states from a financial
results table.
$_$_BEGIN_PRE
table type : TradeDate
must contain : TradeDate Momentum SinceSig
use format : F_TradeDate
use structure : S_TradeDate
table structure : S_TradeDate
Layout : 6,7,39,51,61,71,80
table format : F_TradeDate
column names : ,,,Momentum,SinceSig
column format : name=Momentum alarms="Momentum_red,Momentum_green"
column format : name=SinceSig alarms="SinceSig_red,SinceSig_green"
alarm : name=Momentum_red type=LE value=0.0 alarm_color=red
alarm : name=Momentum_green type=gt value=0.0 alarm_color=green
alarm : name=SinceSig_red type=LE Value=0.0 alarm_color=red
alarm : name=SinceSig_green type=gt value=0.0 alarm_color=green
HTML attributes : onMouseover="changeto(event, 'white')"
$_$_END_PRE
This example consists of three sections;
- [[goto defining a table type,the table type section]]
- [[goto defining a table structure,the table structure section]]
- [[goto defining a table format,the table format section]]
Although this example has just one of each section type, in more complex
conversions you might have multiple Table Types sharing just a handful
of Table Structures and Table Formats.
$_$_HELP_CHAPTER 2,"Identifying table types"
$_$_HELP_SUBJECT "Defining a Table Type section"
Defining a Table Type
=====================
Whenever the software identifies a candidate table, it will check against
the Table Definitions File (TDF) to see if this is a table of a known type.
If it is, it will apply any defined structure or formatting for that type to
the candidate table.
Table types are defined by having a series of table type sections something
like the following in your definition file
$_$_BEGIN_PRE
table type : Rank
must contain : Rank ROC5 ROC10 ROC21
use format : format_rank
use structure : structure_rank
$_$_END_PRE
Each table type section starts with the [[goto TDF line: table type,table type]] line, and is followed by
a number of additional definition lines that apply to this table type.
*NOTE: The [[goto TDF line: use format,use format]] and [[goto TDF line: use structure, use structure]]
lines are optional, although you would want at least one to be present
for the table type to have any real use.*
Each table type section must contain at least one "identifier" line.
Identifier lines are those that specify conditions by which tables of
this type can be identified.
*NOTE: At present the only identifier line supported is the
[[goto TDF line: must contain,must contain]] line*
The identifier line(s) specify conditions that are used to test each table to
see if it could be of this type. Commonly the test is a search for text
that is present in the header of all tables of this type.
If multiple table type sections are defined, then the first table type whose
identifiers match the table is used, so the ordering of table type sections
within the definition file can be important.
For example :-
$_$_BEGIN_PRE
table type : type_1
must contain : Rank
...
table type : type_2
must contain : date Rank
...
$_$_END_PRE
In the above example any table that contains a line of text containing
"date rank" would match both table types. Since type_1 is listed first, all
such tables would be treated as type_1. In this case it would be better to
define type_2 first as below
$_$_BEGIN_PRE
table type : type_2
must contain : date Rank
...
table type : type_1
must contain : Rank
...
$_$_END_PRE
With the above definitions, a table containing "date rank" would be assigned
to type_1, one which simply contained "rank" would be type_2
TDF line: Table type
--------------------
The presence of a "table type" line in the definition file marks the
start of a new table type definition. The line has the format
$_$_BEGIN_PRE
table type :
$_$_END_PRE
where is the a unique name for this type of table, and shouldn't
contain any spaces.
TDF line: Must contain
----------------------
The "must contain" line is an identifier line. That is it is a condition
applied against a candidate table to see if it matches this table type.
The line has the format :
$_$_BEGIN_PRE
must contain :
$_$_END_PRE
The candidate table is tested line-by-line, so the text to be matched must
be wholly contained within one line of the source text. When testing the
match expression the case of the text being tested is ignored, and all
multiple white space is treated as a single space. So the match text
"Date rank" will match the word "date" followed by any number of spaces and
tabs, followed by "rank".
A good use of this line would be to match the know headers in a table,
e.g.
$_$_BEGIN_PRE
must contain : Date Temperature Max Min
$_$_END_PRE
would match a table with headers "Date", "temperature", "MAX" and "MIN" if
they were in that order, regardless of the spacing.
*NOTE: AT present only one "must contain" line per table type is supported*
TDF line: Use Structure
-----------------------
The "use structure" line specifies that if a table matches the identifying
conditions for this table type, then it's structure should be interpreted
according to the rules specified in the named table structure section.
This line has the form
$_$_BEGIN_PRE
use structure :
$_$_END_PRE
where is the name of a table structure section defined
elsewhere in the definition file. The should contain
no spaces.
The same structure may be shared by multiple table types, that is several
table type sections could all end up having the same "use structure" line.
If the given doesn't match a structure defined elsewhere
in the definition file, then the software will report this error each time it
matches a table of this type and then fails to locate the named structure.
That is it gives a runtime error, rather than reporting the error when the
definition file is loaded.
*NOTE: This may change in later versions*
See [[goto Defining a table structure]]
TDF line: Use Format
--------------------
The "use format" line specifies that if a table matches the identifying
conditions for this table type, then it should be formatted according to
the rules specified in the named table format section.
This line has the form
$_$_BEGIN_PRE
use format :
$_$_END_PRE
where is the name of a table format section defined elsewhere
in the definition file. The should contain no spaces.
The same format may be shared by multiple table types, that is several table
type sections could all end up having the same "use format" line.
If the given doesn't match a format defined elsewhere in the
definition file, then the software will report this error each time it
matches a table of this type and then fails to locate the named format.
That is it gives a runtime error, rather than reporting the error when the
definition file is loaded.
*NOTE: This may change in later versions*
See [[goto Defining a table format]]
$_$_HELP_CHAPTER 2,"Defining table layouts"
$_$_HELP_SUBJECT "Defining a Table Structure section"
Defining a Table Structure
==========================
Table structures are defined by having a table structure section something
like the following in your definition file
$_$_BEGIN_PRE
table structure : Percent_funds
Layout : 6,31,41,51,61,71,81
$_$_END_PRE
Each table structure section starts with the [[goto TDF line: table structure,table structure]] line, and
is followed by [[goto TDF line: layout,layout]] line.
TDF line: Table structure
-------------------------
The presence of a "table structure" line in the definition file marks the
start of a new table structure definition. The line has the format
$_$_BEGIN_PRE
table structure :
$_$_END_PRE
where is the a unique name for this structure, and
shouldn't contain any spaces. The is the name used in
any "[[goto TDF line: use structure,Use structure]]" statement in a table type section.
TDF line: Layout
----------------
The Layout line in a table structure section describes how the matched table
should be interpreted into columns. The format of the Layout line is the
same as that used by the [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] pre-processor
command.
$_$_BEGIN_PRE
Layout : 6,7,39,51,61,71,80
$_$_END_PRE
For example the above line specifies the data comes in 6 columns which end
at the column positions 7, 39, 51.. etc
$_$_HELP_CHAPTER 2,"Defining table formats"
$_$_HELP_SUBJECT "Defining a Table Format section"
Defining a Table Format
=======================
NOTE: Most table formatting only applies to HTML conversion by [AscToHTM]
and not RTF conversion by AscToRTF
Table formats are defined by having a table format section something
like the following in your definition file
$_$_BEGIN_PRE
table format : Rank
column names : ,,,ROC5,ROC10,ROC21
caption : Rankings
table colour : #E1D1C1
border colour : #E2E2E2
Colour data rows : Yes
border size : 2
HTML attributes : onmouseover='click'
HTML cell attributes : nowrap
show columns : no,no,no,,,,,,,,
$_$_END_PRE
TDF line: Table format
----------------------
The presence of a "table format" line in the definition file marks the
start of a new table format definition. The line has the format
$_$_BEGIN_PRE
table format :
$_$_END_PRE
where is the a unique name for this format, and
shouldn't contain any spaces.
The is the name used in any "[[goto TDF line: use format,Use format]]" statement in
a table type section.
TDF line: Column names
----------------------
The "Column Names" line allows you to give each column a name. This name should
be unique, and can be referenced in more advanced configuration lines.
However these options are not available in RTF generation.
TDF line : Caption
------------------
The "Caption" line allows you to add a caption to any table that matched
the table type conditions.
However this option is not yet implemented in RTF generation.
TDF line: Table colour
----------------------
The "Table Colour" line allows you to specify a background colour for the
table.
However this option is not yet implemented in RTF generation.
TDF line: Border colour
-----------------------
The "Border Colour" line allows you to specify a border colour for the
table.
However this option is not yet implemented in RTF generation.
TDF line: Colour data rows
--------------------------
The "Colour data rows" line allows you to specify that odd and even rows of
the table should be coloured differently to allow the table to be more easily
understood.
However this option is not yet implemented in RTF generation.
TDF line: Border size
---------------------
The "Border size" line allows you to specify a border colour for the
table.
However this option is not yet implemented in RTF generation.
TDF line: HTML attributes
-------------------------
The "HTML attributes" line only applies to HTML generation by [AscToHTM]
TDF line: HTML cell attributes
------------------------------
The "HTML cell attributes" line only applies to HTML generation by [AscToHTM]
TDF line: Show columns
----------------------
Format is
show columns : ,,...
where is either "yes" or "no" or blank. If blank it's taken to
be "yes" for all columns
This line specifies whether or not each column should be included in the
output. If your table has been exported in CSV format from a spreadsheet
it may contain "work" columns that you don't want shown. This option allows
you to specify that.
$_$_HELP_CHAPTER 1,"Using Style Definition Files to improve table handling"
$_$_HELP_SUBJECT "Overview of Style Definition Files (SDF)"
Using Style Definition Files (SDF)
**********************************
$_$_HELP_TOPIC_ID HIDD_SDF_FILE
As of version 2.0, AscToRTF allows more control over the fonts used to
add style to the document text.
Several users of AscToRTF are feeding output of typesetting software into
AscToRTF as text input. In many cases these users commented that they had
detailed knowledge of how the RTF should be formatted, but were having to
discard that information in the text passed to AscToRTF, with a resulting
loss of details.
Changes have been made in version 2.0 to allow better integration between
the original document and the RTF created by AscToRTF.
These changes allow you to define various font styles in a _Style Definition File_
and to then invoke these files by placing FO (font) tags into the source document.
You can choose to have a FO tag apply from that point onwards, until the next
paragraph/heading/table or just until the end of the current input line. In any
case a new FO tag will override the previous setting.
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION MAKINGRTF
See also
- [[goto Loading the Style Definition File (SDF)]]
- [[goto Pre-processor command: FO]]
- [[goto Scope for font tags]]
$_$_SECTION ALL
Loading the Style Definition File (SDF)
=======================================
All the style definition information should be placed in a "Style Definition File"
(SDF). By convention this file should have a ".inc" extension, but this
isn't a requirement.
To have the file loaded, you will need to set a policy line in your policy
file of the form
$_$_BEGIN_PRE
[config files]
Style Definitions file : Style_definitions.inc
$_$_END_PRE
This will normally appear in the "[config files]" section of your policy
file, but again this isn't strictly necessary.
Once this option appears in your policy file, the style definition file
will be loaded before the conversion process starts.
You can choose the Style Definition File by selecting the menu option
_Conversion Options -> Configuration Files -> Style Definition File_
This will take you to a dialog for [[goto Selecting the Style Definition File]]
An Example Style Definition File
================================
At present only font declarations can be included in a Style Definition File.
Below is a simple example that simply defines the three font styles Fixed,
Heading and Body.
$_$_BEGIN_PRE
define font : Fixed, Courier New, regular, 10
define font : Heading, Arial, regular, 10
define font : Body, Times New Roman, regular, 10
$_$_END_PRE
See [[goto SDF line : define font]]
SDF Line : define font
----------------------
The *define font* line defines a font that can be referenced by a FO tag
in the source document.
Syntax:
$_$_BEGIN_PRE
define font : ,
$_$_END_PRE
Where,
$_$_BEGIN_TABLE
font_ID This is a unique name given to the font specification
as it will be used in the FO tag
font_specification This is the specification of the font to be used
whenever an FO tag references this font_ID.
$_$_END_TABLE
The *font_specification* consists of a comma delimited list of the font
name, the weight and the font size. This is the same format as described
in the [[goto The Font Selection Dialog]]
Example:
define font : Fixed, Courier, bold, 12
This defines a *font_ID* called "fixed". This equates to a Courier font
which is set bold and to be 12pt. If in my source text I add the tag
[[OT]]FO fixed,,14[[CT]]
The the following text will be Courier, Bold and 14pt (because the FO tag
has overridden the specified font size).
See also [[goto Pre-processor command: FO]]
$_$_HELP_CHAPTER 1,"Using Text commands to modify the source text"
$_$_HELP_SUBJECT "Overview of Text Command File"
Using Text Command Files
************************
$_$_HELP_TOPIC_ID HIDD_TEXTSUBS_FILE
*New in version 2.0*
As of version 2.0, AscToRTF allows the use of "Text Commands". These are
commands that allow you to modify the text before it is converted, or
to label certain lines as being of a particular type.
The commands should be placed in an external "Text Command File". This
file can be chosen from _Conversion Options -> Config File Locations_ menu
option.
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION MAKINGRTF
Various commands are available as follows
$_$_BEGIN_DELIMITED_TABLE
[[goto Text Command : ignore_line,ignore_line]] Identifies lines to be discarded from the input
[[goto Text Command : remove_text,remove_text]] Identifies text to be removed from the input
[[goto Text Command : replace_text,replace_text]] Identifies text to be replaced by other text
[[goto Text Command : treat_line,treat_line]] Identifies how a line should be treated
[[goto Text Command : meta_tag_line,meta_tag_line]] Identifies lines to be converted into META tags in HTML
$_$_END_DELIMITED_TABLE
$_$_SECTION ALL
$_$_HELP_CHAPTER 2,"Text Commands"
Text Commands available
=======================
$_$_SECTION MAKINGRTFHELP
Various commands are available as follows
$_$_BEGIN_DELIMITED_TABLE
[[goto Text Command : ignore_line,ignore_line]] Identifies lines to be discarded from the input
[[goto Text Command : remove_text,remove_text]] Identifies text to be removed from the input
[[goto Text Command : replace_text,replace_text]] Identifies text to be replaced by other text
[[goto Text Command : treat_line,treat_line]] Identifies how a line should be treated
[[goto Text Command : meta_tag_line,meta_tag_line]] Identifies lines to be converted into META tags in HTML
$_$_END_DELIMITED_TABLE
$_$_SECTION ALL
Text Command : ignore_line
--------------------------
The *ignore_line* command identifies lines that should be ignored in the input.
Syntax:
$_$_BEGIN_PRE
ignore_line
$_$_END_PRE
Any line matching the specified [[goto line_selection]] criteria will be ignored
in the output. This can be a useful way of ignoring page markers in an
input file, as these don't always transfer well under the conversion.
Text Command : remove_text
--------------------------
The *remove_text* command identifies text that should be removed from the input.
Syntax:
$_$_BEGIN_PRE
remove_text "match string"
$_$_END_PRE
Any line containing text that matches the specified [[goto match_type]] for the supplied
"match string" will have the matching text removed.
Text Command : replace_text
---------------------------
The *remove_text* command identifies text that should be removed from the input.
Syntax:
$_$_BEGIN_PRE
replace_text "match string" by_string "new string"
or
replace_text "match string" by_character ""
$_$_END_PRE
Any line containing text that matches the specified [[goto match_type]] for the supplied
"match string" will have the matching text replaced.
If the replacement is specified as
by_string "new string"
then the text is replaced by the new string. If the replacement is specified as
by_character ""
then the string is replaced by a string of equal length consisting of this single
character repeated. This can be useful for example to replace change bar characters
by spaces in a document where the change bars have confused the program, or to
replace other characters inside a table that are confusing the detection of the
table's true layout.
Text Command : treat_line
-------------------------
The *treat_line* command allows you to specify how a line should be regarded
during the analysis of the file.
Syntax:
$_$_BEGIN_PRE
treat_line
$_$_END_PRE
With this command any line that matches the specified [[goto line_selection]]
criteria will be regarded as the specified [[goto as_line_type]].
For example the command
$_$_BEGIN_PRE
treat_line starting_with string "news" as_header_1
$_$_END_PRE
specifies that any line in which the string "News" is found at the start
should be considered as a level 1 heading.
Text Command : meta_tag_line
----------------------------
The *meta_tag_line* is meant solely for HTML conversion. It identifies lines
that should be converted into HTML META tags.
Syntax:
$_$_BEGIN_PRE
meta_tag_line "tag name" [remove_match_text]
$_$_END_PRE
This command specifies that any line matching the [[goto line_selection]] criteria
should be used to create a META tag called "tag name". The value of this
META tag will be the line itself. If the *remove_match_text* argument is
supplied, the match text itself will be removed from the value.
For example the command
$_$_BEGIN_PRE
meta_tag_line "author" starting_with string "author: " remove_match_text
$_$_END_PRE
Will match the line
Author: Dr John A Fotheringham
will remove the "author: " from this line, and create a META tag as follows
This can be useful when processing text files created by other systems that
add "tagging" and catalogue information at the top.
Note: You could combine this command with a matching [[goto Text Command : ignore_line,ignore_line]] command
to ensure that the line became a META tag, but wasn't included in the conversion
output itself.
$_$_HELP_CHAPTER 2,"Text Command Line syntax elements"
Text Command line elements
==========================
$_$_SECTION MAKINGRTFHELP
The following Text command line elements are used by several commands
$_$_BEGIN_DELIMITED_TABLE
[[goto line_selection]] Complete specification of how to match a line
[[goto line_match]] Location of text within line
[[goto match_type]] Type of text matching required
[[goto replace_type]] Type of text replacement wanted
[[goto as_line_type]] How to treat a "treat_line" line
$_$_END_DELIMITED_TABLE
$_$_SECTION ALL
line_selection
--------------
The *line_selection* element is actually a combination of a number
of simpler elements as follows
Syntax:
$_$_BEGIN_PRE
"match string"
$_$_END_PRE
That is the *line_selection* consists of a [[goto line_match]], a [[goto match_type]], and
then the actual "match string" to be matched. All three elements must be
present in order for the *line_selection* to be valid.
The following are all valid examples
$_$_BEGIN_PRE
starting_with string "Chapter"
starting_with exact_phrase "Author : "
containing phrase "click here"
containing string "http://"
$_$_END_PRE
line_match
----------
The *line_match* element specifies where on the input line the specified
text should be located. The options are
$_$_BEGIN_DELIMITED_TABLE
starting_with Text should be at start of line (ignoring any white space)
containing Text can be anywhere on the input line
$_$_END_DELIMITED_TABLE
Care should be used when using the *containing* option, as false matches
are more likely to occur.
match_type
----------
The *match_type* element specifies how any supplied match string should be
matched. The options are
$_$_BEGIN_TABLE
string This specifies that a string should be matched.
This is, in fact, the most general of match types
and is the one that would normally be used. This
match type is case-insensitive.
exact_string Same as "string", but case-sensitive.
phrase A "phrase" is a string that is surrounded by white space
and/or punctuation on either side (see below).
This match type is case-insensitive
exact_phrase Same as "phrase", but case-sensitive.
wildcard Not yet supported (*)
$_$_END_TABLE
The *match_type* _phrase_ is a special case. This is a _string_ that is surrounded
by white space or punctuation on either side. So whereas the _string_ "the" would
match "then", the _phrase_ "the" wouldn't because the "n" in "then" is not a
white space character.
The start and end of a line count as white space, and any leading or trailing
punctuation is allowed. _Phase_ is therefore a more precise match - even for
single words - than _string_.
Consider the following example, concentrating on the letters "ten" in the
word "tense"
This is a tense situation....
The following would apply
$_$_BEGIN_TABLE
$_$_TABLE_LAYOUT 2,32,90
match_type Matches?
-------------------------------------------------------
string "ten" Yes. The "ten" matches the first three
characters in "tense" in the middle
extact_string "Ten" No. The "t" in "tense" is lower case, so
the match fails
phrase "ten" No. "ten" is not surrounded by white space
or punctuation because it is followed by "se"
exact_phrase "tense situation" Yes. The case matches, and there is a space
before and punctuation (the "...") afterwards.
$_$_END_TABLE
replace_type
------------
The *replace_type* element is used in the [[goto Text Command : replace_text,replace_text]] command to specify
what type of text replacement should be executed. The element should
be immediately followed by the replacement text in quotes.
There are two options:-
$_$_BEGIN_TABLE
by_string The matched text should simply be replaced
by the replacement text.
by_character The matched text should be replaced by an
equal length string composed solely of the
single character in the replacement text.
$_$_END_TABLE
The *by_character* option allows a string to be "blanked out" by the
character of your choice, but without altering the line length or
spacing etc. This can be useful, for example to replace all DOS
line drawing characters by blanks in table, so as to let the software
make a better stab at detecting the table layout.
as_line_type
------------
The *as_line_type* element is used by the [[goto Text command : treat_line,treat_line]] command to specify how
the matching line should be treated. The *as_line_type* assigns to
the matching line a type that would otherwise have to be automatically
be detected by the program. It can therefore help the analysis if you
can tell the program how such lines should be treated.
The options are
$_$_BEGIN_TABLE
as_heading_ Where is "1","2"..."6". The matched
line is treated as a heading of level
as_bullet The matched line is treated as being
an unordered list item (bullet)
as_alpha_bullet The matched line is treated as being an
item on an alphabetic list.
as_capalpha_bullet The matched line is treated as being an
item on an UPPER CASE alphabetic list.
as_roman_bullet The matched line is treated as being an
item on an roman numeral list.
as_caproman_bullet The matched line is treated as being an
item on an UPPER CASE roman numeral list.
as_quoted The matched line is treated as being "quoted
text" such as lines in emails that start with
a ">" are.
as_new_page The matched line is treated as being the
start of a new page.
as_number_bullet The matched line is treated as being an
item on a numbered list.
$_$_END_TABLE
For example the command
treat_line starting_with string ":" as_quoted
can be used to ensure that lines that start with ":" are treated as
if they are "quoted text" such as one finds inside emails. See
[[goto quoted line detection]]
$_$_HELP_CHAPTER 2,"An example Text Command File"
$_$_HELP_SUBJECT "Text Command file
An example Text Command File
============================
Below is an example Text Command file:
$_$_BEGIN_PRE
treat_line starting_with exact_string "new page" as_new_page
treat_line starting_with string "head_1" as heading_1
treat_line starting_with string "head_2" as heading_2
treat_line starting_with string "head_3" as heading_3
remove_text exact_string "head_1"
remove_text exact_string "head_2"
remove_text exact_string "head_3"
ignore_line containing exact_string "PAGE"
$_$_END_PRE
In this example lines starting with "new_page" are treated as page
breaks. Lines starting with "head_1" etc are treated as headings, and
then the text "head_1" is removed. In this way you could label your
heading lines without the labelling appearing in the output. Finally
any line containing the exact_string "PAGE" is discarded. Note that
by using "exact_string" you ensure that the case is matched so "PAGE"
matches but "page" does not.
$_$_HELP_CHAPTER 1,"Creating WinHelp files"
$_$_HELP_SUBJECT "Overview of creating WinHelp files"
Creating WinHelp files
**********************
*New in version 2.0*
From version 2.0 onwards, AscToRTF now has the ability to create RTF files
that are suitable for use as source documents when creating WinHelp files
(.hlp)
Of course, the current flavour of Microsoft help files is the compiled
HTML format (.chm), but many authors still prefer the .hlp format.
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION ALL
Some background on WinHelp files
================================
WinHelp files can be created using the free Microsoft Help Workshop tool
HCW. If you don't already have this installed, you can easily download
this from the Microsoft web site.
The HCW file allows you to define help projects, the details of which
are saved in a [[goto help project file (.hpj)]]. This file contains
the details of your project which will include, among other things
- the name of the [[goto source file (.rtf)]] to be used to create
the text in the Help file
- the name of the [[goto contents file (.cnt)]] to be used as the
contents of the Help file
- Other configuration options such as colours, window sizes etc.
If you're making a help file to support a software application, then the
project file will also contain
- The name of the [[goto resource file (.hm)]] which identifies the
topic IDs that may be requested from inside the software.
It is not the purpose of this document to give a full introduction to
HCW, just to give a flavour of how it works, and how it can be used
with AscToRTF.
Essentially HCW acts as a compiler, that merges these files together so
that you end up with a Help file (.hlp) and a contents file (.cnt) that
go together, and which can then be distributed as a standalone Windows
Help file.
In order for HCW to know how to divide the help into topics, and how
to index and cross-reference these topics, the source RTF file has to
have special formatting applied and has to follow certain rules. For
more details see [[goto Formatting RTF files for use as WinHelp source documents]]
AscToRTF can turn your text file into an RTF file that obeys these rules,
and furthermore can create a good starting Help Project file and contents
list for you. With it's pre-processor, you can add links between topics
and even produce help files that can be invoked from inside application
software. Although the help files produced may be basic (they can't contain
images for example), there will be no easier way to turn your text document
into fully featured WinHelp files.
$_$_HELP_CHAPTER 2,"Formatting RTF for use in WinHelp projects"
Formatting RTF files for use as WinHelp source documents
========================================================
This section outlines just some of the special formatting rules AscToRTF
will apply when you elect to convert your text into a WinHelp source
document.
How to create topics
--------------------
Each topic in the RTF file must begin on a new page. AscToRTF makes
each section heading in your source document a heading on a new page.
For long topics you can stop the title scrolling as you scroll down the
page by applying the "keep with next" attribute to the heading lines.
Because of this, you should avoid using "keep with next" anywhere else
as it confuses the compiler. For this reason AscToRTF doesn't apply this
property to tables and diagrams in the way that it does in normal RTF
production.
To allow linking to a topic, each topic is given a topic ID. The topic
ID is identified by adding a footnote to the heading on the hash character
(#). The text in this footnote is the topic ID, which is best kept as a
single string without spaces in it.
To allow a topic to appear in the Help index, you need to add a second
footnote on the dollar character ($). The text in this footnote should be
a single line description for the index.
To allow a topic to be located by keywords, you need to add a third
footnote on the character 'K'. The text in this footnote should list the
keywords for this topic.
AscToRTF will create all these footnotes for you. It will invent an
ID for you, or - if you supply a HELP_TOPIC_ID pre-processor command, use
that instead. See the [[goto HELP_TOPIC_ID command]]
How to create links to topics
-----------------------------
Links to topic are done as follows
- The Display text for the link is underlined
- this is *immediately* followed (i.e. no white space) by the topic
ID, which must be placed in hidden text.
For the linked topic to appear in a popup box, use a single underline.
For the linked topic to fill the main window, use a double underline.
For reasons not immediately clear, topics with a heading level of 1
can't be invoked in popup windows.
Manually editing such strings is tiresome beyond belief. Happily the
AscToRTF pre-processor makes this much easier by providing the GOTO and
POPUP tags, which are used to generate full and popup links as follows
$_$_BEGIN_PRE
- [[OT]]GOTO how to create topics[[CT]]
- [[OT]]POPUP how to create topics[[CT]]
$_$_END_PRE
becomes
- [[GOTO how to create topics]] (GOTO link)
- [[POPUP how to create topics]] (POPUP link)
Browse sequences
----------------
WinHelp allows you to link topics in a "browse sequence" so that by
pressing the "<<" and ">>" buttons you can move from one topic to the
next and previous logical topics.
This is configured through use of footnotes on the plus sign (+)
AscToRTF adds footnotes so that your entire help file can be browsed
as a single sequence.
How to create hyperlinks to URLs
--------------------------------
AscToRTF can convert URLs into working hyperlinks in the RTF it creates.
These links will also work inside the WinHelp file created from the
RTF source file.
$_$_HELP_CHAPTER 2,"Compiling RTF files into WinHelp files"
$_$_HELP_SUBJECT "Running Microsoft's Help Compiler Workshop (HCW)"
Running Microsoft Help Compiler Workshop (HCW)
==============================================
The Help Compiler Workshop (HCW) will probably be installed on your
system if you have already installed some programming tools such as
visual studio. Otherwise you can download it from
http://download.microsoft.com/download/win95/MSPRESS/1.0/W9X/EN-US/hcwsetup.EXE
or goto http://download.microsoft.com/ and search for "Help Compiler
Workshop" It is a free download.
In HCW you will be prompted to open a [[goto help project file (.hpj)]].
Help project file (.hpj)
------------------------
This file identifies the RTF file(s) to be converted, the Help file title,
resources etc. You can edit the settings using HCW's options, and it is
recommended that you study HCW's own help file for more details on this.
AscToRTF can create a project file for you, with some of these details
filled in. It is recommended you do this the first time you convert
the text file to RTF, but be aware that if you repeat this any existing
.hpj file will be overwritten, and any changes made since the last time
the file was created will be lost.
Amongst other things, the project file identifies
- The [[goto source file (.rtf)]] to be used
- Any [[goto resource file (.hm)]] to be used
Source file (.rtf)
------------------
The main input into the Help Compiler is one or more RTF files. These have
to be formatted in a particular way to achieve all the particular effects
required of a Help Manual.
When you select a conversion type of "Making Windows Help source file",
AscToRTF does all this formatting for you.
See [[goto Formatting RTF files for use as WinHelp source documents]]
Contents file (.cnt)
--------------------
WinHelp files can have their own contents files. By convention these have
the same name as the .hlp file, but with a .cnt extension. When you
convert your text file into a WinHelp source file and elect for AscToRTF
to create a project file, AscToRTF will also create a .cnt file for you
with all the chapter and section headings listed in it.
This relies on AscToRTF correctly detecting all the headings in your source file.
To achieve this see the topic [[goto creating headings]] in the section called
[[goto Tips on how to write text files for AscToRTF]]
Resource file (.hm)
-------------------
Software developers can use AscToRTF to create context-sensitive help for
their applications. This allows users to press F1 anywhere in the program
and be taken to the corresponding topic in the Help file. Indeed exactly
this approach has been used in the AscToRTF help file itself.
To achieve this it is necessary for the Help Compiler to be aware of the
IDs allocated to key controls within the application, and for topics in the
RTF file to be associated with a named control.
The first of these steps is achieved by telling the compiler where the
resource file from your software project is. This is usually a .hm file
created automatically by your software development tool each time you build
your application.
If you tell AscToRTF where this file is located, then when it creates the
Help project file, it will add an entry identifying this file. Alternatively
you can add it manually to the project file yourself using HCW.
To link particular topics to named controls within your software you need to
add HELP_TOPIC_ID commands to your text file just before the heading of
the topic. See the [[goto HELP_TOPIC_ID command]]
$_$_HELP_CHAPTER 2,"How to write your text files with WinHelp in mind"
$_$_HELP_SUBJECT "Tips on how to write text files for AscToRTF"
Tips on how to write text files for AscToRTF
============================================
AscToRTF should be capable of converting files into good looking WinHelp
files just as well as it converts text files into good-looking RTF. However
in WinHelp soured files each new topic should begin on a new page, and
ideally has a topic heading at the top of that page.
To that end AscToRTF treats each "heading" as the start of a new topic.
Thus each "heading" gets a new page, special codes and an entry in any
generated [[goto contents file (.cnt)]].
Creating headings
-----------------
For that reason it is important that your document has clearly marked
headings that can be unambiguously understood. There are two main ways
to do this
a) Use numbered headings. If your document uses a clear numbering
system such as 1, 1.1, 1.2, 2, 2.1 etc, this will normally work
well. However AscToRTF can occasionally get confused, e.g. by
a numbered list at the same indentation as the expected headings,
so care has to be taken to eliminate any such ambiguities
b) Use underlined headings. AscToRTF will recognize any line that
is "underlined" as being a heading. That is, if the following
line is all "underline" characters ("*","=","-",) and of the same
length as the previous line, then this is an underlined heading.
In my experience using underlined headings works best. The possibilities
for error are less, and you don't need to renumber sections if you start
to move things around. For more details on how AscToRTF interprets
underlined headings see [[popup Expect underlined headings]]
This document has been created in exactly this way. If you locate the file
AscToRTF.txt you'll see exactly how this file was created.
Avoid "empty topics"
--------------------
In a structured document, it may happen that you have a title sequence
as follows
$_$_BEGIN_PRE
MAJOR TITLE
***********
Section Title
=============
First topic
-----------
The first text only starts here
$_$_END_PRE
While that works okay as a document, when creating a WinHelp source file,
each of these headings becomes a Help topic, and in the above example the
first two would be "empty" topics.
To get round this, you can add text to your document that will only get included
when making the RTF help file by using the SECTION command together with the
reserved section name MAKINGRTFHELP. For example
$_$_BEGIN_PRE
MAJOR TITLE
***********
$_$_SECTION MAKINGRTFHELP
This chapter contains the following sections:-
[[ot]]goto section title[[ct]]
$_$_SECTION_ALL
Section Title
=============
$_$_SECTION MAKINGRTFHELP
This Section contains the following topics:-
[[OT]]goto first topic[[ct]]
$_$_SECTION ALL
First topic
-----------
The first text only starts here
$_$_END_PRE
When this is converted to normal RTF, the output looks like the original,
but when converted to WinHelp RTF you get three topics, with the first
two containing links to the next topic, allowing the user to navigate
properly to the first topic.
See the [[goto Pre-processor command: SECTION,SECTION]] command and [[goto The MAKINGRTFHELP section name]]
$_$_HELP_CHAPTER 2,"Using HELP pre-processor commands"
$_$_HELP_SUBJECT "Overview of HELP pre-processor commands"
Using the pre-processor HELP commands
=====================================
Although you can use AscToRTF to turn your text files into WinHelp
files without further editing, if you want to exercise a bit more
control over the results, or if you want to create context sensitive
help for your software applications, then you will want to add the
following commands to your source file.
$_$_BEGIN_DELIMITED_TABLE
[[goto HELP_CHAPTER command]] Adds new chapter titles to your generated Contents file
[[goto HELP_SUBJECT command]] Adds a new subject title to you generated Contents file
[[goto HELP_TOPIC_ID command]] Associates a help topic with a named resource
from your software application
[[goto The MAKINGRTFHELP section name]] Allows you to add help file-only test to your source document
$_$_END_DELIMITED_TABLE
HELP_CHAPTER command
--------------------
The HELP_CHAPTER command creates a new "chapter" in the generated contents
file. A Chapter appears as a book that you can click on to go down
a level, but isn't a topic you can read in it's own right.
The syntax is
$_$_BEGIN_PRE
$_$_HELP_CHAPTER ,"Chapter title"
$_$_END_PRE
Where is 1,2,3... according to how many levels deep the chapter
should be in the contents list, and "Chapter title" is the title to appear
in the contents file.
You should place the HELP_CHAPTER command just before the heading that
starts the new chapter in the source document. If you want this new section
to also be a topic in its own right, you will need to add a [[GOTO HELP_SUBJECT command,HELP_SUBJECT]]
command as well.
For example
$_$_BEGIN_PRE
$_$_HELP_CHAPTER 1,"Using AscToRTF to make Help files"
$_$_HELP_SUBJECT "Overview of creating help files"
Creating WinHelp files
**********************
This is my topic text....
$_$_END_PRE
This will create a help chapter called "Using AscToRTF to make Help files"
in the contents list. If you click on that, the first topic will be
called "Overview of creating help files", and if you click on that, you
will be taken to the topic headed "Creating WinHelp files"
which starts "This is my topic..."
See also the [[goto HELP_SUBJECT command]]
HELP_SUBJECT command
--------------------
The HELP_SUBJECT command creates a new "subject" in the current chapter
of the generated contents file. This will appear as a small text icon,
in the contents list, and if you click on this you will be taken into
the matching topic in the help file.
The syntax is
$_$_BEGIN_PRE
$_$_HELP_SUBJECT "Subject text"
$_$_END_PRE
The default behaviour of AscToRTF is to treat each new section as a new
subject, so by default each new heading creates a new topic in the current
chapter of the contents file. As such a HELP_SUBJECT command is not required
for every new heading. However there are two situations in which the
HELP_SUBJECT is required:-
- [[popup Adding a topic after a change in heading level]]
- [[popup Changing the text in the contents file]]
You should place the HELP_SUBJECT command just before the heading that
starts the new topic in the source document.
Adding a topic after a change in heading level
..............................................
Whenever the next heading is at a different level to the
preceding one, a new Help "chapter" is created. A new "subject"
is *not* created by default, and so you need to explicitly add
a HELP_SUBJECT command there if you want the new level heading
to be a selectable topic. See the example given in the
discussion of the [[goto HELP_CHAPTER command]]
Changing the text in the contents file
......................................
By default the text shown in the contents is that of the heading title
itself. However this isn't always useful. For example the first
topic in a new section may be called just "Introduction". In a large
document that is fine, but in a Help File you soon end up with
a dozen "Introduction" sections in the index, and this is unhelpful.
In this case you can add a HELP_SECTION command to make the entry in
the Help file index more useful.
e.g.
$_$_BEGIN_PRE
$_$_HELP_SECTION "Introduction to WinHelp files"
Introduction
------------
WinHelp files are ...
$_$_END_PRE
HELP_TOPIC_ID command
---------------------
The HELP_TOPIC_ID identifies the ID that should be allocated to
a given topic. By default each topic will be allocated a unique
ID derived from the heading text.
The syntax is
$_$_BEGIN_PRE
$_$_HELP_TOPIC_ID
$_$_END_PRE
Where is a unique name that shouldn't contain any
spaces or punctuation characters. The HELP_TOPIC_COMMAND should
be placed just after the heading of the topic it relates to (see
example below)
Normally you won't need to add the HELP_TOPIC_ID command, as the
software will generate an ID and keep track of this when creating any
links to this topic.
However if you are trying to create a context-sensitive help file
for your software application you need to make the topic IDs match the
resource names in your [[goto Resource file (.hm)]].
For example if your .hm file contains a line like
$_$_BEGIN_PRE
HIDD_SETTINGS_DOCO 0x200B3
$_$_END_PRE
For a dialogue used to access the documentation, then your source
file would look like this :-
$_$_BEGIN_PRE
Documentation settings
......................
$_$_HELP_TOPIC_ID HIDD_SETTINGS_DOCO
These options allow you to specify the location of the program's
$_$_END_PRE
If this is done, and the .hm file is added to your [[goto help project file (.hpj)]]
then pressing F1 on the documentation dialogue will launch the help
file at the "Documentation Settings" topic.
The MAKINGRTFHELP section name
------------------------------
If you want to add text that gets included in the WinHelp RTF file,
but not in a normal RTF file, then you can use the [[goto Pre-processor command: SECTION, SCETION]] command
with the reserved section name MAKINGRTFHELP.
For example:-
$_$_BEGIN_PRE
This text will appear in all RTF files
$_$_SECTION MAKINGRTFHELP
(but this text will only appear in the Help RTF file)
$_$_SECTION ALL
This text will also appear in all RTF files
$_$_END_PRE
See [[goto "Avoid ""empty topics"""]] for a discussion of why you might want to do this.
$_$_HELP_CHAPTER 2,"Making context-sensitive help files for your applications"
$_$_HELP_SUBJECT "Integrating the help file with your software application"
Integrating the help file with your software application
========================================================
This section gives a brief overview of how to use AscToRTF to create a
WinHelp file that will provide context-sensitive help for your software
application.
By default when you press F1 on an application, Windows does the following
- identifies the control that had focus and gets its ID
- locates the help file for this application. By default this will
have the same name as the .exe file, but with a .hlp extension
- launches the help file, staring at the topic that matches the
ID (if such a topic exists).
See [[goto matching topic IDs]]
See [[goto setting the help file name]]
See [[goto "Create ""missing"" topics to get a clean compile"]]
Matching Topic IDs
------------------
The IDs used by your application are normally listed in a [[goto resource file (.hm)]]
generated by your software IDE. You need to add this to your [[goto help project file (.hpj)]],
or tell AscToRTF to add it for you when it generates the project file.
Inside your source text file you then need to add a [[goto HELP_TOPIC_ID command]]
to each topic to link it to the control names. Typically you will link
Dialog screens to major topics within your help file.
Setting the help file name
--------------------------
By default Windows expects your help file to have the same name as your application.
The easiest way to achieve this is to call your text file application.txt, so that
when it is converted it becomes application.rtf, and creates an application.hpj that
in turn will make an application.hlp.
You *can* make these files named whatever you want by editing the project file,
but it's easier to go with the flow.
Create "missing" topics to get a clean compile
----------------------------------------------
The Help Compiler Workshop will report as "missing" any ID in the resource
file for which it doesn't find a matching topic. To get round this I
recommend adding a [[goto HELP_TOPIC_ID command]] for each unused ID at
the top of the file. That way the compiler won't complain, and any dialogue
without a help topic will open up at the first topic in the help file.
$_$_HELP_CHAPTER 2,"Making HTML version of your WinHelp files"
$_$_HELP_SUBJECT "Overview of creating HTML version of your WinHelp files"
Creating HTML versions of your WinHelp files
============================================
As well as being able to make normal RTF and WinHelp files from the
same source file with AscToRTF, you could also use [AscToHTM] to
convert the same source file into HTML. Users who purchase AscToRTF
can get a discount on AscToHTM (and vice versa). Details will
be provided when you register your first product.
If you want to have different text in the three output formats
you can use the [[goto Pre-processor command: SECTION,SECTION]] command with the reserved section
names MAKINGRTF, MAKINGRTFHELP and MAKINGHTML.
For example:
$_$_BEGIN_PRE
This document has been converted from text to :-
$_$_SECTION MAKINGHTML
HTML format
$_$_SECTION MAKINGRTF
RTF format
$_$_SECTION MAKINGRTFHELP
WinHelp RTF source file
$_$_SECTION_ALL
...and this text appears in all formats.
$_$_END_PRE
$_$_HELP_CHAPTER 1,"Diagnosing conversion errors"
$_$_HELP_SUBJECT "Overview of handling errors"
Diagnosing conversion errors
****************************
$_$_HELP_TOPIC_ID ID_FAULTS
If you get any unexpected conversion problems:_
try generating some diagnostic files (see output policies...
file generation). This will generate a .lis file which will
show how AscToRTF has analysed each line in your source file
(there is a key at the foot of the .lis file).
Try executing a "simple" conversion.
Review the analysis policies, checking for anything that
doesn't look right.
Read through the [[goto Documentation available]] as this is
expected to give more detail
If you've registered:-
Contact the author for advice.
$_$_HELP_CHAPTER 1,"Change History"
Change History
**************
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 3,,2
$_$_SECTION MAKINGRTF
Here are the versions of AscToRTF that have been released to
date.
- [[goto Version 2.0 (February 2004)]]
- [[goto Version 1.5 (October 2002)]]
- [[goto Version 1.00 (March 2000)]]
$_$_SECTION ALL
$_$_HELP_CHAPTER 2,"Version 2.0 (February 2004)"
Version 2.0 (February 2004)
===========================
A major update since version 1, version 2 is essentially version 1.5,
but fully documented. The changes listed here were mostly available
in version 1.5. Some were obvious, others were not.
$_$_HELP_CHAPTER 3,"New functions"
New features
------------
Support for generating RTF as WinHelp source files
..................................................
AscToRTF can now create RTF files suitable for conversion into WinHelp
help files. Although this type of help file has been superceded by
HTML help, many people still prefer this type of Help file.
The Help files are created from specially formatted RTF files using
the free Help Compiler Workshop (HCW) utility, available from Microsoft.
To support this the following new policies have been added
- [[goto Generate WinHelp project file]]
- [[goto WinHelp Resource File]]
- [[goto Help file citation]]
- [[goto Help file copyright notice]]
- [[goto Help title background colour]]
- [[goto Help body background colour]]
See also the section [[goto Creating WinHelp files]]
New ability to define table layouts and formattign rules
........................................................
To aid in processing tables, the program now allows you to identify various
table structures by specifying various match conditions. Each time the
software encounters a candidate table, it tests this against the match
conditions to see if the "table" is of a known type.
For each table you can specify its structure, and various formatting rules
to be used in its conversion. These structure and formatting definitions can
be shared between multiple table types for your convenience.
All the table type, structures and formatting rules should be placed in
an external text file, known as a *Table Definition File* (or TDF for short).
A new policy allows you to identify which Table Definition File is to be used,
and you can select this from the new _Config File Location_ menu.
For full details see [[goto Using Table Definition Files (TDF)]].
NOTE: This feature was originally added to [AscToHTM], and at present most
of the formatting rules apply more to HTML generation, and so aren't available
in the RTF generation of AscToRTF.
Ability to "tag" your own lables for greater accuracy
.....................................................
The program now supports [[goto Tagged Table commands]]. These commands allow
you to completely markup a table, specifying the column details, the row
details and the contents of each table cell.
This approach can be used by those who want complete control over how
their tables are constructed, or who are generating text files from a source
which knows the table layout and can explicitly state it.
By using the tagged approach, you avoid the prospect of the program making
mistakes when analaysing the layout of the table.
As an example of using tagged table commands, the following sequence in the
source file
$_$_BEGIN_PRE
$_$_BEGIN_USER_TABLE C,1 in
$_$_COLUMN_DETAILS 1,,,L, 2 in
$_$_COLUMN_DETAILS 2,,,C, 1 ins
$_$_TABLE_BORDER 1
$_$_NEW_ROW HEAD
$_$_NEW_CELL
Substance (units)
$_$_NEW_CELL
Year
Sampled
$_$_NEW_ROW DATA
$_$_NEW_CELL
Alpha emitters (pCi/L)
$_$_NEW_CELL
1999
$_$_NEW_ROW DATA
$_$_NEW_CELL
Asbestos (MFL)
$_$_NEW_CELL
1993
$_$_END_TABLE
$_$_END_PRE
becomes
$_$_BEGIN_USER_TABLE C,1 in
$_$_COLUMN_DETAILS 1,,,L, 2 in
$_$_COLUMN_DETAILS 2,,,C, 1 ins
$_$_TABLE_BORDER 1
$_$_NEW_ROW HEAD
$_$_NEW_CELL
Substance (units)
$_$_NEW_CELL
Year
Sampled
$_$_NEW_ROW DATA
$_$_NEW_CELL
Alpha emitters (pCi/L)
$_$_NEW_CELL
1999
$_$_NEW_ROW DATA
$_$_NEW_CELL
Asbestos (MFL)
$_$_NEW_CELL
1993
$_$_END_TABLE
Input text manipulation and labelling using "Text commands"
...........................................................
The program now allows you to apply "text commands" to the input text, before
it is converted. There are several commands possible, which allow you
to identify lines in the input text that should be ignored, and text in
the input file that should be removed or replaced.
You can also use commands to tell the software how to interpret certain
types of line. For example to say which lines are headings, and which should
be regarded as bullet points etc. The Text Commands to be used should be
placed in an external *Text Command File*. A new policy allows you
to identify which Text Command File is to be used, and you can select this
from the new _Config File Location_ menu.
For full details see [[goto Using Text Command Files]]
Control over document styling by using a "Style Definition File"
................................................................
Several users of AscToRTF commented that they wanted to feed the output of
various typesetting programs into AscToRTF as text input. These users stated
that often they had detailed knowledge of how the text should be interpreted or
the RTF should be formatted, but were either having to discard that information
in the text passed to AscToRTF or were unable to provide AscToRTF with enough
hints to ensure the conversion was always accurate.
To help such users, changes have been made in version 2.0 to allow better
integration between the original document and the RTF created by AscToRTF.
From version 2.0 onwards AscToRTF has the ability to use an external
[[goto Using Style Definition Files (SDF),Style definition file]] to define named font styles. These styles can
then be invoked by adding the new [[goto Pre-processor command: FO]] tags to your document.
These tags invoke a font change that applies to the following text. The new
policy [[goto Scope for font tags]] determines the range within the document over which
an FO tag will apply.
For full details see [[goto Using Style Definition Files (SDF)]]
Support for non-ASCII character types and character encodings
.............................................................
_Non-latin and Unicode character sets_
Some support has been added for non-latin character sets. The character
set names are based on those used in HTML charsets, although RTF cannot
support the same range that HTML does.
Support has been added for auto-detecting the character set used, but
this is far from foolproof. If you are using non-latin character sets
you may need to set the character set manually.
It is not possible at present to support multiple character sets in
one document (unless you are using Unicode)
To support this feature the following policies have been added
- the [[goto character encoding]] policy to allow the character
encoding of a document to be set. The software has limited
ability to detect Japanese ("x-sjis") and Cyrillic ("koi-8")
text, but in some cases this will need to be set. Not all options
available are supported in RTF at present.
- The auto-detect of character sets can be switched off by using the
[[goto Look for character encoding]] policy. You might want to
do this if the software wrongly suspects your document is a
non-latin character set.
_other special characters_
- Added support for parsing files with some Mime-encoded quotable
strings in them. The new policy [[goto Input file contains MIME encoding]]
can be found under _Analysis->File structure_. At present there is
some (very limited) auto-detect for this feature.
- Added support for documents with change bars. By default change bars
are stripped out, and the changed text coloured red this behaviour
may be changed in later versions. Added the new policy
[[goto Input file has change bars]] which can be found under _Analysis->File Structure_.
- Added support for converting DOS characters. The new policy
[[goto Input file contains DOS characters]] can be found under
_Analysis->File Structure_.
There is a limited auto-detect of DOS characters when diagrams are
present.
- Added [[goto Input file contains PCL codes]] policy. Again
there is a limited ability to detect these codes. A few of the PCL
codes are interpreted. Most are just discarded.
- Improved handling of VT escape characters. These are either removed
from the output or converted to "line" characters
$_$_BEGIN_IGNORE
// Definition Blocks
// .................
// Definition blocks allow you to define blocks of text that you may
// then insert at any point in the text (e.g. to give an "end of page"
// effect). You can also "define variables" whose value is then inserted
// wherever a VARIABLE tag is used.
//
// This feature, though supported by the core analysis engine, is
// expected to be used more by the users of the [AscToHTM] converter.
//
// The pre-processor commands involved are:
//
// [[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,"VARIABLE"]] [[BR]]
//
// [[HYPERLINK, TAGGING,"SAVE/RESTORE_CONTEXT"]] [[BR]]
$_$_END_IGNORE
Support for comma-delimited and tab-delimietd tables
....................................................
Pre-processor commands have been added to allow you to mark up a section of
comma-delimited or tab-delimited data you want turning into a table.
The new pre-processor directives are the [[goto Pre-processor command: COMMA_DELIMITED_TABLE,COMMA_DELIMITED)TABLE]] command
and the [[goto Pre-processor command: DELIMITED_TABLE,DELIMITED_TABLE]] command
- New [[goto command line qualifiers: /COMMA,/COMMA]] and [[goto command line qualifiers: /TABBED,/TABBED]]command line
qualifiers that allow comma delimited and tab delimited files be
converted into tables.
- New [[goto command line qualifiers: /TABLE,/TABLE]] command line qualifier that allows the input
file to be treated as a single plain text table
In addition to this, the software now has the ability to automatically
detect tab-delimited data tables.
$_$_HELP_CHAPTER 3,"New policies"
New policies
------------
New Font policies
.................
Added policies to allow different fonts to be applied to different
types of text as follows
Normal text [[goto Default font]]
Headings [[goto Heading Font]]
Text in tables [[goto Table font]]
Table of contents [[goto Table of contents Font]]
Fixed-pitch text [[goto Fixed font]]
New Heading policies
....................
There are two new heading types that can be supported :-
- Added support for embedded headings with the [[goto Expect embedded headings]]
policy (see [[goto Embedded heading detection]]). These are "headings" that
are embedded as the first sentence in a paragraph.
- Added support for headings that start with particular words or
phrases via the [[goto Heading key phrases]] policy
(see [[goto Key phrase headings]] for more on this).
Also added :-
- Added the policy [[goto Check indentation for consistency]] so that it could
be disabled in documents where headings were centred (and thus all at different indentations)
- Added support for headings that span up to 3 lines, previously this
was only 2.
New Hyperlink policies
......................
- Added the policy [[goto Create Gopher links]] to toggle the
conversion of gopher links into hyperlinks.
- Added the policy [[goto Create Telnet links]] to toggle the
conversion of telnet links into hyperlinks.
- Added [[goto Check domain name syntax]] policy to toggle the checking
of domain name syntax in detected URLs. You can now switch this off
to allow intranet links to be accepted.
- Changed hyperlink detection to only allow explicit FTP URLs and
email addresses that don't start with numbers. These behaviours can
be reversed using the new policies [[goto Only allow explicit FTP links]]
and [[goto Allow email beginning with numbers]], both of which are on
the _Output->Hyperlinks_ tab.
- Added support for new top level domains (.info, .biz etc)
- Added support for the "snews://" secure news server protocol
- URLs of the form http://username@domain_name/... are now supported
- Added support for "obfuscated" URLs such as
http://3640005069/
http://7934972365/
http://0330.0366.0021.0315/
http://%6c%6f%63%6b%65%72%67%6e%6f%6d%65%2e%63%6f%6d/
Although the display text is left unchanged, the hyperlink will
point to a non-obfuscated URL (either the domain name, or an
IP address). This is because the obfuscated URLs such as there
are often used by spammers, and the author has no intention of
allowing his software to aid spammers in their goals.
If someone cares to give me a valid reason for using such URLs
I may reconsider this behaviour.
New file, page, paragraph and line structure policies
.....................................................
_File structure_
- Added [[goto Lines to ignore at start of file]] and [[goto Lines to ignore at end of file]]
policies to allow lines at the start and end of the source file to
be discarded. This can be useful if you source text is coming from
a third party source that adds extra, unwanted, lines.
- Added auto-detect of double spaced files (files where every second
line is blank). This will set the [[goto Input file is double spaced]]
policy whenever double-spaced text is detected (unless the policy
has already been set).
_Page structure_
- Added [[goto Pre-processor command: PAGE, PAGE]] command. This marks a page boundary.
In the RTF this creates a page marker
- Added [[goto Mirror margins]] policy.
_Page markers_
- Added [[goto Input file has page markers]] and [[goto Page marker size (in lines)]]
policies. These allow you to identify that the file has page markers
containing form feeds and that the first so many lines after the
form feed should be discarded.
_Paragraph structure_
- Added [[GOTO Preserve new paragraph offset]] policy. In documents where
a first line offset is detected at the start of each paragraph you can elect
to have this preserved in the output.
- Added [[GOTO First line indentation (in blocks)]] policy. This allows you
to specify the size of a first line offset, regardless of whether or
not one already exists in the file.
_Line structure_
Added options to allow more control over how the original document's
file structure should be preserved
- Added [[goto Treat each line as a paragraph]] policy.
If this option is selected, every line in the source file is
treated as a paragraph. This may be suitable if the file has been
authored using an editor that wraps the lines (i.e. doesn't put in
hard breaks) and which doesn't add blank lines between paragraphs.
- Added [[goto Preserve line structure]] policy.
If this option is selected a line break is added to every line, thereby
preserving the line structure of the original.
New Table policies
..................
- Added [[GOTO Default TABLE layout]] policy (also the pre-processor [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] command)
This allows you to specify the number of columns in each table, and the
attributes of each column, specifically the character position that
marks the end of each column. Rather than use this policy, it is
probably better to use the related pre-processor [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] command
in the source text on a per-table basis.
- Added [[goto Ignore table header during analysis]] policy
(also pre-processor [[goto Pre-processor command: TABLE_IGNORE_HEADER,TABLE_IGNORE_HEADER]] command)
Specifies that table headers should be ignored when columns are being
auto-detected. Some tables have complex headers that confuse the
analysis. This policy can be used to help them be ignored.
- Added [[goto Table extending factor]] policy. This controls the
degree to which pre-formatted lines should be expanded into
adjacent text.
- Added [[goto Column merging factor]] policy which controls the degree
to which columns which don't appear to be very clear should be "merged" together
- Added [[goto Could be blank line separated]] policy
Indicates that tables could be using blank lines to separate rows
of data. This affects the analysis and detection of the tables extent.
- Added [[HYPERLINK POLICY,"Column boundaries have zero width"]] policy
for tables that have no separator character between columns. Can be
useful for some tables generated by software
- Added [[goto Look for diagrams]] policy. Can be used
to stop complex tables being wrongly interpreted as "diagrams"
- Added [[goto Default TABLE cell alignment]] and [[goto Default TABLE alignment]] policies
to allow you to set the default alignments of data within table cells
and of tables on the page.
- Added [[goto Ignore table header during analysis]] policy. For tables with complex
headers you can elect to ignore these lines in the calculation of
the column structure of the table. This can lead to more accurate results.
Other new policies
..................
- Added [[goto Allow automatic centring]] and [[goto Automatic centring tolerance]] policies.
These allow you to look for text that is centred and to specify a tolerance
used in this detection.
- Added [[goto Look for underlined text]] policy. This allows text detected
as unerlined (other than headings) to be underlined in the output.
$_$_HELP_CHAPTER 3,"New programs"
New programs
------------
API version now available
.........................
As with all JafSoft converters, AscToRTF is available under separate license
as an Application Programming Interface (API). This API allows software developers
to harness the powerful abilities of AscToRTF from within their own software
products.
The API is written in C++, and is supplied as either a library or a DLL under
Windows. As such it can easily be invoked from C, C++ and Visual Basic software
and has also been successfully invoked from inside Java and C# programs.
New utility A2HDETAG
....................
For users who register, there is a new, separate command line utility called
A2HDETAG available so they can "de-tag" their source files of all AscToRTF
pre-processor tags, leaving a plain text fit for publishing, e.g. on Usenet.
In conjunction with this new BEGIN/END_ASCII ... END_ASCII pre-processor tags
have been added. These identify text that will be copied to the output of
A2HDETAG. It is ignored in all other conversions, and is intended to allow
alternative text to be placed in text and HTML versions of a document.
$_$_HELP_CHAPTER 3,"Other changes"
Other changes
-------------
New Preprocessor tags
.....................
Added several new pre-processor in-line tags :-
$_$_BEGIN_DELIMITED_TABLE
[[goto Pre-processor command: FILENAME,FILENAME]] outputs name of file being converted
[[goto Pre-processor command: FRACTION,FRACTION]] outputs a fraction
[[goto Pre-processor command: VERSION,VERSION]] outputs AscToRTF program name and version number
[[goto Pre-processor command: IGNORE,IGNORE]] multi-line text to be ignored
[[goto Pre-processor command: IGNORE_THIS,IGNORE_THIS]] in-line text to be ignored
$_$_END_DELIMITED_TABLE
Other new options
.................
- Added the "Suppress URL messages" option to the [[goto Diagnostic settings]].
When enabled all URLs, email addresses etc will be listed in the
log file. Since this file can be saved to disk, this is one way
of identifying all the candidate hyperlinks from your text file.
- The new [[goto Pre-processor command: ALLOW and DISALLOW,ALLOW and DISALLOW]] tags allow you
to enable/disable the search for headings and lists to sections of the
document. This helps with eliminating faulty analysis that confuses
numbered lists with headings, or lines of text ALL IN CAPITALS as
headings.
New document, the "Table Manual"
................................
To help people better understand how AscToRTF detects and analyses tables,
and to know what they can do to aid, improve and correct this process, a new
manual, known as the "Table Manual" has been produced. You should look for
this on the web site, or check if it has been included with your software
installation.
Changes to the Windows version
..............................
- The main screen now allows access to Policy file selection. Previously
this was only available on the menu structure. The Menu structure
has been left unchanged, meaning you now have two ways of choosing
your policy files.
- The main screen now allows you to search subfolders when using
wildcards.
- The main screen also allows you to specify the File conversion
type. You can choose to treat the input file as a number of
different table types (e.g. tab-delimited data).
- You no longer get prompted to "save policy" just because you
pressed OK on one of the policy sheets. Now this only happens
when something has been changed.
- The main menu now has a "check for updates" option. If you select
this you'll be taken to the JafSoft website where you'll be told
if any newer versions of the software have been released.
- Program now remembers positions of windows from one invocation to
the next.
- The user interface is now available in Italian, French and Swedish.
Changes to the command line version
....................................
- Command line now allows multiple filespecs, separated by spaces.
Policy file must now be a .pol file, rather than the second
argument.
Changes to document analysis
............................
- More changes on bullet characters, in particular to disallow 'O' (upper
case) from becoming a bullet character through analysis. This really
doesn't work in Portuguese documents :-) 'o' (lower case) may still
be detected. If upper case 'O' is wanted this can still be manually
switched on.
- Horizontal lines are now implemented as line rules whose length
attempts to approximate the original (e.g. 50% or whatever). Previously
lines would become full width.
- Bookmark names from filename are now lower case (to reduce possible
mismatches)
- Shareware version now expires after 30 days + 5 uses. This will
allow people to use the software on 5 different days after the first
30 days, giving people more time to evaluate the software at their
leisure.
- Now strip out leading and trailing "---" from heading text to make
them more presentable in RTF
- Changed emphasis handling to allow hyphenated parts to be emphasised
independently, e.g. pre-_formatted_ or _pre_-formatted.
- Fine-tuned the detection of whether or not a file has an in-situ
contents list
- The [[HYPERLINK TAGGING,"LINKPOINT"]] pre-processor tag can now be used as a directive as
well as an in-line tag. (see the [Tag Manual] for details).
- Increased maximum width allowed for input lines in tables to 200
(after encountering a sample at 165). Lines longer than this are
still disregarded as candidate table lines.
- Improved analysis for tables using bar ('|') column separators
- Improved detection of ASCII art diagrams.
- Improved handling of heavily indented blocks of text. Previously
these were (poorly) rendered as tables. Now the tables more
accurately preserve the large indentation (see [[goto Text block detection]]).
- The software will now automatically detect where a table is in fact
tab-delimited data. Where detected it will then and use that tab
structure to calculate columns.
Changes to documentation
........................
- This document has been completely re-written. It is converted from
a single text file into the HTML pages, an RTF file and the Windows
Help file using the [AscToHTM] and [AscToRTF] programs. You can view
the [{SOURCE_FILE]] for this documen as file "asctortf.txt".
- The [Tag Manual] describes the tagging systems available to JafSoft
conversion utilities. Note that not all of the tags described there
are relevant (or supported) in RTF generation. However many are
common between the converters, should you wish to convert the same
text file into other formats
- A "Table manual" is under production to explain how to get the most
from tables in your conversions. This is expected to appear some time
after AscToRTF 2.0 is released.
$_$_HELP_CHAPTER 2,"Version 1.5 (October 2002)"
$_$_HELP_SUBJECT "Overview of version 1.5"
Version 1.5 (October 2002)
==========================
Released as an "interim" release before version 2, version 1.5
contains a large number of changes, not all of which were fully
documented (that will be a large part of the difference between the
two versions).
The software was released at this time to give existing an new users
a far better version to work with and evaluate.
$_$_HELP_CHAPTER 2,"Version 1.00 (March 2000)"
$_$_HELP_SUBJECT "Overview of version 1.0"
Version 1.00 (March 2000)
=========================
The initial version is released after months and months (some might
say years) of promising it.
$_$_HELP_CHAPTER 1,"Ordering"
$_$_HELP_SUBJECT "How to order your copy"
Ordering your copy
******************
$_$_HELP_TOPIC_ID ID_ORDERING
$_$_HELP_TOPIC_ID HIDD_ABOUTBOX
Details on how to register AscToRTF can be found on the web page
http://www.jafsoft.com/asctortf/register_asctortf.html
This URL is also shown on the "About" window.
Discounts are available to anyone wishing to purchase multiple
copies. Site licenses are also available. Users who register
will also get access to the [[goto console version]] which may be better
suited to batch processing or performing automated conversions
Software developers wishing to incorporate AscToRTF's functions
into their own systems may be interested in the [[goto API version]].
For more information, visit the web page, or email *infojafsoft.com*
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION ALL
What happens if I don't register the shareware version of AscToRTF?
===================================================================
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 expires 30 days after
installation. Each time the program runs it will tell you how may
days left you have.
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 UPPER case. This will still allow you to evaluate the
software, but the resulting RTF 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 1000 lines a warning is placed in the
output, and all subsequent lines are converted to upper case. This
allows you to gain an impression of what the RTF will look like for
evaluation purposes.
- In the shareware version, wildcard conversions are limited
to only 5 files
- In the shareware the output is "watermarked"
I don't like limiting the software, but people need reminding, so
there you go.
Upgrade Policy
==============
$_$_HELP_TOPIC_ID ID_UPGRADES
It is our intention to continue development of this product, and
for as long as possible make upgrades available freely via the
Internet to registered users at no cost.
We can't actually promise this, but this is our intention.
In any case we will reward early commitment by ensuring the
cumulative cost of upgrades is never more that making a fresh
first-time purchase.
Other products by the same author
=================================
Other products by the same author include
$_$_BEGIN_TABLE
[AscToHTM] text-to-HTML converter, shareware $40
[AscToTab] text-to-Table converter for HTML and RTF, available as postcardware
[Detagger] HTML-to-text converter, shareware $20
$_$_END_TABLE
There's a lot of common technology between the three products (in
terms of the conversion engine and the user interface), so if you
like one, you should try the others.
For more details visit the web site at
http://www.jafsoft.com/products/
or email the author at *infojafsoft.com*
Contacts on the Web
===================
_The home page_
The [AscToRTF] home page is hosted on the [JafSoft] web site.
_Feedback_
E-mail any feedback to *infojafsoft.com* (replace the "" by "@").
Most people are pleasantly surprised to get a reply. Some are amazed
at the short response time.
Sadly, we cannot guarantee either :-)
Support
=======
A limited amount of support is available to registered users by emailing
*supportjafsoft.com* (replace the "" by "@"). 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.
$_$_HELP_CHAPTER 1,"Other versions of AscToRTF"
Other versions
**************
As well as the more conventional Windows version, AscToRTF functionality
is now available in a number of additional forms to suit the special
needs of users.
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION ALL
API version
===========
For those wishing to call AscToRTF programmatically, an API has been
developed. This is sold under separate license. Contact
*infojafsoft.com* if you're interested (replace the "" by "@").
You can get more details and an evaluation copy from
http://www.jafsoft.com/developers/api_demos.html
The same API is used for all JafSoft converters. You can read more
in the API documentation at
http://www.jafsoft.com/doco/docindex.html
Console version
===============
Although AscToRTF is primarily offered as a Windows application, the
program is also available as a console application which is made
available at no extra cost to registered users. There are a number
of command line options described in this document. The Windows
version is also capable of accepting command line options.
A console version is more suited to certain modes of batch processing,
(for example it can use a steering data file, and won't get focus when
executed).
The conversion engine is identical in each case, it's just GUI-less.
Please note this console version is *not* a DOS version, that is it
will run in a "DOS" window under windows, but not on a system booted
under DOS.
Although available before to registered users, the console version
is now also available for evaluation, due to it's popularity amongst
those doing automated batch conversions to RTF.
You can get more details and an evaluation copy from
http://www.jafsoft.com/developers/console_demos.html
Linux version
=============
Linux versions of JafSoft converters have been successfully built
as both command line programs, and in API form. Unfortunately
JafSoft are unable to support Linux versions directly at the current
time, and have only supplied versions in the past under a source
code license.
$_$_HELP_CHAPTER 1,"Documentation available"
$_$_HELP_SUBJECT "Documentation available"
Documentation available
***********************
$_$_HELP_TOPIC_ID ID_HTMLDOCO
A set of HTML documentation is maintained for AscToRTF. This is
generated by AscToHTM and is expected to be more comprehensive,
up to date, and easier to read than this help file (especially
when wanting a broader view).
You should have got a set of this documentation when you got your
copy of AscToRTF, however you can get more recent versions by
visiting the web site
http://www.jafsoft.com/doco/docindex.html
where you will also find instructions on how to get a .zip copy
for your own use. This RTF documentation is, of course, entirely
generated by AscToRTF itself. The text files used for the
conversion are usually included in the .zip file.
$_$_HELP_CHAPTER 1,"Acknowledgements"
$_$_HELP_SUBJECT "Impossible without..."
Acknowledgements
****************
$_$_HELP_TOPIC_ID ID_ACKNOWLEDGEMENT
I'd like to thank all the people who have helped me produce AscToRTF
and its related products. Although AscToRTF is a one-man programming
effort, I really wouldn't have come this far without the support
and encouragement of friends and users.
I'd like to thank my beta testers Naz Alam, Roy Vernon and
Gonzalo San Martin. Special thanks go to Elliott Roper and all
at Yezerski Roper (my real job) for their tremendous support
during the software's development.
Finally, my biggest thanks are to my registered customers who
keep asking me for features that would never even have occurred
to me. If you think AscToRTF has too many options, I can assure
you that each and every one of them has been added for a reason
and is being used by some happy customer or other.