AscToPDF Help Index
AscToPDF is a utility designed to convert plain text files into PDF pages.  The program can be used to convert legacy text files to PDF as one-off conversions, or to help you author sets of PDF pages in text. The program has been developed from AscToHTM a text-to-HTML conversion utility.  Much of the code and help files are developed in parallel, so there may occasionally be inappropriate references to AscToHTM. 
The program attempts to detect the existing structure in the files being converted by determining rules or policies that describe the file layout. These are known as the analysis policies. 

The policies used by the file can be saved to a policy file and subsequently reloaded.  This allows standard sets of policies to be defined. 
This document describes AscToPDF 0.9, released in April 2006. 
The PDF version of this document was converted from the textfile AscToPDF.txt by the product itself. 
Any HTML, RTF or Windows Help files are also converted from the same text file using the AscToHTM and AscToRTF JafSoft utilities. 

Installation
The trail version of AscToPDF is made available over the web from AscToPDF download zip file.  Once you register you can download the full version (no nags, no limits), and are entitled to free upgrades until the next major release.  Customers who purchase version 0.9 will get a free upgrade to version 1.0 when it is released. 
Installation will vary according to the type of install kit you've downloaded, but in each case you first download the .ZIP file appropriate to your system and unzip. 

Windows installation
The current version of the software makes updates to your Registry.  See the Install notes that come with the software for a description of the registry settings used. 
Installing the Windows GUI version
The standard installations use InnoSetup to offer install and uninstall options.  To use this version, unzip the file and then run the Setup program.  This will move the files to a directory, and create all icons etc. 
Once installed, InnoSetup will also offer an uninstall option. You can access this via Control Panel | Add/remove software. 
Installing the console version
The console version simply comes in a .zip file.  The documentation is not included as this is the same as the Windows version. 
Simply unzip the console version to the folder of your choice. 

How it works
AscToPDF analyses your document, looking at how the text is laid out, and trying to identify and quantify the rules used by the author to format the document.  These rules are then used to set "policies" that determine how each part of the document should be interpreted.  These policies are then used during the output pass to decide how the output document should be formatted. 
The user can choose to manually set "Policies", thereby overriding the software's analysis, and may additionally set some policies that only apply to the output pass (such as which fonts should be used).  These manual options may be saved in a policy file and reloaded the next time.  Different policy files may be created for different document sets, or for different types of output. 
For example analysis might determine that a large number of lines appear to be "underlined", and that these may be headings.  Having made this decision, lines that are underlined will become headings, while those that are numbered or capitalised may not.  If this is the wrong decision, the user can disable the use of underlined headings via a policy file, and even choose to recognize capitalised headings instead should they wish. 

