markup, although it will
still be added to, and accessible from any hyperlinked contents list
you generate for the document.
At present such headings are not auto-detected... you need to
switch on the [[goto Expect Embedded headings]] policy.
Key phrase headings
-------------------
_New in version 2.0_
The program can now look for lines that start with particular words
or phrases (such as "Chapter", "Part", Title") of your choice and
treat these lines as headings. Previously this only worked in a
limited way if the heading line was also *numbered* ("Chapter 1") etc.
To use this feature, set the policy [[goto Heading Key phrases]]
Numbered paragraph detection
----------------------------
Some types of documents use what look like section numbers to number
paragraphs (e.g. legal documents, or sets of rules).
AscToRTF can recognize this, and mark up such lines by placing
the number in bold, and not using the "Heading n" style on the whole
line.
Mail and USENET headers
-----------------------
Some documents, especially those that were originally email or USENET
posts, come with header lines, usually in the form of a number of
lines with a keyword followed by a colon and then some value.
AscToRTF can recognize these (to a limited extent). Where these are
detected the program will parse the header lines to extract the Subject,
Author and Date of the article concerned. A heading containing this
information will then be generated to replace all the unsightly header
lines.
$_$_HELP_CHAPTER 2,"Pre-formatted text, diagrams and tables"
Pre-formatted text
==================
The software can detect various forms of pre-formatted text. This
is text laid out in such a way that the spacing used is critical.
Spacing is not normally preserved in conversion to RTF, so the
correct detection and handling of these special types of text is
quite important.
Types of text recognised include the following
- [[goto Line detection,Lines]]
- [[goto Form feed page markers]]
- [[goto User defined pre-formatted text]]
- [[goto Automatically detected pre-formatted text]]
- [[goto Table detection,Tables]]
- [[goto Code sample detection,Code samples]]
- [[goto ASCII art and diagram detection,Diagrams and ASCII art]]
- [[goto Text block detection,Text blocks]]
- [[goto Other formatted text]]
Line detection
--------------
Lines are interpreted in context. If they appear to be underlining
text, or part of some pre-formatted structure such as a table, then
they are treated as such. Otherwise they become horizontal rules.
An attempt is made to interpret half-lines etc as such, although the
effect is only approximate.
Form feed page markers
----------------------
Form feeds or page breaks become page breaks in the RTF
User defined pre-formatted text
-------------------------------
AscToRTF allows users to define their own regions of pre-formatted text,
using the BEGIN_PRE and END_PRE pre-processor tags (see [[GOTO Using the pre-processor]]).
Such areas are marked up in the "Preformatted" style (see "[[GOTO the use of RTF stylesheets]]"), which uses
a non-proportional font to preserve the relative spacing.
For example :-
$_$_BEGIN_PRE
The use of BEGIN_PRE and END_PRE preprocessor
commands (see 7.1) in
the text documents
tells AscToHTM that
this portion of the
document
has been formatted
by the user and
should be left unchanged.
$_$_END_PRE
$_$_HELP_CHAPTER 3,"Automatically detected pre-formatted text"
$_$_HELP_SUBJECT "Introduction to detecting pre-formatted text"
Automatically detected pre-formatted text
-----------------------------------------
AscToRTF attempts to spot sections of preformatted text. This can vary
from a single line (e.g. a line with a page number on the right-hand
margin) to a complete table of data.
Where such text is detected AscToRTF analyses the section to determine
what type of pre-formatted text it is. Options include
- Tables
- Code samples
- ASCII Art and diagrams
- some other formatted text
A number of policies allow you to control
- whether or not the program looks for such text
- how sensitivity it is to "pre-formatted" text
- how inclined the program is to "extend" the region to adjacent lines
- whether or not table generation should be attempted
- various aspects of any table analysis that is carried out.
See [[GOTO "Pre-formatted text"]] policies for full details.
You can adjust the sensitivity of AscToRTF to pre-formatted text by
setting the minimum number of lines required for a pre-formatted region
using the [[goto Minimum size of automatic section]] policy.
RTF ignores all white space in the source document, thus any hand-crafted
layout information would normally get lost. When AscToRTF detects
such regions it marks them up in fixed width font which tells RTF
this region is pre-formatted.
When tables are detected, AscToRTF will attempt to generate the correct
RTF table.
When AscToRTF gets the detection wrong you can use the AscToRTF
[[goto Using the pre-processor,pre-processor]] to mark up regions of your document
you wish preserved.
Table detection
...............
Tables are marked out by their use of white space, and a regular pattern
of gaps or vertical bars being spotted on each lines. AscToRTF will
attempt to spot the table, its columns, its headings, its cell alignment
and entries that span multiple columns or rows.
Should AscToRTF wrongly detect the extent of a table, you can mark up
a section of text by using the [[goto Pre-processor command: TABLE,TABLE]] pre-processor
markup (see the [Tag Manual]). Alternatively you can try adding
blank lines before and after, as the analysis uses white space to
delimit tables.
You can alter the characteristics of all tables via the table policies
(see [[GOTO Formatting policies]]).
You can alter the characteristics of all or individual tables via the
table pre-processor commands (see [[goto Pre-processor command: TABLE,TABLE]]).
Or you can suppress the whole thing altogether via the
[[goto Attempt TABLE generation]] policy
Tables will be marked up using the "Table" style. See "[[GOTO the use of RTF stylesheets]]".
Code sample detection
.....................
AscToRTF attempts to recognize code fragments in technical documents.
The code is assumed to be "C++" or "Java"-like, and key indicators
are, for example, the presence of ";" characters on the end of lines.
Should AscToRTF wrongly detect the extent of a code fragment, you can
mark up a section of text by using the [[goto Pre-processor command: CODE,CODE]] pre-processor
markup.
Or you can suppress the whole thing altogether via the policy
[[goto Expect code samples]].
Code samples will be marked up using the "Code" style.
See "[[GOTO the use of RTF stylesheets]]".
ASCII art and diagram detection
...............................
AscToRTF attempts to recognize ASCII art and diagrams in documents.
Key indicators include large numbers of non-alphanumeric characters
and the use of white space.
However, some diagrams use the same mix of line and alphabetic
characters as tables, so the two sometimes get confused.
Should AscToRTF wrongly detect the extent or type of a diagram,
you can mark up a section of text by using the [[goto Pre-processor command: DIAGRAM,DIAGRAM]]
pre-processor markup.
Diagrams are marked up using the "Diagram" style.
See "[[GOTO the use of RTF stylesheets]]".
Text block detection
....................
_New in version 2.0_
If AscToRTF detects a block of text at a large indent, it will now
place that text in such a way as to preserve as faithfully as
possible the original indent.
Other formatted text
....................
If AscToRTF detects formatted text, but decides that it is neither
table, code or art (and it knows what it likes), then the text may be
put out "as normal", but with the original line structure preserved.
In such regions other markup (such as bullets) may not be processed
such as it would be elsewhere.
$_$_HELP_CHAPTER 2,"Adding features to the document"
Adding features to the document
===============================
As well as detection features present in the source text, the
software allows you to add in features that you would expect
in the output file that can't be inferred from the input
These include the following.
- [[goto Adding a Document Title,Document title]]
- [[goto Adding a contents list,A working contents list]]
Adding a Document Title
-----------------------
AscToRTF can calculate - or be told - the title of a document. This
will be placed in document properties section in the header of
each RTF file produced.
The Title is calculated as in the order shown below. If the first
algorithm returns a value, the subsequent ones are ignored.
1) If a [[goto Pre-processor command: TITLE,TITLE command]] is placed in the
source text, that value is used
2) If the [[goto Document Details,Document title]] policy is set then this value
is used.
3) Finally, if none of the above result in a title the text
"Converted from " is used.
Adding a Contents list
----------------------
AscToRTF can detect the presence of a contents list in the original
document, or it can insert a field code that will generate a contents
list from the headings that it observes. This is possible because
AscToRTF marks headings up in the Headings style.
See [[goto The use of RTF stylesheets]]
This contents field added can be recalculated in Word by pressing F9.
There are a number of policies that give you control over how and
where a contents list is generated (see [[goto contents policies]]).
_Contents lists placement_
By default the contents list will be placed at the top of the output
file. You can cause contents lists to be placed wherever you want
by using the CONTENTS_LIST preprocessor command (see [[goto pre-processor directives]]).
_Contents list detection_
AscToRTF can detect contents lists in a number of ways
- By detecting "table of contents" "end contents" or something similar
in the text.
- By spotting the numbering sequence has been repeated twice. AscToRTF
will assume the first set is the contents list.
- By spotting [[goto Using the pre-processor,pre-processor]] markup.
This is often a hit-and-miss procedure, and is liable to error.
Should the analysis fail, you can attempt to correct it via the
[[goto contents policies,Contents lists]] policies.
$_$_HELP_CHAPTER 2,"AscToRTF's use of stylesheets"
$_$_HELP_SUBJECT "Stylesheets used by AscToRTF"
The use of RTF stylesheets
==========================
AscToRTF supports the use of stylesheets. That is the marking up
of text in particular styles. AscToRTF uses this to identify how
the text was analysed, thus headings acquire a "Headings" style, and
bulleted lists are marked up in the Bullet Style.
Initially most of these styles are the same, but if you use a word
processor that supports RTF stylesheets (such as Word), you'll be
able to globally change attributes line font face and colour. For
example you could turn all code samples green by changing the attributes
of the code style.
Styles are implemented in a hierarchy, with style attributes being
inherited from their parents. Later versions of AscToRTF may allow
style attributes to be selected before conversion.
The style hierarchy is as follows
$_$_BEGIN_DIAGRAM
Normal (generic normal text style)
|
+-- 1 Body (main body text)
| |
| +--- 11 ShortLine (short lines)
| +--- 12 Bullet (bullets and numbered lists)
| +--- 13 Quoted ("quoted" text as found in emails)
| +--- 14 Hanging (hanging paragraphs)
| +--- 15 Definition (definitions)
|
+-- 2 Table (Table text)
+-- 3 Preform (preformatted text)
+-- 4 Diagram (diagrams)
+-- 5 Code (code samples)
|
+-- 6 Heading (generic heading style)
| |
| +--- 61 Heading1 (level 1 headings)
| +--- 62 Heading2 (level 2 headings)
| +--- 63 Heading3 (level 3 headings)
| +--- 64 Heading4 (level 4 headings)
| +--- 65 Heading5 (level 5 headings)
|
+-- 7 TOC (generic TOC style)
| |
| +--- 71 TOC1 (level 1 TOC entry)
| +--- 72 TOC2 (level 2 TOC entry)
| +--- 73 TOC3 (level 3 TOC entry)
| +--- 74 TOC4 (level 4 TOC entry)
| +--- 75 TOC5 (level 5 TOC entry)
o
$_$_END_DIAGRAM
The default implementations of these styles are as follows:-
_Body_ Uses the user-supplied font. Created
justified text by default.
_ShortLine_ Same as _Body_, but with a \par at the end
of each line to preserve the original line structure.
These paragraphs have zero spacing before
and after, to closely mimic the original text
file structure.
_Bullet_ Styling is the same as _Body_, but the bullet
itself is output using a hanging indent with a
tab after the bullet.
_Quoted_ Text is placed in italics, and left justified.
Each line is given a \par to preserve the original
line structure.
_Hanging_ The text is divided into two parts. The first
is placed on the left, and the "hanging" part is
placed on the right, after a tab. The position
of the tab stop is calculated according to
the size of the text to be placed on the left.
Often text that AscToHTM would put in a table comes
out as a hanging list.
_Definition_ Much like _Hanging_. The definition term is on left,
the rest is hung on the right after a tab. Options
exist to allow the definition term to be made bold.
_Table_ The text is styled as in _Body_, but is placed into
cells in a table. Table analysis is complex, and
deserves a document in its own right, but
in essence the text is placed in cells and
aligned according to original placement and data
type. The whole process can sometimes go wrong.
_Preformatted_ Preformatted text is output in a non-proportional font
(usually Courier) with no spacing between lines and
a \par on each line to preserve the line structure.
A font size of 8pt is used as this best represents
80 characters across a page without wrapping.
_Diagram_ Same as _Preformatted_.
_Code_ Same as _Preformatted_.
_Heading_ Heading itself is unused, but acts as a common parent
for the actual styles "Heading 1", "Heading 2" etc.
These are set to be the same as the Microsoft Word
equivalents.
_TOC_ The table of contents style TOC itself is unused,
but acts as a common parent for the actual styles
"TOC 1", "TOC 2" etc. These are set to be the same
as the Microsoft Word equivalents.
$_$_HELP_CHAPTER 1,"Using policy files"
Using policy files
******************
$_$_HELP_TOPIC_ID ID_POLICY_FILES
Document policies have two main uses; to correct any failure of
analysis that AscToRTF makes, and to tell the program how to
produce better RTF in ways that couldn't possibly be inferred
from the original text.
Examples of the former may include specifying a nominal page
width, and stating whether or not underlined section headings
are expected etc.
Examples of the latter include adding colour and titles to
the page, as well as requesting that a large document is split
into several pages.
$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION MAKINGRTF
[[goto analysis policies]]
- [[goto General analysis policies,General Analysis]]
- [[goto Headings Policies]]
- [[goto bullet policies,Bullets]]
- [[goto Pre-formatted text policies,Pre-formatted text]]
- [[goto Table analysis policies,Table analysis]]
[[goto output policies]]
- [[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]]
$_$_SECTION ALL
What are Policy files?
======================
$_$_HELP_TOPIC_ID ID_DEFINEPOLICYFILES
AscToRTF has a large number of options available to influence the
analysis of your text files, and the output to RTF. These options
are called "policies" as they govern how the source file should
be interpreted and converted.
Policies may be saved in text files, known as policy files. These
files have a ".pol" extension by default. The policy files are
usually updated by changing the policies and saving the changes
in a new file. Because they are text files you can also edit them
directly, in a text editor. The files have the format of one
policy per line of
Text in the form
PolicyText :
The use of policy files allow a given set of options to be saved
and reused for other conversions, or later conversions of the same file.
See [[goto Using policy files]] for more information.
$_$_HELP_CHAPTER 2,"Analysis policies"
$_$_HELP_SUBJECT "Introduction"
Analysis policies
=================
$_$_HELP_TOPIC_ID ID_CONV_POLICIES
Analysis policies are usually calculated by AscToRTF by making a
first pass through your document. The resulting policies are then
used during the second, conversion pass to categorise all input
lines so that they may be correctly converted to HTML.
You should only need to change these policies should the analysis fail.
- [[goto 'What to look for' policies]]
- [[goto General analysis policies,General Analysis]]
- [[goto bullet policies,Bullets]]
- [[goto File Structure policies,File generation]]
- [[goto Headings Policies]]
- [[goto Pre-formatted text policies,Pre-formatted text]]
- [[goto Table analysis policies,Table analysis]]
$_$_HELP_CHAPTER 3,"What to look for" policies
$_$_HELP_SUBJECT "List of 'look for' policies"
'What to look for' policies
---------------------------
$_$_HELP_TOPIC_ID HIDD_LOOKFOR
These policies act as "broad stroke" policies enabling or disabling
areas of functionality within the software by telling it what to look
for and to try to detect.
For example you can tell the program whether or not to bother looking
for patterns of indentation, bullets, or numbered lists. In many
cases if you enable a policy you can further fine tune the conversion
details on other policy sheets.
- [[popup Look for indentation]]
- [[popup Look for white space,Look for paragraphs]]
- [[popup Look for short lines]]
- [[popup Look for horizontal rules]]
- [[popup Look for bullets and numbered lists]]
- [[popup Look for definitions]]
- [[popup Look for quoted lines]]
- [[popup Look for emphasis]]
- [[popup Look for underlined text]]
- [[popup Look for mail and USENET headers]]
- [[popup Look for character encoding]]
- [[popup Look for preformatted text,Look for regions of preformatted text]]
- [[popup Look for diagrams]]
Look for indentation
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_INDENTS
AscToRTF can attempt to detect the indentation pattern of your
document and replicate it in the output file. If you chose to
disable this policy, all your text will be output with no
indentations at all.
If the program is wrongly indenting your files, you can try
adjusting the pattern of indentation on the
[[goto General analysis policies,General Analysis]] tabbed policy sheet.
Look for white space
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_PARAS
By default AscToRTF will attempt to look for paragraphs in your
source. Usually this is signaled by a blank line between paragraphs,
a leading indent on the first line of each paragraph, or (in
extreme cases) a short line at the end of a paragraph.
If you don't want AscToRTF to detect paragraphs, disable this policy.
If AscToRTF is wrongly detecting paragraphs, try adjusting the
paragraph analysis policies on the [[goto General analysis policies,General Analysis]]
tabbed policy sheet.
Look for short lines
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_SHORTLINES
By default AscToRTF will attempt to detect short lines and preserve
their structure by adding a line break. Disabling this will cause
short lines to be merged into the surrounding paragraph's text.
If AscToRTF is wrongly handling your short lines, you can adjust
the short line cutoff point or the page width (which is used in
short line detection) in the Sizes section of the
[[goto General analysis policies,General Analysis]] tabbed policy sheet.
Look for horizontal rules
.........................
$_$_HELP_TOPIC_ID ID_LOOKFOR_RULES
By default AscToRTF will treat a series of hyphens, minus signs,
equal signs on the same line as a horizontal rule. (On occasion it
might be regarded as underlining a heading on the previous line).
You can disable this is you wish, or you can specify how many
"line" characters it takes to make a horizontal rule.
Look for bullets and numbered lists
...................................
$_$_HELP_TOPIC_ID ID_LOOKFOR_BULLETS
By default AscToRTF will try to detect bullet points and numbered
lists. This can sometimes go wrong if you have lines that look to
the program like bullet points.
You can disable this behaviour should you wish. Alternatively you
can fine tune the detection of bullets on the [[goto bullet policies,"bullet analysis"]]
tabbed policy sheet.
Look for definitions
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_DEFINITIONS
By default AscToRTF will try to detect definitions and notes,
usually in the form of a single word and a hanging paragraph.
This can often go wrong, so you can use this policy to disable
this feature.
Look for quoted lines
.....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_QUOTES
By default AscToRTF will try to identify "quoted" lines.
Quoted lines are lines that have had a single character
(often ">" or "!") inserted at the start. This is common
practice when quoting email in a reply. AscToRTF places
such text in italics.
You can disable this behaviour should you wish.
Look for emphasis
.................
*New in version 2.0*
AscToRTF will try to look for text that has been marked up
with underscores and asterisks to signify bold an italic text.
For example
$_$_CHANGE_POLICY look for emphasis : no
*This is bold* and _this is italic_
$_$_CHANGE_POLICY look for emphasis : no
becomes
*This is bold* and _this is italic_
Look for underlined text
........................
*New in version 2.0*
AscToRTF will try to detect where a line of text has been "underlined"
by following it by a same length row of dashes, hyphens, equal signs
etc. This text will then be regarded as a candidate for being an
underlined heading or - if those are not allowed - underlined text.
If you have tables and reports, you may want to switch this policy
off since the line at the end of a table may appear to under- or
over-line the last line of text in the table.
Look for mail and USENET headers
................................
$_$_HELP_TOPIC_ID ID_LOOKFOR_MAILHEAD
AscToRTF will try to look for email and USENET headers. Where
these are recognised they can be simplified so that only
the To, Form and Subject lines are shown in the output.
You can disable this behaviour should you wish.
Look for character encoding
..............................
Specifies whether or not the software should attempt to detect alternative
character sets, such as those used for languages such as Greek, Turkish,
Chinese etc.
The software does this by doing a statistical analysis on the characters used
in the source file. This process isn't perfect, and when it fails you will
need to manually set the correct character set using the [[GOTO Character encoding]]
policy.
If you find the program is wrongly detecting the character encoding, disable
this policy and/or manually set it using the [[GOTO Character encoding]] policy
Note: Not all character sets are supported by RTF.
Look for preformatted text
..........................
$_$_HELP_TOPIC_ID ID_LOOKFOR_PREFORM
By default AscToRTF will try to identify regions of preformatted
text. Once identified AscToRTF will try to decide if it's a
diagram, table or some other form of preformatted text. If it thinks
it's a table it will attempt to place the text in an appropriate
table structure.
You can disable the search for preformatted text, or if you allow
preformatted text, disable table generation. (This may be
appropriate if you have a large number of ASCII diagrams in
your text).
The search for preformatted text can be refined via the
[[goto Pre-formatted text policies,Pre-formatted text]] and [[goto Table analysis policies,Table analysis]]
tabbed policy sheets.
The output of tables can be fine-tuned via the
output policy [[goto Formatting policies,Formatting]] tabbed policy sheet.
Look for diagrams
.................
Specifies whether or not regions of preformatted text that are detected
should be considered as candidate diagrams. Text that contains numbers
of characters such as "|", "-", ">" and "<" may be considered to be
an ASCII diagram.
If you find the program is wrongly treating tables as diagrams
then disable this policy.
$_$_HELP_CHAPTER 3,"General analysis policies"
General analysis policies
-------------------------
$_$_HELP_TOPIC_ID HIDD_ANALYSIS
These policies aid AscToRTF's analysis by describing in detail what
the contents of the document being converted are
*Sizes*
- [[popup Page Width]]
- [[popup TAB Size]]
- [[popup Short line length]]
- [[popup Min Chapter Size]]
*Paragraphs*
- [[popup Blank lines between paragraphs]]
- [[popup New paragraph offset]]
*Definitions*
- [[popup Search for definitions,Search for definitions in source text]]
- [[popup hanging indent position(s),Definition paragraph indent levels]]
- [[popup recognize hyphen characters]]
- [[popup recognize colon characters]]
- [[popup Other definition characters]]
*Layout*
- [[popup indent position(s), Indentation levels]]
Page Width
..........
$_$_HELP_TOPIC_ID ID_PAGEWIDTH
This indicates the width (in characters) of your nominal output
page. This width is calculated from the observed line lengths
in the original document.
This width is used in short line calculation, and determining
whether a given line contains a definition term or not
(definition character near the start of the line).
In documents that contain line feeds this should be automatically
detected.
In other documents you may need to set this manually.
TAB size
........
$_$_HELP_TOPIC_ID ID_TABSIZE
This indicates the size (in characters) of your tabs. AscToRTF
converts all tabs to spaces on conversion before analysis. By
default a tab size of 8 characters is assumed.
The tab size can influence the analysis of paragraph indentations
and other layout. Provided they are used consistently there
shouldn't be a problem. However where tabs and spaces are used
in combination, mistakes can arise.
This is particularly true in tables of data. AscToRTF does not
expect tab-separated table cells, instead converting the tabs
to spaces and analysing the results.
If your source document has been created with an editor with a
different tab size, you should change this value should you
start to experience strange layout conversion problems.
Short Line Length
.................
$_$_HELP_TOPIC_ID ID_SHORTLINE
This policy is used to determine what is a "short line". Short
lines are treated specially by AscToRTF by adding a paragraph
marker on the end. They can also be used to detect ends of
paragraphs in those documents that don't have blank lines between
paragraphs.
Normally AscToRTF will determine whether or not a line is short
by comparing it to the page width, given the current context.
The default value is 0 characters (indicating a comparison to
Page Width should be used). Set this to any value you like.
A value of 80 is likely to make every line in your original
document have a paragraph marker on the end.
Min Chapter Size
................
$_$_HELP_TOPIC_ID ID_MINCHAPTER
This policy tells AscToRTF what the smallest chapter size may be.
This is used when trying to determine if a numbered line is a
chapter heading. AscToRTF tries to avoid treating numbered lists
as a series of small chapters using this policy.
The default value is 8 lines. Change this only if you suspect
small chapters are being ignored, or large list items are being
treated as chapter headings.
Blank Lines between paragraphs
..............................
$_$_HELP_TOPIC_ID ID_BLANKLINES
AscToRTF can detect whether or not it should expect blank lines
between paragraphs. Documents without blank lines between
paragraphs will be harder to convert, and errors are more likely.
Unfortunately text documents exported from Word for Windows
often have this property.
Where there are no blank lines, AscToRTF relies of spotting the
last line of a paragraph (usually shorter), and (in some
documents) the presence of a [[popup New paragraph offset,"hanging indent"]] at the
start of each new paragraph.
This should be automatically detected.
New Paragraph Offset
....................
$_$_HELP_TOPIC_ID ID_NEWPARA
Some documents start the first line of a new paragraph with an
offset of a number of characters. This is especially true in text
files saved from Word for Windows documents.
AscToRTF can sometimes confuse such paragraphs as being two different
levels of indentation. Use this policy to eliminate such confusion.
This should be automatically detected
Search for definitions
......................
$_$_HELP_TOPIC_ID ID_ALLOWDEFINITIONS
This policy can be used to disable the search for definitions.
Sometimes this leads to unexpected results with text that is
not part of a definition being treated as such. In such cases
you can adjust the definition policies, but if this still
fails, use this to disable the search completely.
See also [[popup one-line definitions]] and [[popup definition paragraphs]]
Hanging indent position(s)
..........................
$_$_HELP_TOPIC_ID ID_DEFNINDENTS
This policy identifies the indentations used for the follow-on
text in [[popup definition paragraphs]]. These indentation
levels need not be the same as the indentation levels used for
normal text, though of course often they are.
This should be detected automatically, but if your document has
only a few examples it's possible AscToRTF will ignore them.
In such cases you may need to set this policy manually.
_Note, this policy appears on-screen as "Definition paragraph indent levels"_
Recognize hyphen characters
...........................
$_$_HELP_TOPIC_ID ID_HYPHENDEFNS
This policy specifies whether or not hyphen (-) characters are
used in [[popup one-line definitions]].
If the hyphen character only occurs in definitions, then set the
nearby always flag, otherwise AscToRTF will have to guess whether
a particular character is part of a definition or not. This is
sometimes a source of conversion errors.
If this policy is selected, it will result in a suitable "Definition Char"
line being added to the policy file.
This should be detected automatically.
Recognize colon characters
..........................
$_$_HELP_TOPIC_ID ID_COLONDEFNS
This policy specifies whether or not colon (:) characters are
used in [[popup one-line definitions]].
If the colon character only occurs in definitions, then set the
nearby always flag, otherwise AscToRTF will have to guess
whether a particular character is part of a definition or not.
This is sometimes a source of conversion errors.
If this policy is selected, it will result in a suitable "Definition Char"
line being added to the policy file.
This should be detected automatically.
Other definition Characters
...........................
$_$_HELP_TOPIC_ID ID_DEFNCHARS
This policy specifies which other characters are used in
[[popup one-line definitions]].
This may be detected automatically, but more likely you'll need
to specify it yourself.
Each character selected as a potential delimiter will result in a
"Definition Char" line being added to the policy file.
Indent position(s)
..................
$_$_HELP_TOPIC_ID ID_INDENTS
AscToRTF recognises multiple levels of indentation. This policy
shows the character levels at which indentation has been detected.
AscToRTF converts all tab characters into multiple spaces in input.
These indentation positions are the positions that result after
that conversion. Depending on your tab settings these might not
be exactly the positions you would expect.
Normally these levels are correctly detected automatically, but
should you wish to set them manually you may need to experiment
slightly to see how AscToRTF has handled your tabs.
Bullet policies
---------------
$_$_HELP_TOPIC_ID HIDD_BULLETS
AscToRTF should be able to detect the use of bullets on a
reasonably sized document. These policies describe the type
of bullets expected.
- [[popup Look for bullets, Automatically detect bullets and numbered lists]]
*Expected Bullet types*
- [[popup expect numbered bullets, numbered bullets]]
- [[popup expect alphabetic bullets, alphabetic bullets]]
- [[popup expect roman numeral bullets, roman numeral bullets]]
*Bullet characters*
- [[popup "Recognise '-' as a bullet",recognize hyphen character as a bullet point]]
- [[popup "Recognise 'o' as a bullet",'recognize an "o" character as a bullet point']]
- [[popup Other bullet point characters]]
Look for bullets
................
$_$_HELP_TOPIC_ID ID_AUTODETECT_BULLETS
This policy states whether or not the program should attempt to
automatically detect bullets and numbered lists. This should
normally be left on unless your document has no such features,
but the program (wrongly) thinks it has.
This policy appears on the Bullets dialog as "Automatically detect
bullets and numbered lists", but is identical to the "Look for bullets"
policy on the [[goto 'What to look for' policies]] tabbed property sheet.
Expect Numbered bullets
.......................
$_$_HELP_TOPIC_ID ID_NUMBERBULLETS
This policy states whether or not numbered bullet points are
expected. The numbered bullets can be followed by any
punctuation, thus 1., 2) and (3) will all be recognised, but
RTF will not necessarily support this in the markup produced.
This should be automatically detected.
Expect alphabetic bullets
.........................
$_$_HELP_TOPIC_ID ID_ALPHABULLETS
This policy states whether or not alphabetic bullet points are
expected. The numbered bullets can be followed by any punctuation,
thus a., b) and (c) will all be recognised, but RTF will not
necessarily support this in the markup produced.
Both upper and lower case bullets are recognised (and supported
in the markup).
This should be automatically detected
Expect roman numeral bullets
............................
$_$_HELP_TOPIC_ID ID_ROMANBULLETS
This policy states whether or not roman numeral bullet points
are expected. The numbered bullets can be followed by any
punctuation, thus i., ii) and (iii) will all be recognised, but
RTF will not necessarily support this in the markup produced.
Both upper and lower case bullets are recognised (and supported
in the markup), although the range of roman numeral values
supported is limited.
This should be automatically detected.
Recognise 'o' as a bullet
.........................
$_$_HELP_TOPIC_ID ID_MINUSBULLETS
This policy states whether or not bullet points starting with
the hyphen character '-' are expected.
This policy appear on-screen as "Recognize hyphen character as a bullet point"
This should be automatically detected.
Recognise '-' as a bullet
.........................
$_$_HELP_TOPIC_ID ID_OBULLETS
This policy states whether or not bullet points starting with
the lower case 'o' are expected.
This policy appear on-screen as "Recognize 'o' character as a bullet point"
This should be automatically detected.
Other bullet point characters
.............................
$_$_HELP_TOPIC_ID ID_OTHERBULLETS
This policy lists any other characters that are to be recognised
as bullet characters.
Each bullet character entered will appear in the policy file as
it's own "Bullet Char" line.
This should be automatically detected, but may sometimes need to
be manually entered.
$_$_HELP_CHAPTER 3,"Contents policies"
Contents policies
-----------------
$_$_HELP_TOPIC_ID HIDD_CONTENTS
This dialog shows both analysis and output policies connected with contents list detection and generation.
*Analysis*
- [[popup Expect contents list]]
$_$_BEGIN_IGNORE
! *Output*
! - [[popup Generate a contents list]]
!
! See the discussion on contents list generation in the [[goto Documentation available]]
$_$_END_IGNORE
Expect contents list
....................
$_$_HELP_TOPIC_ID ID_EXPECTCONTENTS
This policy specifies whether or not the document already
contains a contents list. If it does, AscToRTF will attempt
to convert the existing list into a series of hyperlinks.
This should be detected automatically, but occasionally you
will need to set this policy manually.
See the discussion on contents list generation in the
[[goto Documentation available]]
$_$_BEGIN_IGNORE
! Generate a contents list
! ........................
! $_$_HELP_TOPIC_ID ID_MAKECONTENTS
! This policy specifies whether or not AscToRTF should generate a
! contents list. This lost will be generated from either an
! existing list in the source documents, or from the observed headings.
!
! A link to "contents list" will be added to the main RTF file.
!
! See the discussion on contents list generation in the
! [[goto Documentation available]]
!
$_$_END_IGNORE
$_$_HELP_CHAPTER 3,"File Structure policies"
File Structure policies
-----------------------
$_$_HELP_TOPIC_ID HIDD_FILESTRUCT
These policies aid AscToRTF's analysis by describing some of the
file structure that would affect the analysis.
- [[popup Keep it simple, Expect only a simple layout]]
*Expected File contents*
- [[popup Expect Code samples,'Expect "C"-code samples']]
- [[popup Input file contains DOS characters, Contains DOS characters]]
- [[popup Input file contains PCL codes, Contains PCL printer codes]]
- [[popup Input file contains Japanese characters, Contains non-European (e.g. Japanese) characters]]
- [[popup Input file contains MIME encoding, Contains mime-encoded quotable characters]]
- [[popup Input file has change bars, File has change bars]]
- [[popup Input file has page markers, File has Page markers]]
- [[popup Page marker size (in lines)]]
*Text Attributes*
- [[popup Text justification]]
- [[popup Input file is double spaced, File is double spaced]]
*Text to ignore*
- [[popup Lines to ignore at start of file, Number of lines to ignore at start of document]]
- [[popup Lines to ignore at end of file, Number of lines to ignore at end of document]]
Keep it simple
..............
$_$_HELP_TOPIC_ID ID_SIMPLE
AscToRTF puts a lot of effort into detecting overall structure
such as headings etc.
In documents that don't have any such structure, AscToRTF is
liable to convert any line with a number at the start into a
heading.
To prevent this, you can mark the document as simple, that is
with no global structure. In a simple document AscToRTF will
attempt far less analysis.
This policy appears on-screen as "Expect only a simple layout".
AscToRTF attempts to automatically identify simple documents,
but you may still need to set this policy manually.
Expect Code samples
...................
$_$_HELP_TOPIC_ID ID_EXPECTCODE
AscToRTF can markup C-like code fragments in ...
tags
to preserve the layout and readability of the quoted code.
This may be automatically detected, but occasionally needs to be
manually corrected.
Input file contains DOS characters
..................................
$_$_HELP_TOPIC_ID ID_DOSCHARS
AscToRTF can convert files that use the DOS (OEM) character set.
By default the file is assumed to be in the ANSI character set,
but some files may have originated under DOS.
This may be automatically detected, but usually needs to be
manually set.
Input file contains PCL codes
.............................
$_$_HELP_TOPIC_ID ID_PCL_CODES
_New in version 2.0_
Indicates that the input file contains PCL printer codes. When set, the
program will make whatever sensible use it can of these codes, otherwise they
will be removed.
Please note that the PCL printer codes offer a rich command language that
may be used to drive graphical printers. As such the emulation possibilities
in a *text* converter are limited, and it is quite likely that files that make
heavy use of such codes will fail dramatically to convert.
That said, those codes that are not recognised will be eliminated
from the output.
Input file contains Japanese characters
.......................................
$_$_HELP_TOPIC_ID ID_JAPANCHARS
*** not implemented yet ***
Files using non-ASCII character sets (Japanese, Korean etc) will
be incorrectly converted. This may be fixed (as far as possible)
in later versions.
Appears on-screen as "Contains non-European (e.g. Japanese) characters"
Input file contains MIME encoding
.................................
$_$_HELP_TOPIC_ID ID_MIMECHARS
AscToRTF can convert mime-encoded quotable characters. These will
usually appear in files that were originally part of an email
message. Such files use the "=" character to escape special
characters. So for example "=20" should be interpreted as a
space.
This appears on-screen as "Contains mime-encoded quotable characters"
This may be automatically detected in files where the "=" is
used to break up long lines, but more usually you will need
to manually set this.
Input file has change bars
..........................
$_$_HELP_TOPIC_ID ID_CHANGEBARS
AscToRTF can strip out change bars in documents that contain them.
Change bars are usually a vertical bar '|' placed in the
leftmost or rightmost column.
Currently this is not automatically detected, and so will need
to be manually switched on.
Input file has page markers
...........................
$_$_HELP_TOPIC_ID ID_PAGEMARKER
AscToRTF has a limited ability to remove page markers. These are
normally a few lines following a form feed (FF) character,
containing page numbers etc. This will commonly occur with files
generated from older software packages.
Page marker size (in lines)
...........................
$_$_HELP_TOPIC_ID ID_PAGE_MARKERSIZE
The number of lines after each form feed (FF) that should be
ignored. These lines will not be copied to the output.
Text Justification
..................
$_$_HELP_TOPIC_ID ID_TEXTJUSTIFICATION
AscToRTF recognises documents that are left justified (default),
right justified, centred or both left and right justified
(confusingly known as "justified").
The program cannot currently mark up the text in a matching style,
but this policy
is important in the analysis. For example "justified" documents
are padded with extra white space which could be interpreted as
pre-formatted text where the document not recognised as being
justified.
Normally this policy is correctly detected automatically.
Input file is double spaced
...........................
$_$_HELP_TOPIC_ID ID_DOUBLESPACED
AscToRTF will normally treat a blank line as a break between
paragraphs. Some files have extra CR/LF characters (usually
if they've come from a different computer, or from a printer
package). In such cases AscToRTF will see every second line
as blank, and this will affect the analysis, usually by turning
each line of data into a separate paragraph.
If you have such a file, use this policy to mark the file as
double spaced to get better results.
Lines to ignore at start of file
................................
$_$_HELP_TOPIC_ID ID_IGNORE_AT_START
_New in version 2.0_
This specifies how many lines from the input files should be
ignored at the start of the file. These lines will be discarded
from the output.
This can be useful when converting file copied from a news feed
or whatever that adds a small data header to the file.
Lines to ignore at end of file
..............................
$_$_HELP_TOPIC_ID ID_IGNORE_AT_END
_New in version 2.0_
This specifies how many lines from the input files should be
ignored at the end of the file. Up to 40 lines may be ignored
in this way. These lines will be discarded from the output.
This can be useful when converting file copied from a news feed
or whatever that adds a small data footer to the file.
$_$_HELP_CHAPTER 3,"Headings policies"
Headings policies
-----------------
$_$_HELP_TOPIC_ID HIDD_HEADINGS
These policies determine the headings structure that the document
is expected to have. Normally these are calculated correctly by
AscToRTF, but due to the complexity of heading detection, you may
sometimes need to correct the analysis.
At the top of the dialog you can specify what type of headings
you expect to see. Any combination is allowed, although
usually documents use just one type of heading.
- [[popup Expect Numbered headings]]
- [[popup Expect Underlined headings]]
- [[popup Expect Capitalised headings]]
- [[popup Expect Embedded headings]]
- [[popup Heading Key phrases]]
- [[popup Use first line as heading]]
- [[popup Center first heading]]
- [[popup Check indentation for consistency, Check indentations of headings are consistent]]
If numbered headings are expected, it may be possible to expect
headings at multiple levels, and to also expect a contents list.
Each level of heading will have it's own set of policies which
are shown on this dialog. The policies are shown in text form,
but are edited via [[goto the heading details dialog]]
Note: This area of functionality is continually under review.
See also the discussion in detecting [[goto headings and section titles]].
Expect numbered headings
........................
$_$_HELP_TOPIC_ID ID_NUMBERED_HEADINGS
This policy specifies whether or not numbered headings are
expected in the document.
Numbered headings may be found at multiple levels, and their
details may be edited via [[goto The heading details dialog]]
This should be calculated correctly by AscToRTF. But is prone
to error, getting confused by numbered bullets and the like.
In such cases you may need to set this policy manually.
Expect underlined headings
..........................
$_$_HELP_TOPIC_ID ID_UNDERLINED_HEADINGS
This policy specifies whether or not underlined headings are
expected. Note, where the headings themselves are numbered,
the underlining will be taken into account, and you should
set the [[popup expect numbered headings]] policy instead.
AscToRTF uses the character in the underlining to determine
the heading level, thus text underlined with equals signs
is given prominence over text with single underline characters
such as minus signs, tildes or underscores.
Expect capitalised headings
...........................
$_$_HELP_TOPIC_ID ID_CAP_HEADINGS
This policy specifies whether or not CAPITALISED headings are
expected. Note, where the headings themselves are numbered,
this policy need not be set, and instead you should set the
[[popup expect numbered headings]] policy instead.
Expect Embedded headings
........................
$_$_HELP_TOPIC_ID ID_EMBEDDED_HEADINGS
_New in version 2.0_
This policy specifies whether or not "embedded" headings are
expected, i.e.. the heading is "embedded" in the first paragraph.
Such headings are expected to be a complete sentence or phrase
in UPPER CASE at the start of a paragraph.
At present such headings are not auto-detected... you need to
switch this policy.
Heading Key phrases
...................
$_$_HELP_TOPIC_ID ID_KEYPHRASE_HEADINGS
_New in version 2.0_
If specified, then any line that begins with one of the key phrases
will be regarded as a heading. The syntax is
, ...
where each set of details is
= , []
and
= [|]
That is, each set of can optionally specify a .
If omitted this will default to 1,2,3 for the first, second, third set
of details etc. Note, this is a *logical* heading level, and will be
apparent in the contents list.
Each set of must supply a set of , and each set of phrases
would must have at least one phrase with extra phrases added if wanted,
separated by vertical bars.
So for example
Part, Chapter, Section
would treat lines beginning with the words "Part", "Chapter" and "Section"
as level 1,2, and 3 headings.
The key phrases are case-sensitive in order to reduce the likelihood of
false matches with lines that just happen to have these phrases at the start
of the line. So
PART|Part, Chapter, Section
Would allow either "PART" or "Part" to be matched.
"PART|Part,1" , "Chapter,2" , "Section,2"
Would make lines beginning with "Part" level-1 headings, while both
"Chapter" and "Section" would become level 2. This would be the same
as
"PART|Part,1" , "Chapter|Section,2"
Note, spaces may form part of a match phrase, but because of their
use in the tag syntax commands and vertical bars may not.
If false matches occur, (e.g. the word "Part" appears in the body of
the text) edit the source text so that the offending word is no longer
at the start of the line.
Use first line as heading
.........................
*New in version 2.0*
When this option is selected, the first line in the document will be
treated as a heading. This can be a useful option to select when the
first line of your document is a document title line, but doesn't
conform to the headings style used in the rest of the document.
See also [[goto use first line as title]]
Center first heading
....................
*New in version 2.0*
When this option is selected, the first heading in the document is centred.
This may be an appropriate choice when the first heading is in fact to
be treated as a document title.
See also [[goto use first line as heading]]
Check indentation for consistency
.................................
$_$_HELP_TOPIC_ID ID_HEADINDENTS
The program performs a number of consistency checks when detecting
headings. Amongst these is a check that all headings of the
same type occur at the same indentation. This check can help
distinguish between numbered headings and numbered lists.
However, if you have numbered headings that are different
indentations - e.g. because they are centred on the page - then
this check will cause them to be rejected as headings. In such
cases you can manually disable this check.
This policy appears on-screen as "Check indentations of
headings are consistent"
The heading details dialog
..........................
$_$_HELP_TOPIC_ID HIDD_HEADDTLS
This dialog is reached through one of the edit buttons on the
main [[goto Headings Policies]] dialog. This allows you to
edit details of a particular type or level of heading.
*Position of section number on the line*
- [[popup Indentation of heading lines]]
- [[popup Heading prefix words]]
*Section number formatting*
- [[popup Heading numbering scheme]]
- [[popup Heading separator characters]]
- [[popup Heading trailing letters]]
*Bracketing*
- [[popup Heading bracket characters]]
Indentation of heading lines
............................
$_$_HELP_TOPIC_ID ID_HEAD_INDENT
AscToRTF uses checks on indentation levels to reject lines with
numbers on that could be confused with headers.
This is the indentation level (in characters) that heading of
this types are expected to be found at.
Heading prefix words
....................
$_$_HELP_TOPIC_ID ID_HEAD_PREFIX
Some documents put words like "chapter", "subject" and
"section" in front of the section number. These are known
as prefix words.
Heading numbering scheme
........................
$_$_HELP_TOPIC_ID ID_HEAD_NUMBERTYPE
This is the numbering scheme expected for headings at
this level. At present AscToRTF can't cope with mixed types
like "II-2.b".
This may be addressed in later versions.
Heading separator characters
............................
$_$_HELP_TOPIC_ID ID_HEAD_SEPARATOR
This shows the separator expected between parts of the heading
number.
*** Not currently supported ***
Heading trailing letters
........................
$_$_HELP_TOPIC_ID ID_HEAD_TRAILALPHA
This shows whether we expect trailing letters after the section
number, as in "1.1b".
*** Not currently supported ***
Heading bracket characters
..........................
$_$_HELP_TOPIC_ID ID_HEAD_BRACKETS
This shows what bracket characters (if any) we expect before and
after the section number as in "[2.2]" or "3.2.1)".
*** Not currently supported ***
Pre-formatted text policies
...........................
$_$_HELP_TOPIC_ID HIDD_PREFORMAT
These policies specify how AscToRTF detects pre-formatted text.
Detecting pre-formatted regions
- [[popup Minimum size of automatic 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