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
-------------------
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).
AscToPDF 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.
AscToPDF 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 PDF, 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 PDF
User defined pre-formatted text
-------------------------------
AscToPDF 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]]).
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
-----------------------------------------
AscToPDF 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 AscToPDF 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 AscToPDF 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.
When AscToPDF detects such regions it marks them up in fixed width font
which tells PDF this region is pre-formatted.
When tables are detected, AscToPDF will attempt to generate the correct
PDF table.
When AscToPDF gets the detection wrong you can use the AscToPDF
[[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. AscToPDF will
attempt to spot the table, its columns, its headings, its cell alignment
and entries that span multiple columns or rows.
Should AscToPDF 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.
$_$_BEGIN_IGNORE
You can alter the characteristics of all tables via the table policies
(see [[GOTO Formatting policies]]).
$_$_END_IGNORE
You can alter the characteristics of all or individual tables via the
table pre-processor commands (see [[goto Pre-processor command: TABLE,TABLE]]).
$_$_BEGIN_IGNORE
Or you can suppress the whole thing altogether via the
[[goto Attempt table generation]] policy
$_$_END_IGNORE
Code sample detection
.....................
AscToPDF 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 AscToPDF 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]].
ASCII art and diagram detection
...............................
AscToPDF 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 AscToPDF 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.
Text block detection
....................
If AscToPDF 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 AscToPDF 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.
$_$_BEGIN_IGNORE
$_$_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
-----------------------
AscToPDF can calculate - or be told - the title of a document. This
will be placed in document properties section in the header of
each PDF 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
----------------------
AscToPDF 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 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_
AscToPDF 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. AscToPDF
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.
$_$_END_IGNORE
$_$_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 AscToPDF makes, and to tell the program how to
produce better PDF 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]]
$_$_BEGIN_IGNORE
- [[goto Table analysis policies,Table analysis]]
[[goto output policies]]
- [[goto File Structure policies,File generation]]
- [[goto Document details]]
$_$_BEGIN_IGNORE
- [[goto Formatting Policies,Formatting]]
- [[goto Hyperlinks policies,Hyperlinks]]
$_$_END_IGNORE
- [[goto Preprocessor policies,Preprocessor]]
$_$_BEGIN_IGNORE
- [[goto Link Dictionary Edit Dialog,Link Dictionary]]
$_$_END_IGNORE
$_$_END_IGNORE
$_$_SECTION ALL
What are Policy files?
======================
$_$_HELP_TOPIC_ID ID_DEFINEPOLICYFILES
AscToPDF has a large number of options available to influence the
analysis of your text files, and the output to PDF. 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 AscToPDF 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]]
$_$_BEGIN_IGNORE
- [[goto Table analysis policies,Table analysis]]
$_$_END_IGNORE
$_$_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 bullets and numbered lists]]
- [[popup Look for mail and USENET headers]]
- [[popup Look for preformatted text,Look for regions of preformatted text]]
$_$_BEGIN_IGNORE
- [[popup Look for emphasis]]
- [[popup Look for horizontal rules]]
- [[popup Look for quoted lines]]
- [[popup Look for definitions]]
- [[popup Look for underlined text]]
- [[popup Look for character encoding]]
- [[popup Look for diagrams]]
$_$_END_IGNORE
NOTE: Some options on this screen are grayed out. These options are
supported by other JafSoft conversion utilities and it is hoped
to extend this support to AscToPDF as development allows.
Look for indentation
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_INDENTS
AscToPDF 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 AscToPDF 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 AscToPDF to detect paragraphs, disable this policy.
If AscToPDF 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 AscToPDF 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 AscToPDF 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.
$_$_BEGIN_IGNORE
Look for horizontal rules
.........................
$_$_HELP_TOPIC_ID ID_LOOKFOR_RULES
By default AscToPDF 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.
$_$_END_IGNORE
Look for bullets and numbered lists
...................................
$_$_HELP_TOPIC_ID ID_LOOKFOR_BULLETS
By default AscToPDF 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.
$_$_BEGIN_IGNORE
Look for definitions
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_DEFINITIONS
By default AscToPDF 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 AscToPDF 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. AscToPDF places
such text in italics.
You can disable this behaviour should you wish.
Look for emphasis
.................
AscToPDF 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
........................
AscToPDF 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.
$_$_END_IGNORE
Look for mail and USENET headers
................................
$_$_HELP_TOPIC_ID ID_LOOKFOR_MAILHEAD
AscToPDF 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.
$_$_BEGIN_IGNORE
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
$_$_END_IGNORE
Look for preformatted text
..........................
$_$_HELP_TOPIC_ID ID_LOOKFOR_PREFORM
By default AscToPDF will try to identify regions of preformatted
text. Once identified AscToPDF 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]]
$_$_BEGIN_IGNORE
and [[goto Table analysis policies,Table analysis]]
$_$_END_IGNORE
tabbed policy sheets.
$_$_BEGIN_IGNORE
The output of tables can be fine-tuned via the
output policy [[goto Formatting policies,Formatting]] tabbed policy sheet.
$_$_END_IGNORE
$_$_BEGIN_IGNORE
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.
$_$_END_IGNORE
$_$_HELP_CHAPTER 3,"General analysis policies"
General analysis policies
-------------------------
$_$_HELP_TOPIC_ID HIDD_ANALYSIS
These policies aid AscToPDF'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]]
$_$_BEGIN_IGNORE
*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]]
$_$_END_IGNORE
*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. AscToPDF
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. AscToPDF 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 AscToPDF 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 AscToPDF 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 AscToPDF what the smallest chapter size may be.
This is used when trying to determine if a numbered line is a
chapter heading. AscToPDF 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
AscToPDF 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, AscToPDF 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.
AscToPDF can sometimes confuse such paragraphs as being two different
levels of indentation. Use this policy to eliminate such confusion.
This should be automatically detected
$_$_BEGIN_IGNORE
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]]
$_$_END_IGNORE
$_$_BEGIN_IGNORE
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 AscToPDF 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"_
$_$_END_IGNORE
$_$_BEGIN_IGNORE
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 AscToPDF 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 AscToPDF 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.
$_$_END_IGNORE
Indent position(s)
..................
$_$_HELP_TOPIC_ID ID_INDENTS
AscToPDF recognises multiple levels of indentation. This policy
shows the character levels at which indentation has been detected.
AscToPDF 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 AscToPDF has handled your tabs.
Bullet policies
---------------
$_$_HELP_TOPIC_ID HIDD_BULLETS
AscToPDF 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 "recognize '-' as a bullet",recognize hyphen character as a bullet point]]
- [[popup "recognize '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
PDF 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 PDF 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
PDF 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.
Recognize '-' 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.
Recognize 'o' 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]]
Expect contents list
....................
$_$_HELP_TOPIC_ID ID_EXPECTCONTENTS
This policy specifies whether or not the document already
contains a contents list. If it does, AscToPDF 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]]
$_$_HELP_CHAPTER 3,"File Structure policies"
File Structure policies
-----------------------
$_$_HELP_TOPIC_ID HIDD_FILESTRUCT
These policies aid AscToPDF'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
AscToPDF puts a lot of effort into detecting overall structure
such as headings etc.
In documents that don't have any such structure, AscToPDF 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 AscToPDF will
attempt far less analysis.
This policy appears on-screen as "Expect only a simple layout".
AscToPDF attempts to automatically identify simple documents,
but you may still need to set this policy manually.
Expect Code samples
...................
$_$_HELP_TOPIC_ID ID_EXPECTCODE
AscToPDF 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
AscToPDF 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
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
AscToPDF 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
AscToPDF 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
AscToPDF 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
AscToPDF 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
AscToPDF 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 AscToPDF 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
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
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
AscToPDF, 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 AscToPDF. 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.
AscToPDF 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
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
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
.........................
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.
$_$_BEGIN_IGNORE
See also [[goto use first line as title]]
$_$_END_IGNORE
Center first heading
....................
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
AscToPDF 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 AscToPDF 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 ***
$_$_HELP_CHAPTER 3,"Pre-formatted text policies"
Pre-formatted text policies
---------------------------
$_$_HELP_TOPIC_ID HIDD_PREFORMAT
These policies specify how AscToPDF 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.
AscToPDF 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 AscToPDF 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.
$_$_BEGIN_IGNORE
$_$_HELP_CHAPTER 3,"Table analysis policies"
Table analysis policies
-----------------------
$_$_HELP_TOPIC_ID HIDD_TABANAL
These policies specify how AscToPDF 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 PDF table
generation attempted for regions of apparently pre-formatted
text. AscToPDF will attempt to analyse such regions, preferring
to fit them into a PDF table. However, if this is not possible,
or if AscToPDF 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 AscToPDF 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
.............................
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.
Expect sparse tables
....................
$_$_HELP_TOPIC_ID ID_TABLE_SPARSE
This policy is used to tell AscToPDF that you expect your tables
to be quite sparse in places. This can affect AscToPDF'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"
$_$_END_IGNORE
$_$_BEGIN_IGNORE
$_$_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 PDF. Generally
these policies allow you to decide how the resulting PDF should
look in a manner that cannot be inferred from the original document.
- [[goto File Structure policies,File generation]]
- [[goto Document details]]
$_$_BEGIN_IGNORE
- [[goto Formatting policies,Formatting]]
- [[goto Hyperlinks policies,Hyperlinks]]
$_$_END_IGNORE
- [[goto Preprocessor policies,Preprocessor]]
$_$_BEGIN_IGNORE
- [[goto Link Dictionary Edit Dialog,Link Dictionary]]
$_$_END_IGNORE
$_$_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. AscToPDF will generate 3 files with the
following extensions:
$_$_BEGIN_TABLE
.lis1 A line-by-line summary of how AscToPDF analysed the source file
during the analysis pass
.lis A line-by-line summary of how AscToPDF 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 AscToPDF 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 PDF document. Depending on your PDF 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
.......................
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
..........................
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]]
$_$_BEGIN_IGNORE
$_$_HELP_CHAPTER 3,"Formatting"
Formatting Policies
-------------------
$_$_HELP_TOPIC_ID HIDD_RTF_FORMAT
These options offer settings that allow you to control some of
the formatting applied to the PDF 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
........................
When enabled the software will attempt [[goto centred text detection]].
This policy appears on-screen as "Enable automatic centring"
Automatic centring tolerance
............................
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
.............................
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)
..................................
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
................................
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
........................
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
.............................
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
............................
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.
Default TABLE alignment
.......................
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).
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. AscToPDF 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
...........................
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 PDF.
$_$_END_IGNORE
$_$_BEGIN_IGNORE
$_$_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.
AscToPDF 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
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
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
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 AscToPDF should attempt to identify Usenet
newsgroup names and turn them into active "news" hyperlinks.
AscToPDF 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,
AscToPDF 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,
AscToPDF 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 AscToPDF 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.
$_$_END_IGNORE
$_$_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
................
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)
...........................
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.
$_$_BEGIN_IGNORE
$_$_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.
$_$_END_IGNORE
$_$_END_IGNORE
$_$_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 PDF 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.
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
$_$_BEGIN_IGNORE
[[goto Tagged table commands]] Commands that allow you to specify a table structure cell-by-cell
[[goto Table modifier commands]] Commands that delimit and control table generation
$_$_END_IGNORE
[[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.
Note: At this time not many of the JafSoft pre-processor in-line
tags offred by our other conversion programs are supported by
AscToPDF.
$_$_BEGIN_IGNORE
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]]
$_$_END_IGNORE
$_$_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 PDF 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 PDF 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 PDF document 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: 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.
$_$_BEGIN_IGNORE
[[popup Pre-processor command: ASCII,ASCII]] Mark a section of text for utility A2HDETAG.
$_$_END_IGNORE
$_$_END_TABLE
Pre-processor command: ALLOW and DISALLOW
-----------------------------------------
$_$_HELP_TOPIC_ID ID_PRE_ALLOW_AND_DISALLOW
AscToPDF 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
$_$_BEGIN_IGNORE
Pre-processor command: ASCII
----------------------------
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 PDF by AscToPDF
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 PDF 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 PDF or HTML
$_$_END_ASCII
$_$_END_PRE
$_$_END_IGNORE
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
AscToPDF 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
AscToPDF 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
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
AscToPDF 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
AscToPDF 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
Note: At present AscToPDF doesn't have the ability to fully lay
out your table in the way that other JafSoft utilities
such as AscToHTM and AscToRTF do, For the time being
"tables" will simply be output using a fixed font. However
in later version it is hoped to fully implement table
creation.
*General comments on marking up tables*
AscToPDF 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
$_$_BEGIN_IGNORE
value set in the [[goto Attempt table generation]] policy, as that
$_$_END_IGNORE
value set in the poliy file, as those policy values only refer to
the auto-detection of tables. Placing markup in the source *forces*
the text to be treated as tables.
$_$_BEGIN_IGNORE
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]]
$_$_END_IGNORE
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. AscToPDF
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
$_$_BEGIN_IGNORE
$_$_HELP_CHAPTER 2,"Tagged Table commands"
Tagged Table commands
=====================
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 PDF 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 normally have been calculated automatically for the column as
a whole.
$_$_END_IGNORE
$_$_BEGIN_IGNORE
$_$_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
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
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.
$_$_END_IGNORE
$_$_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: 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: VERSION,VERSION]] Output the program version used in this conversion
$_$_BEGIN_IGNORE
[[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: POPUP,POPUP]] Add a hyperlink to a section title
[[popup Pre-processor command: SUPER and SUB,SUPER and SUB]] Add superscripts and subscripts
$_$_END_IGNORE
$_$_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]]*"
$_$_BEGIN_IGNORE
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
---------------------------
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 AscToPDF as a heading.
Pre-processor command: POPUP
----------------------------
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]].
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]]
$_$_END_IGNORE
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 AscToPDF is run,
or in the same directory as the original source file. AscToPDF
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
---------------------------
The syntax is
$_$_PAGE
This signals a page boundary. In PDF generation a page break will be generated
at this point.
Pre-processor command: VERSION
------------------------------
This in-line tag adds a description of the program name/version used to
convert the files (e.g. "AscToPDF 2.1")
Syntax:
[[OT]]VERSION[[CT]]
Outputs the version name of the conversion into the output file. For example
"[[VERSION]]".
$_$_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
As of version 2.0, AscToPDF 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 "heading" as_heading_1
can be used to ensure that lines that start with "heading" are treated
as headings of level 1.
$_$_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,"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 AscToPDF 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 AscToPDF that have been released to
date.
- [[goto Version 0.9 (April 2006)]]
$_$_SECTION ALL
$_$_HELP_CHAPTER 2,"Version 0.9 (April 2006)"
$_$_HELP_SUBJECT "Overview of version 0.9"
Version 0.9 (April 2006)
========================
The initial beta 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 AscToPDF can be found on the web page
http://www.jafsoft.com/asctopdf/register_asctopdf.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 AscToPDF'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 AscToPDF?
==========================================
Originally I wanted to produce a fully-featured, but time-limited
evaluation 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 trial 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 trial 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 PDF will be of little use to you.
- In the evaluation 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 PDF will look like for
evaluation purposes.
- In the evaluation version, wildcard conversions are limited
to only 5 files
- In the evaluation version 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
At present AscToPDF is in late beta. Anyone who registers AscToPDF at this
time will get a free upgrade to version 1.0.
Beyond that Free upgrades will be given for all minor releases,
but an upgrade fee will be liable for version 2.0.
During the late beta phase, the price of AscToPDF will be substantially
less than what we anticipate selling version 1.0 for.
Other products by the same author
=================================
Other products by the same author include
$_$_BEGIN_TABLE
[AscToHTM] text-to-HTML converter, $30
[AscToRTF] text-to-RTF converter, $59
[AscToTab] text-to-Table converter for HTML and RTF, available as postcardware
[Detagger] HTML-to-text converter, $29.95
$_$_END_TABLE
There's a lot of common technology between these 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 [AscToPDF] 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
*infojafsoft.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 AscToPDF"
Other versions
**************
As well as the more conventional Windows version, AscToPDF 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 AscToPDF 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 AscToPDF 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 PDF.
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 AscToPDF. 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 AscToPDF, 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 PDF documentation is, of course, entirely
generated by AscToPDF 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 AscToPDF
and its related products. Although AscToPDF is a one-man programming
effort, I really wouldn't have come this far without the support
and encouragement of friends and users.