Assumptions made by the program
AscToPDF makes one big assumption :- 
Each text file has been laid out in a consistent manner by its author in a way that makes it easy for a human reader to understand 
Given this, AscToPDF tries to read the text file and mark it up in PDF accordingly.  This is achieved by making three passes through the document, an analysis pass, a collating pass, and an output pass. 
Note:     Sadly this assumption is not always true :( 

The analysis pass
During the analysis pass AscToPDF gathers together all the statistics that it needs to analyse how the author has laid out the file. 
For example, the distribution of line indentations and line lengths is observed, together with the number and types of bullets, section headings and lots of other stuff. 
Once this has been done, the program uses this data to determine how the author has structured the document.  For example are the section headings underlined, capitalised or numbered?  If numbered, what style of numbering is used, and at what level of indentation is the heading placed? 
This information is then used to set the analysis polices (see the Policy manual) which may then be overridden by the user, or by loading a policy file with different values. 

The collating pass
Having performed the analysis, the program makes a second "collating" pass.  This is effectively a dry run for the output pass. 
During this pass the program determines how the file will be output, what headings there are and where certain key in-line tags occur. 
It also assembles any contents list. 
This information is then used during the output pass to reduce the likelyhood of errors, and to ensure all internal hyperlinks are valid and will point to the correct file location. 

The output pass
During the output pass AscToPDF generates the PDF file (there's nothing like stating the obvious :-) 
The PDF generated depends only on the original document, the calculated document policy, and any user policies supplied. 
Understanding the PDF generated describes the markup produced in more detail. 

Running the software
Overviews
·	Understanding the PDF generated 
·	Using policy files
·	analysis policies
·	Using the pre-processor 
·	Saving program preferences 
·	Diagnosing conversion errors
Other Information
·	Ordering your copy
·	Upgrade Policy
·	Documentation available
·	Acknowledgements
Running as a Windows application
Main Dialog
AscToPDF can be invoked as a normal Windows application.  On start-up you will be presented with the main window.  This consists of a menu bar across the top of the window, and some data entry fields in the main body of the window. 
Menu Bar 
File menu      File options
Conversion Options menu        Options that affect the conversion
Settings menu  Edit the program's settings
Language menu  Select the language you'd like the program's user
View menu      View the created PDF files or the messages for the
Help menu      Various help files and on-line resources	interface to be in
last conversion	
Data entry fields 
The data entry fields show 
·	the file(s) selected for conversion
·	whether or not you want to search sub-folders
·	the conversion type wanted
·	the output directory
·	the output filename
Normally you need simply select the input file(s) using the Browse button, and the rest of the fields will be set to default values. 
If you want to use wildcards, type the file specification in the data entry box directly. 
Once you have selected your files, press the Convert button.  The Status Window will briefly appear whilst the conversion proceeds. 

Policy files 
AscToPDF has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the PDF it generates.  Policy files are described more fully in Using policy files. 
Options on this screen include :- 
·	Load policies from an existing policy file
·	Reset all policies to their default values
More options are available under the Conversion Options menu. 

Search sub-folders
When this option is selected, the software will convert any files that match the supplied filename in either the directory specified or any of its sub-folders. 
Conversion type
The Conversion Type specified how the input file should be regarded during the conversion.  The options available include 
plain text	The input file is a plain text file, and the
	software should analyse it to determine how
	it is structures
text table	The input file is a plain text file which
	contains a single table.  The program will treat
	the whole file as a table, and use analysis to
	calculate the table layout
comma-delimited table	The input file is a comma-delimited data file
	(usually a .csv file).  Each line in the file
	will be treated as a row in the table, and commas
	are used to separate the data for each column.
tab-delimited table	As above, but the TAB character is used as a
	delimiter
other-delimited table	As above, but you need to specify the delimiter in
	the field that appears when this option is selected.
In the delimited table types the delimiter character shouldn't appear in the data value itself.  This usually means that tab-delimited files work better.  In a comma-delimited file, any value that contains a comma must be placed in double quotes.  Any double quotes in a quoted value should be doubled up inside the quote. 
So the value 
"Enter," she said 
would need to be written as 
"""Enter,"" she said" 
in the data file. 

File menu
The file menu offers the following options:- 
Convert	This will prompt you for a file to convert and will then convert the selected file(s).
Load policy file	Load policies from a policy file
Save policy file	Save the current set of policies to a policy file
Exit	Exit the program.

Conversion Options menu
This menu allows you access to the conversion options - also known as policies - that give you a large amount of control over the conversion process.  These policies can be saved to a policy file (with a .pol extension by default) for re-use in later conversions. Policies are explained more in Using policy files 
The menu options include:- 
Analysis policies
source document
Configuration File locations       Specify the locations of various configuration files	Edit those policies that affect the analysis of your	
Load policy file	Load policies from a policy file	
Reload policies from file
a different file.	Allows you to re-load the policy file, or to load	
Re-analysing the input file    Re-analyse the input file to re-calculate the analysis
policies
Resetting policies to default values   Reset policies to default values.	 	
Analysis policies menu
The Analysis Policies menu allows you to change those policies that affect the analysis of the source document. 
These are discussed fully in the Analysis Policies section of this document. 

Config File locations menu
The Config File Location menu allows you to specify the location of various additional configuration files.  The locations you select will be stored in your policy file, so in a sense these files act as extensions of the policy file, but by being stored in separate files the same configuration files can be shared by multiple policy files. 
The options on this menu allow you to select do locate following :- 

·	Text Command File
Selecting the Text Command File
This option allows you to select the Text Command File you wish to use. 

Re-analysing the input file
This option, available from the conversion options menu, allows you to reset the analysis options by analysing the current input file.  This is not normally necessary, as this will be done automatically during a conversion. 
Resetting policies to default values
This option will reset all policies to their default values.  If a policy file has been loaded, it will be unloaded. 
Load policy file
AscToPDF has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the PDF it generates. These policies can be saved in a policy file for later re-use in future conversions.  This dialog screen is primarily intended to allow you to load a previously saved policy file 
Policy files are described more fully in Using policy files. 
Options on this screen include :- 
·	Load policies from an existing policy file
·	Save policy file to save options to file for later re-use
·	Reset all policies to their default values
Save Policy File
This window is displayed whenever the user wishes to save their policies to a file, usually for use in later conversions. 
To save the file, simply select the policy file name, usually with a .pol extension. 
This window contains a radio button with two options: 
·	Save only those policies that have changed
If this option is selected, then only those policies that have been loaded from an existing file and/or been edited during the current session will be saved. 
This is the recommended option, as it will exclude all policies that have been set up correctly automatically. 
·	Save all policies
If this option is selected, that all policies are written to file. This is a good way of documenting the policies used, but is usually too restrictive to be loaded as input into conversions of other files. 
The saved file is a text file designed so that it may be manually edited and reloaded.  If you do so, take care not to change the key phrases at the start of each line. 
Note	If you find that conversions that used to work "stop working" it's possibly because you're using a complete policy file

Settings menu
The program settings menu allows you to customise the way AscToPDF executes each time it is invoked.  This is kept separate from the use of policy files, which are used to customise the actual conversion process. 
This menu has the following options :- 
Documentation Settings	Specify the location of your documentation on your hard drive
Diagnostic Settings	Set message filters and alter the error reporting level to
control the number and type of messages generated during
conversions
Drag and Drop Settings	Set the program's properties when invoked by dragging files
into the icon on the desktop
Results viewers settings	Specify the viewers to be used for viewing results
files, and their method of invocation
Use of policy file settings	Specify any default policy file to be used.

Documentation settings
These options allow you to specify the location of the program's documentation on your local system.  This is required for the option on the Help menu to work. 
By default the documentation is placed in the same directory as the program on installation, so you should only need to change this setting should you decide to move the documentation. 
Diagnostic settings
These options allow you to set the level of error reporting, or to suppress messages of various types from being displayed during conversion. 
The types of messages include :- 
INFO messages Informational messages.  These convey information	
 	telling you what was been done and why.	
 	 	
WARNING messages      Warning messages.  These tell you that something	
 	you have requested has not been done, or something	
 	has been done which may not be correct.  It's possible	
 	you may be able to take corrective action.	
 	 	
*TAG	ERROR messages*    Tagging errors.  Only occur when you use the	
 	preprocessor in-line tags and directives introduced	
 	in Version 4.0	
 	 	
PROGRAM ERROR messages        Program errors.  The program has detected it	
 	has done something wrong.  The conversion may still	
 	be successful, but there is nothing you can do about	
 	such messages except report them to the program's	
 	author at info<at>jafsoft.com	
 	 	
*URL	messages*  URL detection.  When a URL is found a message	
 	is displayed.  When switched on this can be a quick way	
 	of listing all the URLs in a file :-)	
Drag and drop settings
These options specify the behaviour of AscToPDF when invoked via drag and drop (i.e. by dropping a file icon on AscToPDF's icon). 
Show the status screen 
The status dialog, showing messages reporting how the conversion is going should be shown. 
View results in browser once complete 
The selected viewer (browser) for the results files should be invoked on the last file converted once conversion is complete 
Start program after conversion 
The program should be launched in Windows mode once the conversion is completed. 

Results viewers settings
This identifies the viewers to be used whenever AscToPDF launches an application to view a results or documentation file.  Viewers may be required for both HTML and PDF files. 
You can elect to have results viewed automatically after each conversion.  This will normally result in the named application being launched to view the last file converted. 
For HTML, you can elect to use Dynamic Data Exchange (DDE) to have the results displayed in a currently active browser.  This can be quicker and more efficient that launching a new instance of the browser each time.  You should ensure your DDE browser matches the program named as the default browser so that if not already active, the program can start a fresh instance. 
When DDE is used the results will vary from browser to browser. IE for example will come to the front, whereas Netscape will not, and if it is minimised you won't see the results until you maximise the browser again. 
For PDF, DDE is not currently available. 
Use of policy file settings
Using a default policy file 
This determines which policy file, if any, is to be used by default when AscToPDF is first invoked.  The actual policy file used can, of course, be changed via the policy dialogue. 
The default policy file will also be used if AscToPDF is invoked via drag'n'drop.  This avoids the need for creating batch files with the policy file name on the command line. 
Always reload policy file during conversion 
This specifies that the current policy file should be reloaded every time the conversion is done.  If the file is large, and you are repeatedly converting using the same policy file, then this can slow you down.  On the other hand if you are editing the policy file by hand outside the program between conversions then you will want this option enabled. 
Language menu
From version 3.2 onwards it is possible to change the user interface to the language of your choice.  This is a process being rolled out by a number of volunteers who are converting the menu, dialog, ToolTips, message and documentation text.  At any given time you may still find English translations, especially in the messages displayed, and in the help and documentation files, but it is hoped that the efforts of these volunteers will make the program easier to use for non-English speakers. 
Supported languages 
At present work is under way on 
Spanish	Gonzalo San Martin is undertaking the Spanish translation.	
 	Gonzalo operates a highly popular Real Madrid fan page (in	
 	Spanish and English) which you can visit at	
 	http://members.bigfoot.com/~G.SanMartin/ 	
 	Gonzalo can be contacted at G.SanMartin<at>bigfoot.com	
 	 	
Italian	The Italian translation is being undertaken by	
 	Gianluigi Pizzuto who can be contacted at gibly<at>libero.it and	
 	has a web page at http://web.tiscalinet.it/fotone 	
 	 	
Swedish	The Swedish translation is being undertaken by Dan Svarreby	
 	who can be contacted at dan.svarreby<at>home.se.	
 	 	
German	The German translations is being undertaken by Jörg Feierabend	
 	who can be contacted at zeitenwanderer<at>t-online.de	
 	 	
French	The French translation is being undertaken by Andre Martinez.	
 	 	
Portuguese	The Portuguese translation is being undertaken by Ana Maria	
 	G. F. de Mello who can be contacted at anagfm<at>bigfoot.com	
 	 	
Dutch	The Dutch translation is being undertaken by Jurrien Dokter,	
 	who can be contacted at info<at>axswebsolutions.nl and runs	
 	the web site at http://www.axswebsolutions.nl/ 	
If you would like to volunteer to help with this effort, please email translations<at>jafsoft.com or visit the web page at 
http://www.jafsoft.com/products/translations.html 
Language "Skins"
From version 1.1 the program supports the use of language 'skins' 
Language 'Skins'
AscToPDF supports the use of "language skins", that is the ability to export, edit and re-import from text file the strings used in the program's user interface. 
The "language skin" is a text file, usually with an .lng extension.  This file consists of one string per line, with each line being numbered to identify the string.  You can edit these strings into your own language, and then reload the modifications back into the program.  If you do this, make sure you leave the numbers unchanged. 
Export current language setting to file 
This option allows you to export all the current language strings to an external .lng file.  You may then edit this file to get the user interface strings that you want. 
Load a language "skin" 
If you check the "use language skin" box, then the program will load the specified file each time it runs, using the text in that file as the user interface.  Changes will take effect when you press OK. 
View menu
This menu contains the following options 
·	Messages from last conversion
·	View conversion results
View conversion results
Once you've converted a file, you can view the results in the browser of your choice.  AscToPDF will detect the default browser used on your system.  If you wish you can change this through the settings menu 
You can view results in the selected browser by selecting the option on the view menu or by pressing the View results button on the main screen. 
AscToPDF can also be configured to automatically review results when run from the command line or in drag'n'drop operation. 

Help menu
The help menu has the following options:- 
Contents	Brings up the contents page of this help file.  Help can be
brought up anywhere in the program by pressing F1

HTML doco (offline)	Brings up the local copy of the HTML documentation in your
preferred browser

HTML doco (online)	Brings up the Internet copy of the HTML documentation in your
preferred browser.

Register (online)	In the evaluation version this will take you to the web page
which gives registration details. You will need to be
online for this to work

About	Shows the program version and other details.  Includes buttons
to take you to the home page etc on the web.

Update menu
The update menu has the following option 
Check for newer versions
This option will take you to the web site, where a check will be made to tell you if this is still the latest version of the software. 

Status window
The status window is displayed whenever a conversion is in progress. It displays messages showing how the conversion is progressing. 
Usually these are just informational messages telling you of lines on which AscToPDF hasn't performed markup because they "fail policy". For example a line with a number at the beginning won't be turned into a header unless the number is in sequence, and the line is at the correct indentation level. 
You should review these messages and check they don't indicate an error in conversion. 
This screen can be retrieved by pressing the "Show messages window" button on the main window. 

Running as a command line program
You can run AscToPDF from the command line inside a Command Line ("DOS") window. You can also run a console version, A2PCONS. 
The command line has the syntax 
c:> A2PCONS <files1> [<files2> ...] [<policy file>] [/qualifiers]
if running the console version, or 
c:> AscToPDF <files1> [<files2> ...] [<policy file>] [/qualifiers]
if running the Windows version (although this doesn't support all qualifiers). 
If you supply no <files1> on the command line, then the windows version will be launched as normal, but the console version will prompt you for filenames.  The <files1> value can be any valid filespec, including wildcards. You can supply additional <files2>, <files3>... values should you wish.  For example 
c:> a2hcons a*.txt b*.txt c*.txt abc.pol /out=c:\temp\
will convert all the files a*.txt, b*.txt and c*.txt in the current folder using the policy file abc.pol and place all the output files in the folder c:\temp\. 
If you supply one or more valid <files> value these files will be converted. 
For the Windows version, depending on the Settings you've selected, the Status Window will be displayed during the conversion, the program will display once finished, and a viewer may be launched to view the results. 
Note, generally we advise using the console version for command line operations 
If you want to use a policy file, add this to the argument list.  The policy file must have a .pol extension, and only the first policy file listed will be used. 
Recognised qualifiers include 
/COMMA	Input file is a comma-delimited table
/CONSOLE	Direct the output to the console stdout stream
/DOS	Generate DOS 8.3 filenames
/HELP	Generates a HELP message
/LOG=filename	Generate a log file.
/LIST=filename	Generate a list file.
/OUTPUT=filespec	Specify the output filename(s)
/POLICY=filename	Generate a .pol policy file from the analysis of the source file
/SILENT	Suppress all console messages
/SIMPLE	Treat the source file as "simple", i.e. don't look for complex constructs
/TABBED	Input file is a tab-delimited table
/TABLE	Input file is a plain text table

Qualifiers must begin with the slash (/) character but may be of mixed case and may be shortened provided they remain unique.  So /H will get you help, whereas you can't use /S since that could be /SILENT or /SIMPLE 
Command line qualifiers: /COMMA
Specifies that the source file is a comma-delimited table.  In this case each line will become a row in a table, and each value separated by a comma will become a cell in the table. 
Command line qualifiers: /CONSOLE
Specifies that the output should be direct to the output stream.  This should normally be used with command line qualifiers: /SILENT to suppress all status messages. 
This option could be useful if you wanted to pipe the output into some other application. 

Command line qualifiers: /DEBUG
This qualifier will cause the program to generate diagnostics files. 
Command line qualifiers: /DOS
If specified the output filenames will be in the 8.3 format 
Command line qualifiers: /HELP
On the console version this generates a help message detailing usage. 
Command line qualifiers: /LIST
These qualifiers cause AscToPDF to generate some diagnostic files, which have extensions 
	.LIS1		an analysis before policy is set	
	.LIS		an analysis after policy is set	
The list files can assist in understanding how AscToPDF has interpreted your file.  The .stats file is neither pretty, nor easy to read, but can in extreme cases assist in diagnosing faults should you wish to report them. 
If Command line qualifiers: /LIST is used, only the list files are created. 
Command line qualifiers: /LOG
This qualifier will cause the status messages created by the program to be copied into a log file.  This log file will include messages suppressed from the user interface. 
You can specify a filename as /LOG="<name>", the default filename, if omitted, will be AscToPDF.log 
Command line qualifiers: /OUTPUT
The /OUTPUT=filename qualifier specifies where the output file(s) should be placed.  It can include wildcards, with the input file being used to replace any parts of the filename not specified. 
Thus "/OUT=c:\temp\*.sav" will result in a file with the same name, but with a .sav extension, and in the "c:\temp\" directory folder. 
If omitted, the output file will be given the same name as the input file but with a .pdf extension. 
Command line qualifiers: /POLICY
This qualifier will cause the program to generate a .pol file for each file converted.  This file will represent the "best guess" policy file generated by the program through analysis of your file. 
WARNING	The .pol file will have the same name as the file being converted with a .pol extension, and will overwrite any existing policy file of the same name. For this reason we recommend your input policy files should have different names (e.g.. by adding "in_" in front of the name.

Command line qualifiers: /SILENT
This qualifier suppresses all error messages from being displayed to the console.  Mainly relevant in the console version of the program, rather than the Windows version. 
Command line qualifiers: /SIMPLE
This qualifier indicates that you want the source file treated as a "simple" file, and that AscToPDF shouldn't look for more complex constructs such as headings etc. 
This is equivalent to the Keep it simple policy 
Command line qualifiers: /TABBED
Specifies that the source file is a tab-delimited table.  In this case each line will become a row in a table, and each value separated by a tab will become a cell in the table. 
Command line qualifiers: /TABLE
Specifies that the source file is a plain text table.  In this the program will do its best to analyse the table structure, and reproduce it. 
Running from the 'SendTo' menu
AscToPDF can make a useful addition to your "Send to" menu (available when you right-click on a file in explorer). 
To add AscToPDF to this menu, simply add a shortcut to your SendTo shortcuts folder.  Under Windows 9x this is 
/Windows/SendTo 
under Windows XP this is 
/Documents and Settings/<Your_User_Name>/SendTo 
If you want to use a standard policy file (e.g. with a particular colour scheme), then create a simple .bat file with the command 
AscToPDF %1 standard.pol 

Getting the most from AscToPDF
Making your first attempt
Starting to use the console version
To run the console version A2PCONS simply type 
c:> A2PCONS Input_file.name
at the command line. This will create a file :- 
input_file.pdf 
An output file which will have the same file name with a .pdf extension 
The program may display a number of status messages which are largely informational, and can be ignored if the conversion worked okay.  If it didn't, these messages may give a clue as to where the analysis went wrong. 
Starting to use the Windows version
Enter the name of the file to be converted in the File(s) to convert text field.  You can type in wildcards into this field.  If you wish, use the browse button to search for the file to be converted. 
Alternatively simply drop the file icon from an Explorer window onto the program. 
Once you've chosen the file(s), the output filename and output directory are calculated for you from the filename.  If you wish, you may change these values. 
Press the Convert File(s) button.  The Status Display window will appear briefly showing progress messages.  You can dismiss this display (or tick the option that it does so automatically on completion).  If you wish to view these messages later, you can selected the Show Messages option on the View menu. 
To view the last file converted, press the View results button.  This should launch your default application for the file types (.pdf) just created.  This will usually be your default word processor package. 

Refining your results
If all goes well the resultant PDF file will be satisfactory. 
If there are problems, or if you wish to add to the created file, you can tailor the conversion by changing policies. 

In the Windows version, this is done by editing policies via the Conversion Options menu, which is fully described in the context-sensitive Windows Help file (press F1 at any point). 
The conversions options are also known as "policies", and these can be saved to a text policy file.  Policy files are just text files with one option per line.  If you're careful, they can be edited by hand in a text editor.  It is the format of policies in a policy file that is shown and discussed in this document. 
Policy files created in the Windows version can also be used by the console version. 
Using policy files to improve the conversion
If your initial results are a little strange, then review the policies calculated by the program, and create a "policy file" to tell the program how to do the conversion differently. 
You can do this as follows :- 
a)	By creating a "sample" policy file
You can create a sample .pol policy file that documents the policies used.  Do this either by using the command line 
c:> A2PCONS Input_file.name /policy
or by ticking 
"Generate a sample policy file" 
on the Conversion Options->File Generation tabbed dialogue 
When this is done then the next time you convert the file, in addition to the .pdf file generated, you will now have an output policy file "input_file.POL" which describes the document policy file calculated by AscToPDF and used by it during the conversion. 
This file will contain one line each for all the program policies, most of which should be correct. 
Review the contents of this file, deleting all lines that look correct, and editing all lines that appear to be wrong.  You want to delete "correct" lines, because that leaves the program free to re-calculate these options on a file-by-file basis.  If you leave the "correct" value in the file, you fix the option, which may not be "correct" for later files that you choose to convert. 
Save the modified .POL file which should only contain lines for those policies you think are wrong or want to override. 
You'll may need to review the Policy manual in order to understand the policies to do this fully. 
b)	By re-analysing the file
Under Windows a slightly easier option is to select Conversion Options -> Re-analyse the file.  This will analyse the file and change all the policy values currently on display to be the values calculated by the program.  You can then review and change these values using the tabbed dialogues. 
Once you're happy with your changes, select "Save policies to file" from the menu, saving only the changed policies.  You can review this file in a normal text editor. 
Once you've produced your new input policy file, re-run the conversion using the new policy file.  The program will now override aspects of the calculated document policy with the input policy you've supplied. 
Each document policy file consists of a number of lines of data. Each line has the form 
Keywords     :    Data value(s)

For clarity a number of section headers are added like this : 
[Analysis]

Such headings are ignored, as are any lines whose keywords are not recognised or not yet supported.  The order of policies in the file, and their location within "sections" is totally unimportant. 
The order of policies within the file is usually unimportant, and the placement relative to the "headings" is ignored.  The Headings are simply there to make the file easier to read in a text editor. 
A sample fragment from a calculate policy file looks like this 
[Hyperlinks]
------------	 	
Create hyperlinks:	Yes	
Create mailto links:	Yes	
Create NEWS links:	Yes	
These are all default values used by AscToPDF.  If, for example you want to add a title to your page and prevent email addresses being turned into hyperlinks, simply create a policy file containing the lines 
        [Hyperlinks]
        ------------
        Create mailto links:      No
(Remember the insertion of section headings is optional, as is the ordering of policies within the file). 
By refining the input policy file, you can greatly influence the output that AscToPDF generates 

Using multiple policy files
If you wish to use AscToPDF to support several text files e.g. for a set of Intranet documentation, it may be useful to share some common document policies. 
To support this AscToPDF allows two special types of line in the policy file. 
a)	Include files
include file      :   Link_Dictionary.dat

If a line of this type is encountered, the contents of the file Link_dictionary.dat are included in the current policy file.  This is the best way of sharing data across many converted files. 
b)	"daisy-chain" files
switch to file    :   Other_policy_file.dat

If a line of this type is encountered, the processing of the current file terminates, and continues in the named file. 
This is a way of "daisy-chaining" policy files together which may be useful if you wish to group files together at different levels. 
Use the pre-processor and in-line tags
AscToPDF has a built-in pre-processor.  This allows you to add special codes to your source file that tell the program what you'd like it to do. 
Examples include delimiting tables, or adding a timestamp to the file being converted.  Again, much of this functionality was developed for AscToHTM and may be less useful for PDF generation. 
See Using the pre-processor and pre-processor in-line tags for more details. 

Processing several files at once
The program is capable of processing more than one file in a single run.  There are a number of ways in which you can tell the program which files you want. 
·	You can use wildcards to specify the filenames The wildcard will be expanded to a set of filenames, and each file will be processed in turn. 
·	(From the command line only) You can use a script file That is you can pass the name of a file which lists the files you want converted. 
·	(From the command line only) You can pass in multiple file specifications, each of which can be a wildcard.  For details see running as a command line program 
Using wildcards
You can convert multiple files at one time by specifying a wildcard describing the files to be converted.  The wildcard has to be meaningful to the operating system you are using, and will be expanded in alphabetical order.  Under Windows this ordering may be case-sensitive. 
At present we recommend that wildcards are only used on the contents of a single directory.  Indeed wildcards spanning directories are probably not supported (let's just say it's untested :-) 
Note, the same policies will apply to all files being converted.  If you wish different policies to apply, use a script (see 4.3.3.2) 
Note	In the trial version, wildcard conversions are limited to only 5 files

Using script files
From the command line you can convert several files at the same time in the order and manner of your choosing.  To do this use the command 
c:> A2PCONS @List.file [rest of command line]
Where the file "list.file" is a steering file which contains a list of AscToPDF command, and the "@" in front indicates it is a list file, rather than a file to be converted. 
An example list file might look like 
! this is the main document	
DOCO.TXT
#	IN_DOCO.POL	
# These are the
CHAPTER2.TXT	other chapters	
CHAPTER3.TXT	/SIMPLE	
Note the use of "!" or "#" at the start of a line signifies it's a comment line to be ignored. 
Any qualifiers used on the original A2PCONS line will be used as defaults for each conversion, but will be overridden by any listed in the list file.  In this way it would be possible to specify a default policy file for a bunch of similar conversions. 
Note	In the trial version, batch conversions are limited to only 5 files

Generating log files
If you want a log of what has been done, you can create a log file. This can be done in a number of ways :- 
·	From the command line
On the command line you can use to launch the program, add the /LOG=<filespec> qualifier (see command line qualifiers: /LOG). 

·	From the Status Dialog
In the Windows version, the Status Dialog now contains a "Save to file" option to save the displayed messages. 

Understanding the PDF generated
Before converting files to PDF, AscToPDF first attempts to analyse your document looking for the following components. 
·	Text layout
·	Paragraph detection
·	Indentation detection
·	Bullets and list detection
·	Text formatting
·	Emphasis detection
·	Unix Emphasis character detection
·	Headings and section titles
·	Numbered heading detection
·	Capitalised heading detection
·	Underlined heading detection
·	Embedded heading detection
·	Key phrase headings
·	Numbered paragraph detection 
·	diagrams and tables
·	Line detection
·	Form feed page markers
·	User defined pre-formatted text 
·	Automatically detected pre-formatted text
·	Table detection
·	Code sample detection
·	ASCII art and diagram detection
·	Text block detection
·	Other formatted text
Text layout
The software can detect several types of text layout.  For more details see the following topics. 
·	Paragraph detection
·	Indentation detection
·	Hanging paragraph indent detection
·	Bullets and list detection
Paragraph detection
AscToPDF can automatically detect paragraphs in your document. Normally this is done by detecting blank lines between paragraphs, but when there are no blank lines other features such as short lines at the end of a paragraph and an offset at the start of each new paragraph may also be taken into account. 

Indentation detection
AscToPDF performs statistical analysis on the document to determine at what character positions indentations occur.  This information is used on the output pass to determine the indentation level for each source line. 
In calculating the indent positions AscToPDF first converts all tabs to spaces.  This may result in unexpected indent positions, but shouldn't normally be a problem.  If it is, adjust the Tab size policy. 
AscToPDF may reject indentations that appear too close together, so as to keep the number of indent levels manageable. 
You can override the analysis by specifying your own indentation policy.  This can sometimes be useful to add an extra indentation level, or to better match up bullet paragraphs with non-bullet paragraphs. 
See also Indentation policy and Bullet policies 

Hanging paragraph indent detection
Some documents have hanging paragraph indents.  That is, the first line of each paragraph starts at an offset to the rest of the paragraph. 
AscToPDF struggles heroically with this, and tries not to treat this as text at two indent levels, but it does occasionally get confused. 
If writing a text file from scratch with AscToPDF in mind, then it is best to avoid this practice. 
Bullets and list detection
AscToPDF detects and supports several types of bullets and lists. This has the effect of putting the bulleted text one level of indentation to the right of the current text. 
Should the analysis fail, you can override any and all of these via the analysis bullet policies 
Bullet paragraphs
AscToPDF will attempt to detect bullet paragraphs, that is, paragraphs that belong to the bullet point.  To do this it attempts to match the indentation of follow-on lines with that past the bullet character(s) on the bullet line itself. 
Currently this detection only stretches to the paragraph containing the bullet. 
Possible problems 
1)	Numbered bullets may sometimes get confused with numbered sections.  This can be corrected by switching off numbered sections (if there aren't any), replacing the numbered bullets by letters or roman numerals, or by moving the numbered bullets to a different indentation level from the section numbers.
2)	AscToPDF currently only detects the first paragraph belonging to a bullet.  If the bullet has several paragraphs there may be alignment problems, as the positioning of the second and subsequent paragraphs will depend on the indentation policy. Sometimes careful balancing of the indentations and the indentation policies can sort the problem.

Bullet chars
Bullet chars are lines of the type 
- this is a bullet line

- this is a bullet paragraph
because it carries over onto
more lines

That is, a single character followed by the bullet line.  AscToPDF can determine via statistical analysis which character, if any, is being used in this way.  Special attention is paid to the '-' and 'o' characters. 
Numbered bullet detection
AscToPDF can spot numbered bullets.  These can sometimes be confused with section headings in some documents.  This is one area where the use of a document policy really pays dividends in sorting the sheep from the goats. 
Alphabetic bullet detection
AscToPDF detects upper and lower case alphabetic bullets. 
Roman Numeral bullet detection
AscToPDF detects upper and lower case roman numeral bullets. 

Text formatting
In addition to various types of formatted text layouts, the software can detect a number of special types of text formatting, including the following. 

·	Emphasised text
·	Unix emphasis characters
Emphasis detection
AscToPDF can look for text emphasised by placing asterisks (*) either side of it, or underscores (_).  AscToPDF will convert the enclosed text to bold and italic respectively using Bold and italic tags respectively. 
AscToPDF will also look for combinations of asterisks and underscores which will be placed in bold italic.  The asterisks and underscores should be properly nested. 
The emphasised word or phrase should span no more than a few lines, and in particular should not span a blank line.  If the phrase is longer, or if AscToPDF fails to match opening and closing emphasis marks, the characters are left unconverted. 
Tests are made to ignore double asterisks and underscores, and sometimes adjacent punctuation will prevent the text being marked up. 
Only markup that occurs in matched pairs over 2-3 lines will be converted, so _this and that* won't be converted. 

Unix emphasis character detection
AscToPDF also tries to handle use of Ctrl-H in Unix documents. In such documents Ctrl-H can be used to overstrike characters. Common effects are double printing and underlining.  Where detected AscToPDF will use bold and underlining markup. 
Examples could include:- 
The word this^H^H^H^H____ is underlined. The word that^H^H^H^Hthat is bold (overwritten twice). 

Headings and section titles
AscToPDF recognises various types of headings.  Where headings are found, and deemed to be consistent with the prevailing document policy (correct indentation, right type, in numerical sequence etc), AscToPDF will use the standard "Heading n" styles. 
In addition to this, AscToPDF will insert a bookmark to allow direct access via the PDF bookmarks feature 

Numbered heading detection
Sections of type N.N.N can be checked for consistency, and references to them can be spotted and converted into hyperlinks. 
At present more exotic numbering schemes using roman numerals and letters of the alphabet are not fully supported. 

Capitalised heading detection
AscToPDF can treat wholly capitalised lines as headings.  It also allows for such headings to be spread over more than one line. 

Underlined heading detection
AscToPDF can recognize underlined text (e.g. a row of minus signs), and optionally promote the preceding line to be a section header. 
The "underlining" line should have no gaps in it, and should be a similar length to the preceding heading.  If these conditions aren't met you'll probably get a horizontal rule instead. 
If you're authoring a file from scratch, it is probably best to use underlined headings for ease of use. 
Embedded heading detection
The program can look for headings "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.  Where detected the heading will be marked up in bold, rather than <Hn> 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 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 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. 

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 
·	Lines
·	Form feed page markers
·	User defined pre-formatted text
·	Automatically detected pre-formatted text
·	Tables
·	Code samples
·	Diagrams and ASCII art
·	Text blocks
·	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 Using the pre-processor). 
For example :- 
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.

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 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 Minimum size of automatic <PRE> 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 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 TABLE pre-processor markup (see the Tag manual).  Alternatively you can try adding blank lines before and after, as the analysis uses white space to delimit tables. 

You can alter the characteristics of all or individual tables via the table pre-processor commands (see TABLE). 

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 CODE pre-processor markup. 
Or you can suppress the whole thing altogether via the policy 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 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. 

Using 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. 
analysis policies 
·	General Analysis
·	Headings Policies
·	Bullets
·	Pre-formatted text
What are Policy files?
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 : <policy value> 
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 Using policy files for more information. 

Analysis 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. 
·	'What to look for' policies
·	General Analysis
·	Bullets
·	File generation
·	Headings Policies
·	Pre-formatted text
'What to look for' policies
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. 
·	Look for indentation
·	Look for paragraphs
·	Look for short lines
·	Look for bullets and numbered lists
·	Look for mail and USENET headers
·	Look for regions of preformatted text

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
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 General Analysis tabbed policy sheet. 
Look for white space
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 General Analysis tabbed policy sheet. 
Look for short lines
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 General Analysis tabbed policy sheet. 

Look for bullets and numbered lists
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 bullet analysis tabbed policy sheet. 

Look for mail and USENET headers
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. 

Look for preformatted text
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 Pre-formatted text 
tabbed policy sheets.

General analysis policies
These policies aid AscToPDF's analysis by describing in detail what the contents of the document being converted are 
Sizes 
·	Page Width
·	TAB Size
·	Short line length
·	Min Chapter Size
Paragraphs 
·	Blank lines between paragraphs
·	New paragraph offset

Layout 
·	Indentation levels
Page Width
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
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
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
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
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 hanging indent at the start of each new paragraph. 
This should be automatically detected. 
New Paragraph Offset
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 

Indent position(s)
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
AscToPDF should be able to detect the use of bullets on a reasonably sized document.  These policies describe the type of bullets expected. 
·	Automatically detect bullets and numbered lists

Expected Bullet types 
·	numbered bullets
·	alphabetic bullets
·	roman numeral bullets

Bullet characters 
·	recognize hyphen character as a bullet point
·	'recognize an "o" character as a bullet point'
·	Other bullet point characters
Look for 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 'What to look for' policies tabbed property sheet. 
Expect Numbered bullets
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
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
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
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
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
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. 

Contents policies
This dialog shows both analysis and output policies connected with contents list detection and generation. 
Analysis
·	Expect contents list
Expect contents list
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 Documentation available 

File Structure policies
These policies aid AscToPDF's analysis by describing some of the file structure that would affect the analysis. 
·	Expect only a simple layout

Expected File contents
·	'Expect "C"-code samples'
·	Contains DOS characters
·	Contains PCL printer codes
·	Contains non-European (e.g. Japanese) characters
·	Contains mime-encoded quotable characters
·	File has change bars
·	File has Page markers
·	Page marker size (in lines)

Text Attributes
·	Text justification
·	File is double spaced

Text to ignore
·	Number of lines to ignore at start of document
·	Number of lines to ignore at end of document
Keep it 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
AscToPDF can markup C-like code fragments in <PRE>...</PRE> 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
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
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
*** 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
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
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
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)
The number of lines after each form feed (FF) that should be ignored.  These lines will not be copied to the output. 
Text Justification
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
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
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
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. 

Headings policies
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. 
·	Expect Numbered headings
·	Expect Underlined headings
·	Expect Capitalised headings
·	Expect Embedded headings 
·	Heading Key phrases 
·	Use first line as heading
·	Center first heading
·	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 the heading details dialog 
Note:   This area of functionality is continually under review. 
See also the discussion in detecting headings and section titles. 

Expect 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 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
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 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
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 expect numbered headings policy instead. 
Expect 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
If specified, then any line that begins with one of the key phrases will be regarded as a heading.  The syntax is 
<details>, <details>... 
where each set of details is 
<details> = <phrases>, [<heading_level>] 
and 
<phrases> = <phrase_1> [|<phase_2>] 
That is, each set of <details> can optionally specify a <heading_level>. 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 <details> must supply a set of <phrases>, 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. 

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 use first line as heading 
Check indentation for consistency
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
This dialog is reached through one of the edit buttons on the main Headings Policies dialog.  This allows you to edit details of a particular type or level of heading. 
Position of section number on the line 
·	Indentation of heading lines
·	Heading prefix words
Section number formatting 
·	Heading numbering scheme
·	Heading separator characters
·	Heading trailing letters
Bracketing 
·	Heading bracket characters
Indentation of heading lines
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
Some documents put words like "chapter", "subject" and "section" in front of the section number.  These are known as prefix words. 
Heading numbering scheme
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
This shows the separator expected between parts of the heading number. 
*** Not currently supported *** 
Heading trailing letters
This shows whether we expect trailing letters after the section number, as in "1.1b". 
*** Not currently supported *** 
Heading bracket characters
This shows what bracket characters (if any) we expect before and after the section number as in "[2.2]" or "3.2.1)". 
*** Not currently supported *** 
Pre-formatted text policies
These policies specify how AscToPDF detects pre-formatted text. 
Detecting pre-formatted regions 
·	Minimum size of automatic <PRE> section
See the section on pre-formatted text for more details. 
Minimum size of automatic <PRE> section
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 <PRE> is a reference to the shared ancestry of this software with the text to HTML converter from which it evolved. 

Using the pre-processor
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 
·	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) 
·	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. 
Pre-processor commands come in several types:- 
Document commands	Commands that change the document title and keywords etc
Section delimiters	Commands that delimit sections in the source text
Other commands	Other miscellaneous commands

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 "[[" and "]]".  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.

Document commands
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. 
DESCRIPTION	Add a description in the document properties
KEYWORDS	Add keywords to the document properties
TITLE	Add a Title to the PDF pages

Pre-processor command: 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 
$_$_DESCRIPTION <rest of line is used as a description>

This takes precedence over any description added via a policy file. 
Not yet implemented 
Pre-processor command: 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 
$_$_KEYWORDS <rest of line is used as a list of keywords>

This takes precedence over any keywords added via a policy file. 
Not yet implemented 

Pre-processor command: 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 
$_$_TITLE <rest of line is used as a title>

This title takes precedence over any title added via a policy file. 
Not yet implemented 
Section delimiters
These commands mark the start and end of various sections in your document 
ALLOW and DISALLOW	Enable and disable certain types of detection.
CONTENTS	Mark a section as the contents list.
CODE	Mark a section as C-like code sample
DIAGRAM	Mark a section as a diagram or ASCII Art
IGNORE	Ignore a section of the document
PRE	Mark a section as pre-formatted text.
TABLE	Mark a section as a table.
COMMA_DELIMITED_TABLE	Mark a section as comma-delimited data table.
DELIMITED_TABLE	Mark a section as a tab-delimited data table.
SECTION	Mark the start of a user-specified section.

Pre-processor command: 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 
ALLOW/DISALLOW	<comma-separated list of keywords>

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 
$_$_ALLOW reset, Headings

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. 
        $_$_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

Pre-processor command: 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_CONTENTS
        ...
        $_$_END_CONTENTS
AscToPDF will then attempt to treat the enclosed text as a contents list. 
See comments on contents policies 
Pre-processor command: 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_CODE
        ...
        $_$_END_CODE
AscToPDF will then mark up the enclosed text in fixed width fonts. 
See comments on pre-formatted text 
Pre-processor command: COMMA_DELIMITED_TABLE
These commands delimit a table of comma-delimited data 
Syntax: 
        $_$_BEGIN_COMMA_DELIMITED_TABLE
        ...
        (lines of comma-delimited data)
        ...
        $_$_END_COMMA_DELIMITED_TABLE
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 Pre-processor command: TABLE 

Pre-processor command: DELIMITED_TABLE
These directives delimit a table of delimited data 
Syntax: 
        $_$_BEGIN_DELIMITED_TABLE [<delimiter>]
        ...
        (lines of delimited data)
        ...
        $_$_END_DELIMITED_TABLE
where 
<delimiter>	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 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 Pre-processor command: TABLE 

Pre-processor command: 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_DIAGRAM
        ...
        $_$_END_DIAGRAM
AscToPDF will then mark up the enclosed text in fixed width fonts. 
See comments on pre-formatted text 

Pre-processor command: 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_IGNORE
      ...
      (text to be ignored)
      ...
      $_$_END_IGNORE
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
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
        ...
        $_$_END_PRE
AscToPDF will then mark up the enclosed text in fixed width fonts. 
See comments on pre-formatted text 

Pre-processor command: 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_TABLE
        ...
        $_$_END_TABLE
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 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 DELIMITED_TABLE and COMMA_DELIMITED_TABLE commands. 
Note in each case the presence of these directives overrides any 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. 

Pre-processor command: 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: 
        $_$_SECTION <name>
        ...
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: 
        $_$_SECTION all
        ...

Other commands
BR	Insert a line break
CHANGE_POLICY	Dynamically vary policies through the input file
FILENAME	Output the original filename
IGNORE_THIS	Ignore some text in the source
INCLUDE	Include an external file into the source
PAGE	Create a page boundary at this location
VERSION	Output the program version used in this conversion

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
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 
$_$_CHANGE_POLICY <policy line as in policy file>

For example placing 
$_$_CHANGE_POLICY Convert mailto links : yes

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: 
[[FILENAME]] 
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 [[FILENAME]] at [[TIMESTAMP]]" 
which becomes 
"This file was converted from asctopdf.txt at 17-Apr-2006" 

Pre-processor command: IGNORE_THIS
This is an in-line tag whose contents are ignored.  Could be used for comments 
Syntax: 
[[IGNORE_THIS <anything_you_like>]] 
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 IGNORE command 
Pre-processor command: INCLUDE
You can include one source file in another by using the include command as follows:- 
$_$_INCLUDE filename

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:
[[VERSION]] 
Outputs the version name of the conversion into the output file.  For example "AscToRTF 2.0". 

Using Text Command Files
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. 
Various commands are available as follows 
ignore_line	Identifies lines to be discarded from the input
remove_text	Identifies text to be removed from the input
replace_text	Identifies text to be replaced by other text
treat_line	Identifies how a line should be treated
meta_tag_line	Identifies lines to be converted into META tags in HTML

Text Commands available
Text Command : ignore_line
The ignore_line command identifies lines that should be ignored in the input. 
Syntax: 
ignore_line <line_selection>

Any line matching the specified 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: 
remove_text <match_type> "match string"

Any line containing text that matches the specified 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: 
or	replace_text <match_type> "match string" by_string "new string" replace_text <match_type> "match string" by_character "<char>"
Any line containing text that matches the specified 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 "<char>" 
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: 
treat_line <line_selection> <as_line_type>

With this command any line that matches the specified line_selection criteria will be regarded as the specified as_line_type. 
For example the command 
treat_line starting_with string "news" as_header_1

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: 
meta_tag_line "tag name" <line_selection> [remove_match_text]

This command specifies that any line matching the 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 
meta_tag_line "author" starting_with string "author: " remove_match_text

Will match the line 
Author: Dr John A Fotheringham 
will remove the "author: " from this line, and create a META tag as follows 
<META NAME="author" CONTENT="Dr John A Fotheringham"> 
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 ignore_line command to ensure that the line became a META tag, but wasn't included in the conversion output itself. 

Text Command line elements
line_selection
The line_selection element is actually a combination of a number of simpler elements as follows 
Syntax: 
<line_match> <match_type> "match string"

That is the line_selection consists of a line_match, a 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 
starting_with	string	"Chapter"	
starting_with	exact_phrase	"Author : "	
 	 	 	
containing	phrase	"click here"	
containing	string	"http://"	
line_match
The line_match element specifies where on the input line the specified text should be located.  The options are 
starting_with	Text should be at start of line (ignoring any white space)
containing	Text can be anywhere on the input line
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 
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 (*)	
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 
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.
replace_type
The replace_type element is used in the 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:- 
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.
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 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 
as_heading_<n>	Where <n> is "1","2"..."6".  The matched	
 	line is treated as a heading of level <n>	
 	 	
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.	
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. 
An example Text Command File
Below is an example Text Command file: 
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"	 	
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. 

Diagnosing conversion errors
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 Documentation available as this is expected to give more detail 
If you've registered:- 
Contact the author for advice. 

Change History
Here are the versions of AscToPDF that have been released to date. 
·	Version 0.9 (April 2006)
Version 0.9 (April 2006)
The initial beta version is released after months and months (some might say years) of promising it. 

Ordering your copy
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 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 API version. 
For more information, visit the web page, or email info<at>jafsoft.com 

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
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

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
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 info<at>jafsoft.com 
Contacts on the Web
The home page
The AscToPDF home page is hosted on the JafSoft Limited web site. 
Feedback
E-mail any feedback to info<at>jafsoft.com (replace the "<at>" 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 info<at>jafsoft.com (replace the "<at>" 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. 

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. 

API version
For those wishing to call AscToPDF programmatically, an API has been developed.  This is sold under separate license.  Contact info<at>jafsoft.com if you're interested (replace the "<at>" 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. 

Documentation available
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. 

Acknowledgements
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.