$_$_TITLE Documentation for the AscToRTF conversion utility $_$_DESCRIPTION AscToRTF is a utility for converting plain text (ASCII) into Rich Text Format. $_$_CHANGE_POLICY Indent Position(s) : 0 4 8 12 16 $_$_CHANGE_POLICY Create mailto links : no $_$_CHANGE_POLICY Default font : Arial, regular, 10 $_$_CHANGE_POLICY Could be blank line separated : yes $_$_TABLE_HEADER_COLS 1 $_$_TABLE_BORDER 0 $_$_HELP_SUBJECT "Introduction to AscToRTF" $_$_SECTION MAKINGRTF AscToRTF Help Index ******************* $_$_SECTION MAKINGHTML [[HTML

Documentation for the AscToRTF text-to-RTF conversion utility

]] $_$_SECTION ALL $_$_HELP_TOPIC_ID HID_ANAL_BULLETS $_$_HELP_TOPIC_ID HID_ANAL_CONTENTS $_$_HELP_TOPIC_ID HID_ANAL_FILESTRUCT $_$_HELP_TOPIC_ID HID_ANAL_HEADINGS $_$_HELP_TOPIC_ID HID_ANAL_LAYOUT $_$_HELP_TOPIC_ID HID_ANAL_LOOKFOR $_$_HELP_TOPIC_ID HID_ANAL_PREFORM $_$_HELP_TOPIC_ID HID_ANAL_TABLE $_$_HELP_TOPIC_ID HID_CONFIG_STYLEFILE $_$_HELP_TOPIC_ID HID_FILE_CONVERT $_$_HELP_TOPIC_ID HID_FILE_EXIT $_$_HELP_TOPIC_ID HID_HELP_ABOUTXXXTOXXX $_$_HELP_TOPIC_ID HID_HELP_CONTENTS $_$_HELP_TOPIC_ID HID_HELP_HTML $_$_HELP_TOPIC_ID HID_HELP_HTML_NET $_$_HELP_TOPIC_ID HID_HELP_REGISTER $_$_HELP_TOPIC_ID HID_MERRILL $_$_HELP_TOPIC_ID HID_OUT_FILE_CONTENTS $_$_HELP_TOPIC_ID HID_OUT_FILE_DIRECTORY $_$_HELP_TOPIC_ID HID_OUT_FILE_FILE $_$_HELP_TOPIC_ID HID_OUT_FILE_FRAMES $_$_HELP_TOPIC_ID HID_OUT_FILE_GENERATION $_$_HELP_TOPIC_ID HID_OUT_FILE_NAMES $_$_HELP_TOPIC_ID HID_OUT_HTML_ADDED $_$_HELP_TOPIC_ID HID_OUT_HTML_HYPERLINKS $_$_HELP_TOPIC_ID HID_OUT_HTML_LINKDICT $_$_HELP_TOPIC_ID HID_OUT_HTML_STYLE $_$_HELP_TOPIC_ID HID_OUT_MISC_PREPRO $_$_HELP_TOPIC_ID HID_OUT_OVERVIEW $_$_HELP_TOPIC_ID HID_OUT_RTF_SETTINGS $_$_HELP_TOPIC_ID HID_OUT_STYLE_COLOURS $_$_HELP_TOPIC_ID HID_OUT_STYLE_CSS $_$_HELP_TOPIC_ID HID_OUT_STYLE_FONT $_$_HELP_TOPIC_ID HID_OUT_STYLE_HTML $_$_HELP_TOPIC_ID HID_OUT_TABLE_TABLE $_$_HELP_TOPIC_ID HID_POLICIES_ANALYSIS $_$_HELP_TOPIC_ID HID_POLICIES_CHANGE $_$_HELP_TOPIC_ID HID_POLICIES_LOAD $_$_HELP_TOPIC_ID HID_POLICIES_OUTPUTTOHTML $_$_HELP_TOPIC_ID HID_POLICIES_RELOAD $_$_HELP_TOPIC_ID HID_POLICIES_RESETTODEFAULTS $_$_HELP_TOPIC_ID HID_POLICIES_SAVE $_$_HELP_TOPIC_ID HID_PROD_ASCTOHTM $_$_HELP_TOPIC_ID HID_PROD_ASCTORTF $_$_HELP_TOPIC_ID HID_PROD_ASCTOTAB $_$_HELP_TOPIC_ID HID_PROD_JAFSOFT $_$_HELP_TOPIC_ID HID_REANALYSE $_$_HELP_TOPIC_ID HID_REMEMBER_SETTINGS $_$_HELP_TOPIC_ID HID_RTF_CONTENTS $_$_HELP_TOPIC_ID HID_RTF_DOCUMENT $_$_HELP_TOPIC_ID HID_RTF_HELP $_$_HELP_TOPIC_ID HID_RTF_LINKDICT $_$_HELP_TOPIC_ID HID_SETTINGS_DIAGNOSTICS $_$_HELP_TOPIC_ID HID_SETTINGS_DOCO $_$_HELP_TOPIC_ID HID_SETTINGS_DRAG $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_ENGLISH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_FRENCH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_GERMAN $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_OTHER $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_PORTUGUESE $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_SPANISH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_SWEDISH $_$_HELP_TOPIC_ID HID_SETTINGS_LOADLANG $_$_HELP_TOPIC_ID HID_SETTINGS_POLICY $_$_HELP_TOPIC_ID HID_SETTINGS_VIEWER $_$_HELP_TOPIC_ID HID_SHOW_STATUS $_$_HELP_TOPIC_ID HID_SHOW_TOOLTIPS $_$_HELP_TOPIC_ID HID_UPGRADE $_$_HELP_TOPIC_ID HID_VIEW_LASTCONVERSION $_$_HELP_TOPIC_ID HID_VIEW_MESSAGES $_$_HELP_TOPIC_ID HIDD_A2HDLG_DIALOG $_$_HELP_TOPIC_ID HIDD_ADDEDHTML $_$_HELP_TOPIC_ID HIDD_ADVANCED_HTML $_$_HELP_TOPIC_ID HIDD_CHOOSE_LANGUAGE $_$_HELP_TOPIC_ID HIDD_COLOURS $_$_HELP_TOPIC_ID HIDD_CSS $_$_HELP_TOPIC_ID HIDD_DETAG $_$_HELP_TOPIC_ID HIDD_DIRECTORY $_$_HELP_TOPIC_ID HIDD_EXPIRED $_$_HELP_TOPIC_ID HIDD_FRAME_COLOUR $_$_HELP_TOPIC_ID HIDD_FRAMES $_$_HELP_TOPIC_ID HIDD_HEADING_LEVELS $_$_HELP_TOPIC_ID HIDD_MERRILL $_$_HELP_TOPIC_ID HIDD_SETTINGS_SINGLEVIEWER $_$_HELP_TOPIC_ID HIDD_SPLASH $_$_HELP_TOPIC_ID HIDD_STATIC $_$_HELP_TOPIC_ID HIDD_STYLE $_$_HELP_TOPIC_ID HIDD_TABLE $_$_HELP_TOPIC_ID HIDD_TAG_MANIPULATION $_$_HELP_TOPIC_ID HIDD_Template $_$_HELP_TOPIC_ID HIDD_TEXT_FRAGMENTS $_$_HELP_TOPIC_ID HIDD_TEXT_MISC $_$_HELP_TOPIC_ID HIDD_TEXT_PARAGRAPHS $_$_HELP_TOPIC_ID HIDD_TEXTFORMAT $_$_HELP_TOPIC_ID HIDD_TEXTLINK $_$_HELP_TOPIC_ID HIDD_TEXTTABLE $_$_HELP_TOPIC_ID HIDR_ACCELERATOR1 $_$_HELP_TOPIC_ID HIDR_MAINFRAME $_$_HELP_TOPIC_ID HID_SHOW_RESULTS $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_ITALIAN $_$_HELP_TOPIC_ID HID_ANAL_BULLETS $_$_HELP_TOPIC_ID HID_ANAL_CONTENTS $_$_HELP_TOPIC_ID HID_ANAL_FILESTRUCT $_$_HELP_TOPIC_ID HID_ANAL_HEADINGS $_$_HELP_TOPIC_ID HID_ANAL_LAYOUT $_$_HELP_TOPIC_ID HID_ANAL_LOOKFOR $_$_HELP_TOPIC_ID HID_ANAL_PREFORM $_$_HELP_TOPIC_ID HID_ANAL_TABLE $_$_HELP_TOPIC_ID HID_FILE_CONVERT $_$_HELP_TOPIC_ID HID_FILE_EXIT $_$_HELP_TOPIC_ID HID_HELP_ABOUTXXXTOXXX $_$_HELP_TOPIC_ID HID_HELP_CONTENTS $_$_HELP_TOPIC_ID HID_HELP_HTML $_$_HELP_TOPIC_ID HID_HELP_HTML_NET $_$_HELP_TOPIC_ID HID_HELP_REGISTER $_$_HELP_TOPIC_ID HID_MERRILL $_$_HELP_TOPIC_ID HID_POLICIES_ANALYSIS $_$_HELP_TOPIC_ID HID_POLICIES_CHANGE $_$_HELP_TOPIC_ID HID_POLICIES_LOAD $_$_HELP_TOPIC_ID HID_POLICIES_OUTPUTTOHTML $_$_HELP_TOPIC_ID HID_POLICIES_RELOAD $_$_HELP_TOPIC_ID HID_POLICIES_RESETTODEFAULTS $_$_HELP_TOPIC_ID HID_POLICIES_SAVE $_$_HELP_TOPIC_ID HID_PROD_ASCTOHTM $_$_HELP_TOPIC_ID HID_PROD_ASCTORTF $_$_HELP_TOPIC_ID HID_PROD_ASCTOTAB $_$_HELP_TOPIC_ID HID_PROD_JAFSOFT $_$_HELP_TOPIC_ID HID_REANALYSE $_$_HELP_TOPIC_ID HID_RTF_CONTENTS $_$_HELP_TOPIC_ID HID_RTF_DOCUMENT $_$_HELP_TOPIC_ID HID_RTF_LINKDICT $_$_HELP_TOPIC_ID HID_SETTINGS_DIAGNOSTICS $_$_HELP_TOPIC_ID HID_SETTINGS_DOCO $_$_HELP_TOPIC_ID HID_SETTINGS_DRAG $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_ENGLISH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_GERMAN $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_OTHER $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_PORTUGUESE $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_SPANISH $_$_HELP_TOPIC_ID HID_SETTINGS_POLICY $_$_HELP_TOPIC_ID HID_SETTINGS_VIEWER $_$_HELP_TOPIC_ID HID_VIEW_LASTCONVERSION $_$_HELP_TOPIC_ID HID_VIEW_MESSAGES $_$_HELP_TOPIC_ID HIDD_ADDEDHTML $_$_HELP_TOPIC_ID HIDD_COLOURS $_$_HELP_TOPIC_ID HIDD_CSS $_$_HELP_TOPIC_ID HIDD_DIRECTORY $_$_HELP_TOPIC_ID HIDD_MERRILL $_$_HELP_TOPIC_ID HIDD_SPLASH $_$_HELP_TOPIC_ID HIDD_STATIC $_$_HELP_TOPIC_ID HIDD_STYLE $_$_HELP_TOPIC_ID HIDD_Template $_$_HELP_TOPIC_ID HIDR_ACCELERATOR1 $_$_HELP_TOPIC_ID HIDR_MAINFRAME $_$_HELP_TOPIC_ID HIDR_MENU_ASCTORTF $_$_HELP_TOPIC_ID HIDR_MENU1 $_$_HELP_TOPIC_ID HIDR_MENU2 AscToRTF is a utility designed to convert plain text files into RTF pages. The program can be used to convert legacy text files to RTF as one-off conversions, or to help you author sets of RTF 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 [[goto analysis policies]]. The RTF generated by the program can be configured to a limited extent via the programs [[goto output 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. $_$_SECTION MAKINGRTFHELP There's a [[goto complete contents list for this document]] Complete contents list for this document ======================================== $_$_HELP_TOPIC_ID ID_CONTENTS_LIST This is a complete contents list for the .rtf file used to generate this help file. Sadly it isn't hyperlinked, but it may help you find what you're looking for. Ignore any page numbers. $_$_SECTION ALL $_$_CONTENTS_LIST 2 $_$_HELP_CHAPTER 1,"Installation" Installation ************ The shareware version of AscToRTF is made available over the web from [a2r Download location]. Once you register you can download the full version (no nags, no limits), and are entitled to free upgrades for an arbitrary (equals "my decision is final") period of time. So far I've *never* requested payment for any [a2r updates] of AscToRTF over the last 2-3 years. 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. $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION ALL $_$_HELP_CHAPTER 2,"Windows Installation" 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 [[goto 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. $_$_HELP_CHAPTER 2,"OpenVMS version" $_$_HELP_SUBJECT "Installation" OpenVMS version of AscToRTF =========================== Sorry. No VMS distribution is planned at this time as RTF is not exactly a VMS-friendly file format. That said, the software - like AscToHTM - is largely developed under VMS, so if there is enough interest this may change. Email *infojafsoft.com* if you're interested (replace the "" by "@"). $_$_HELP_CHAPTER 1,"How it works" $_$_HELP_SUBJECT "Overview" How it works ************ AscToRTF 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. $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION ALL Assumptions made by the program =============================== AscToRTF 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, AscToRTF tries to read the text file and mark it up in RTF accordingly. This is achieved by making three passes through the document, an [[goto The analysis pass,analysis pass]], a [[goto The collating pass,collating pass]], and an [[goto The output pass,output pass]]. Note: Sadly this assumption is not always true :( The analysis pass ================= During the analysis pass AscToRTF 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 AscToRTF generates the RTF file (there's nothing like stating the obvious :-) The RTF generated depends only on the original document, the calculated document policy, and any user policies supplied. [[GOTO Understanding the RTF generated]] describes the markup produced in more detail. $_$_HELP_CHAPTER 1,"Running the software" Running the software ******************** $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION MAKINGRTFHELP - [[goto Running as a Windows application]] - [[goto Running as a command line program]] - [[goto "Running from the 'SendTo' menu"]] $_$_SECTION ALL Overviews ========= - [[goto Understanding the RTF generated]] - [[goto Using policy files]] - [[goto analysis policies]] - [[goto output policies]] - [[goto Using the pre-processor]] - [[goto settings menu,"Saving program preferences"]] - [[goto Diagnosing conversion errors]] Other Information ================= - [[goto Ordering your copy]] - [[goto Upgrade Policy]] - [[goto Documentation available]] - [[goto Acknowledgements]] $_$_HELP_CHAPTER 2,"Running as a Windows application" $_$_HELP_SUBJECT "Overview" Running as a Windows application ================================ $_$_HELP_TOPIC_ID ID_RUN_WINDOWS AscToRTF 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* $_$_BEGIN_DELIMITED_TABLE [[goto File menu]] File options [[goto Conversion Options menu]] Options that affect the conversion [[goto Settings menu]] Edit the program's settings [[goto Language menu]] Select the language you'd like the program's user interface to be in [[goto View menu]] View the created RTF files or the messages for the last conversion [[goto Help menu]] Various help files and on-line resources $_$_END_DELIMITED_TABLE *Data entry fields* The data entry fields show - the file(s) selected for conversion - whether or not you want to [[goto search sub-folders]] - the [[goto 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 [[goto Status Window]] will briefly appear whilst the conversion proceeds. *Policy files* AscToRTF has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the RTF it generates. Policy files are described more fully in [[goto 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 .................. *New in version 2.0* 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 ............... *New in version 2.0* The *Conversion Type* specified how the input file should be regarded during the conversion. The options available include $_$_BEGIN_TABLE 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. $_$_END_TABLE 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. $_$_HELP_CHAPTER 3,"File menu" $_$_HELP_SUBJECT "Options" File menu --------- $_$_HELP_TOPIC_ID ID_MENU_FILE The file menu offers the following options:- $_$_BEGIN_DELIMITED_TABLE Convert This will prompt you for a file to convert and will then convert the selected file(s). [[goto Load policy file]] Load policies from a policy file [[goto Save policy file]] Save the current set of policies to a policy file Exit Exit the program. $_$_END_DELIMITED_TABLE $_$_HELP_CHAPTER 3,"Conversion Options menu" $_$_HELP_SUBJECT "Options" Conversion Options menu ----------------------- $_$_HELP_TOPIC_ID ID_MENU_OPTIONS 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 [[goto Using policy files]] The menu options include:- $_$_BEGIN_DELIMITED_TABLE [[goto Analysis policies]] Edit those policies that affect the analysis of your source document [[goto Output policies]] Edit those policies that affect the type of RTF generated. [[goto Config File locations menu, Configuration File locations]] Specify the locations of various configuration files [[goto Load policy file]] Load policies from a policy file Reload policies from file Allows you to re-load the policy file, or to load a different file. [[goto Re-analysing the input file]] Re-analyse the input file to re-calculate the analysis policies [[goto Resetting policies to default values]] Reset policies to default values. $_$_END_DELIMITED_TABLE 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 [[goto Analysis Policies]] section of this document. Output policies menu .................... The Output Policies menu allows you to change those policies that affect the output of the conversion process. These are discussed fully in the [[goto Output 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 :- - [[goto Selecting the Link Dictionary File,Link Dictionary File]] - [[goto Selecting the Style Definition File,Style Definition File]] - [[goto Selecting the Table Definition File,Table Definition File]] - [[goto Selecting the Text Command File,Text Command File]] Selecting the Link Dictionary File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This option allows you to select the Link Dictionary. When selected it takes you to the Link Dictionary dialogue where you can select the Link Dictionary file you want, and also view and edit its contents (although this could also be done directly using a text editor) If a file has been selected you can press the Edit button to bring up a dialog where you can [[goto Link Dictionary Edit Dialog,edit the selected link dictionary]] although you may find this easier to do using a text editor. See [[goto Using link dictionary files]] Selecting the Style Definition File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This option allows you to select the [[goto Using Style Definition Files (SDF),Style Definition File]] you wish to use. This defines the "styles" that will be available for use in the FO (font) preprocessor tag. It also allows you to select the [[goto Scope for font tags]] See [[goto Pre-processor command: FO]] Selecting the Table Definition File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This option allows you to select the [[goto Using Table Definition Files (TDF),Table Definition File]] you wish to use. Selecting the Text Command File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This option allows you to select the [[goto Using Text Command Files,Text Command File]] you wish to use. Re-analysing the input file ........................... $_$_HELP_TOPIC_ID ID_REANAL This option, available from the [[goto 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 .................................... $_$_HELP_TOPIC_ID ID_RESET_POLICY This option will reset all policies to their default values. If a policy file has been loaded, it will be unloaded. Load policy file ................ $_$_HELP_TOPIC_ID HIDD_OPTIONS AscToRTF has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the RTF 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 [[goto Using policy files]]. Options on this screen include :- - Load policies from an existing policy file - [[popup Save policy file]] to save options to file for later re-use - Reset all policies to their default values Save Policy File ................ $_$_HELP_TOPIC_ID HIDD_SAVE_POLICY 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 $_$_HELP_CHAPTER 3,"The Settings Menu" $_$_HELP_SUBJECT "Options" Settings menu ------------- $_$_HELP_TOPIC_ID ID_MENU_SETTINGS $_$_HELP_TOPIC_ID HIDD_SETTINGS The program settings menu allows you to customise the way AscToRTF executes each time it is invoked. This is kept separate from the use of [[goto what are policy files?,"policy files"]], which are used to customise the actual conversion process. This menu has the following options :- $_$_BEGIN_DELIMITED_TABLE [[goto Documentation Settings]] Specify the location of your documentation on your hard drive [[goto Diagnostic Settings]] Set message filters and alter the error reporting level to control the number and type of messages generated during conversions [[goto Drag and Drop Settings]] Set the program's properties when invoked by dragging files into the icon on the desktop [[goto Results viewers settings]] Specify the viewers to be used for viewing results files, and their method of invocation [[goto Use of policy file settings]] Specify any default policy file to be used. $_$_END_DELIMITED_TABLE Documentation settings ...................... $_$_HELP_TOPIC_ID HIDD_SETTINGS_DOCO 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 ................... $_$_HELP_TOPIC_ID HIDD_SETTINGS_MESSAGES 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 :- $_$_BEGIN_DELIMITED_TABLE *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 *infojafsoft.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 :-) $_$_END_DELIMITED_TABLE Drag and drop settings ...................... $_$_HELP_TOPIC_ID HIDD_SETTINGS_DRAG These options specify the behaviour of AscToRTF when invoked via drag and drop (i.e. by dropping a file icon on AscToRTF'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 ........................ $_$_HELP_TOPIC_ID HIDD_SETTINGS_VIEWER $_$_HELP_TOPIC_ID HIDD_SETTINGS_VIEWER_RTF This identifies the viewers to be used whenever AscToRTF launches an application to view a results or documentation file. Viewers may be required for both HTML and RTF 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 RTF, DDE is not currently available. Use of policy file settings ........................... $_$_HELP_TOPIC_ID HIDD_SETTINGS_POLICY *Using a default policy file* This determines which [[goto what are policy files?,"policy file"]], if any, is to be used by default when AscToRTF 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 AscToRTF 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. $_$_HELP_CHAPTER 3,"Language menu" $_$_HELP_SUBJECT "Language options" Language menu ------------- $_$_HELP_TOPIC_ID HIDD_TRANSLATIONS $_$_HELP_TOPIC_ID ID_MENU_LANGUAGE $_$_HELP_TOPIC_ID ID_SETTINGS_LANGUAGE $_$_HELP_TOPIC_ID HIDD_LANGUAGES 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 $_$_BEGIN_TABLE 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.SanMartinbigfoot.com* Italian The Italian translation is being undertaken by Gianluigi Pizzuto who can be contacted at *giblylibero.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.svarrebyhome.se*. German The German translations is being undertaken by Jörg Feierabend who can be contacted at *zeitenwanderert-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 *anagfmbigfoot.com* $_$_END_TABLE If you would like to volunteer to help with this effort, please email translationsjafsoft.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 [[goto "language 'skins'"]] Language 'Skins' ................ AscToRTF 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. $_$_HELP_CHAPTER 3,"View menu" $_$_HELP_SUBJECT "View menu options" View menu ---------- $_$_HELP_TOPIC_ID ID_VIEW_MENU This menu contains the following options - [[goto Status window,Messages from last conversion]] - [[goto View conversion results]] View conversion results ....................... $_$_HELP_TOPIC_ID ID_VIEW_RESULTS Once you've converted a file, you can view the results in the browser of your choice. AscToRTF will detect the default browser used on your system. If you wish you can change this through the [[goto settings menu]] You can view results in the selected browser by selecting the option on the [[popup view menu]] or by pressing the View results button on the main screen. AscToRTF can also be configured to automatically review results when run from the command line or in drag'n'drop operation. $_$_HELP_CHAPTER 3,"Help menu" $_$_HELP_SUBJECT "Help menu options" Help menu --------- $_$_HELP_TOPIC_ID ID_MENU_HELP The help menu has the following options:- $_$_BEGIN_DELIMITED_TABLE _Contents_ Brings up the contents page of this help file. Help can be brought up anywhere in the program by pressing F1 _RTF doco (offline)_ Brings up the local copy of the RTF documentation in your preferred browser _RTF doco (online)_ Brings up the Internet copy of the RTF documentation in your preferred browser. _Register (online)_ In the shareware 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. $_$_END_DELIMITED_TABLE $_$_HELP_CHAPTER 3,"Status window" $_$_HELP_SUBJECT "The status window" Status window ------------- $_$_HELP_TOPIC_ID HIDD_STATUS_DIALOG 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 AscToRTF 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. $_$_HELP_CHAPTER 2,"Running AscToRTF as a command line program" $_$_HELP_SUBJECT "Command line syntax" Running as a command line program ================================= $_$_HELP_TOPIC_ID ID_RUN_COMMAND You can run AscToRTF from the command line inside a Command Line ("DOS") window. You can also run a [[goto console version]], A2RCONS. The command line has the syntax c:> A2RCONS [ ...] [] [/qualifiers] if running the console version, or c:> AscToRTF [ ...] [] [/qualifiers] if running the Windows version (although this doesn't support all qualifiers). If you supply no on the command line, then the windows version will be launched as normal, but the console version will prompt you for filenames. The value can be any valid filespec, including wildcards. You can supply additional , ... 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 value these files will be converted. For the Windows version, depending on the [[goto settings menu,Settings]] you've selected, the [[goto 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 $_$_BEGIN_DELIMITED_TABLE [[popup command line qualifiers: /COMMA,/COMMA]] Input file is a comma-delimited table [[popup command line qualifiers: /CONSOLE,/CONSOLE]] Direct the output to the console stdout stream [[popup command line qualifiers: /CONTENTS,/CONTENTS]] Generate a contents list [[popup command line qualifiers: /DOS,/DOS]] Generate DOS 8.3 filenames [[popup command line qualifiers: /HELP,/HELP]] Generates a HELP message [[popup command line qualifiers: /LOG,"/LOG=filename"]] Generate a log file. [[popup command line qualifiers: /LIST,"/LIST=filename"]] Generate a list file. [[popup command line qualifiers: /OUTPUT,"/OUTPUT=filespec"]] Specify the output filename(s) [[popup command line qualifiers: /POLICY,"/POLICY=filename"]] Generate a .pol policy file from the analysis of the source file [[popup command line qualifiers: /SILENT,/SILENT]] Suppress all console messages [[popup command line qualifiers: /SIMPLE,/SIMPLE]] Treat the source file as "simple", i.e. don't look for complex constructs [[popup command line qualifiers: /TABBED,/TABBED]] Input file is a tab-delimited table [[popup command line qualifiers: /TABLE,/TABLE]] Input file is a plain text table $_$_END_DELIMITED_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 ------------------------------- _New in version 2.0_ 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 --------------------------------- _New in version 2.0_ Specifies that the output should be direct to the output stream. This should normally be used with [[goto 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: /CONTENTS ---------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_CONTENTS This qualifier will cause a contents list to be generated containing links to all the headings detected ion the source document. See the discussion on [[goto adding a contents list]] and the [[goto contents policies]] Command line qualifiers: /DEBUG ------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_DEBUG This qualifier will cause the program to generate diagnostics files. Command line qualifiers: /DOS ----------------------------- $_$_HELP_TOPIC_ID ID_QUAL_DOS If specified the output filenames will be in the 8.3 format Command line qualifiers: /HELP $_$_HELP_TOPIC_ID ID_QUAL_HELP ------------------------------ On the [[goto console version]] this generates a help message detailing usage. Command line qualifiers: /LIST ------------------------------ These qualifiers cause AscToRTF 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 AscToRTF 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 ----------------------------- $_$_HELP_TOPIC_ID ID_QUAL_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="", the default filename, if omitted, will be AscToRTF.log Command line qualifiers: /OUTPUT -------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_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 .rtf extension. Command line qualifiers: /POLICY -------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_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 -------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_SILENT This qualifier suppresses all error messages from being displayed to the console. Mainly relevant in the OpenVMS and console versions of the program, rather than the Windows version. Command line qualifiers: /SIMPLE -------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_SIMPLE This qualifier indicates that you want the source file treated as a "simple" file, and that AscToRTF shouldn't look for more complex constructs such as headings etc. This is equivalent to the [[goto Keep it simple]] policy Command line qualifiers: /TABBED -------------------------------- _New in version 2.0_ 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 ------------------------------- _New in version 2.0_ 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. $_$_HELP_CHAPTER 2,Running from the 'SendTo' menu $_$_HELP_SUBJECT "Invoking the program from your right-click 'Sent To' menu" Running from the 'SendTo' menu ============================== $_$_HELP_TOPIC_ID ID_RUN_SENDTO AscToRTF can make a useful addition to your "Send to" menu (available when you right-click on a file in explorer). To add AscToRTF to this menu, simply add a shortcut to your /Windows/SendTo directory. 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 *AscToRTF %1 standard.pol* $_$_HELP_CHAPTER 1,"Getting the most from AscToRTF" Getting the most from AscToRTF ****************************** $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION MAKINGRTFHELP This section contains discussions on the following - [[goto Making your first attempt]] - [[goto Refining your results]] - [[goto Using policy files to improve the conversion]] - [[goto Using link dictionary files]] - [[goto Using multiple policy files]] - [[goto Use the pre-processor and in-line tags]] - [[goto Processing several files at once]] - [[goto Using wildcards]] - [[goto Using script files]] - [[goto Generating log files]] $_$_SECTION ALL $_$_HELP_CHAPTER 2,"Getting started" Making your first attempt ========================= $_$_SECTION MAKINGRTFHELP This section contains discussions on the following topics. - [[goto Starting to use the console version]] - [[goto Starting to use the Windows version]] $_$_SECTION ALL Starting to use the console version ----------------------------------- To run the console version A2RCONS simply type c:> A2RCONS Input_file.name at the command line. This will create a file :- input_file.rtf An output file which will have the same file name with a .rtf 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 [[goto View menu]]. To view the last file converted, press the *View results* button. This should launch your default application for the file types (.rtf) just created. This will usually be your default word processor package. $_$_HELP_CHAPTER 2,"Refining your results" $_$_HELP_SUBJECT "Improving your results" Refining your results ===================== If all goes well the resultant RTF 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. Note: Unlike [AsctoHTM], AscToRTF has relatively few output policies, as it is expected that users will "tidy up" the created file using their preferred Word processing application. 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:> A2RCONS 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 .rtf file generated, you will now have an output policy file "input_file.POL" which describes the document policy file calculated by AscToRTF 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 $_$_BEGIN_PRE Keywords : Data value(s) $_$_END_PRE For clarity a number of section headers are added like this : $_$_BEGIN_PRE [Analysis] $_$_END_PRE 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 $_$_BEGIN_PRE [Hyperlinks] ------------ Create hyperlinks: Yes Create mailto links: Yes Create NEWS links: Yes $_$_END_PRE These are all default values used by AscToRTF. 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 $_$_BEGIN_PRE [Hyperlinks] ------------ Create mailto links: No $_$_END_PRE (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 AscToRTF generates Using link dictionary files --------------------------- NOTE: This feature is a legacy from [AscToHTM]. The generation of hyperlinks in RTF documents - though possible - is less likely to be of interest. In addition to adding hyperlinks for all URLs, email addresses, section references and contents list entries, AscToRTF allows users to specify key phrases that should be turned into hyperlinks. This is achieved by adding lines to the input policy of the form $_$_BEGIN_PRE [Link Dictionary] ----------------- Link definition : "[Google]" = "Google search engine" + "www.google.com" $_$_END_PRE The syntax used here is $_$_BEGIN_PRE Link definition : "match phrase" = "replacement phrase" + "link" $_$_END_PRE In this case the string "[google]" is replaced by a link to a web page "www.google.com" with the text "Google search engine" being highlighted. NOTE: Unlike AscToHTM, only external hyperlinks are accepted. Relative links will be ignored since they won't work from inside an RTF document. Using multiple policy files --------------------------- If you wish to use AscToRTF to support several text files e.g. for a set of Intranet documentation, it may be useful to share some common document policies, e.g. colour, headers and footers and particularly the link dictionary. To support this AscToRTF allows two special types of line in the policy file. a) Include files $_$_BEGIN_PRE include file : Link_Dictionary.dat $_$_END_PRE 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 $_$_BEGIN_PRE switch to file : Other_policy_file.dat $_$_END_PRE 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 -------------------------------------- AscToRTF 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 RTF generation. See [[GOTO Using the pre-processor]] and [[GOTO pre-processor in-line tags]] for more details. $_$_HELP_CHAPTER 2,"Processing multiple files at once" 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 [[goto Using wildcards,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 [[goto Using script files,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 [[goto 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 shareware 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:> A2RCONS @List.file [rest of command line] Where the file "list.file" is a steering file which contains a list of AscToRTF 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 $_$_BEGIN_PRE ! this is the main document DOCO.TXT IN_DOCO.POL # # These are the other chapters CHAPTER2.TXT CHAPTER3.TXT /SIMPLE $_$_END_PRE 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 A2RCONS 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 shareware version, batch conversions are limited to only 5 files $_$_HELP_CHAPTER 2,"Generating a log file" $_$_HELP_SUBJECT "Creating a log file" 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= qualifier (see [[goto command line qualifiers: /LOG]]). - *From the policy file* Use the [[goto Generate diagnostics files]] policy. You will need to manually edit this into your .pol file, as it can't be set via the user interface. - *From the Status Dialog* In the Windows version, the Status Dialog now contains a "Save to file" option to save the displayed messages. $_$_HELP_CHAPTER 1,"Understanding the RTF generated" Understanding the RTF generated ******************************* Before converting files to RTF, AscToRTF first attempts to analyse your document looking for the following components. - [[goto Text layout]] - [[goto Paragraph detection]] - [[goto Indentation detection]] - [[goto Bullets and list detection]] - [[goto Definition detection]] - [[goto Text formatting]] - [[goto Centred text detection]] - [[goto Quoted line detection]] - [[goto Emphasis detection]] - [[goto Unix Emphasis character detection]] - [[goto Adding hyperlinks]] - [[goto Contents List detection]] - [[goto Cross-reference detection]] - [[goto URL detection]] - [[goto Usenet Newsgroup detection]] - [[goto E-mail address detection]] - [[goto User-specified keywords]] - [[goto Headings and section titles]] - [[goto Numbered heading detection]] - [[goto Capitalised heading detection]] - [[goto Underlined heading detection]] - [[goto Embedded heading detection]] - [[goto Key phrase headings]] - [[goto Numbered paragraph detection]] - [[goto Pre-formatted text, diagrams and tables]] - [[goto Line detection]] - [[goto Form feed page markers]] - [[goto User defined pre-formatted text]] - [[goto Automatically detected pre-formatted text]] - [[goto Table detection]] - [[goto Code sample detection]] - [[goto ASCII art and diagram detection]] - [[goto Text block detection]] - [[goto Other formatted text]] - [[goto Adding features to the document]] - [[goto Adding a Document Title]] - [[goto Adding a Contents list]] - [[goto The use of RTF stylesheets]] $_$_HELP_CHAPTER 2,"Text layout" Text layout =========== The software can detect several types of text layout. For more details see the following topics. - [[goto Paragraph detection]] - [[goto Indentation detection]] - [[goto Hanging paragraph indent detection]] - [[goto Bullets and list detection]] - [[goto Definition detection]] Paragraph detection ------------------- $_$_HELP_TOPIC_ID ID_PARAGRAPHS AscToRTF 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 --------------------- AscToRTF 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 AscToRTF 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 [[goto Tab size]] policy. AscToRTF 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 [[goto indent position(s),"Indentation policy"]] and [[goto 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. AscToRTF 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 AscToRTF in mind, then it is best to avoid this practice. $_$_HELP_CHAPTER 3,"Bullets and lists" $_$_HELP_SUBJECT "Detecting bullets and lists" Bullets and list detection -------------------------- AscToRTF detects and supports several types of bullets and lists. However it doesn't attempt to convert these into auto-numbered lists (introduced in a later version of RTF). 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 [[goto bullet policies]] Such text is marked up using the "Bullet" Style. See "[[GOTO the use of RTF stylesheets]]". *Bullet paragraphs* AscToRTF 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) AscToRTF 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 $_$_BEGIN_PRE - this is a bullet line - this is a bullet paragraph because it carries over onto more lines $_$_END_PRE That is, a single character followed by the bullet line. AscToRTF 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 ......................... AscToRTF 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 ........................... AscToRTF detects upper and lower case alphabetic bullets. Roman Numeral bullet detection .............................. AscToRTF detects upper and lower case roman numeral bullets. [[LINKPOINT "Definitions"]] $_$_HELP_CHAPTER 3,"Definitions" $_$_HELP_SUBJECT "Definition detection" Definition detection -------------------- AscToRTF will search for definitions. Definitions consist of a definition term and then the definition description. - [[popup One-line definitions]] - [[popup Definition paragraphs]] One-line definitions .................... A definition line is a single line that appears to be defining something. Usually this is a line with either a colon (:) or an equals sign (=) in it. For example $_$_BEGIN_PRE IMHO = In my humble opinion Address : Somewhere over the rainbow. $_$_END_PRE AscToRTF attempts to determine what definition characters are used and whether they are *"strong"* (only ever used in a definition) or *"weak"* (only sometimes used in a definition). AscToRTF marks up definition lines by placing a line break on the end of the line to preserve the original line structure. Where this decision is made incorrectly unexpected breaks can appear in text. AscToRTF offers the option of marking up the definition term in bold. This is not the default behaviour however. Definition paragraphs ..................... AscToRTF also recognises the use of definition paragraphs such as :- $_$_BEGIN_PRE Note: This is a definition paragraph whereby the whole paragraph is defining the term shown on the first line. Unfortunately AscToRTF currently only copes with single paragraphs (i.e. not with continuation paragraphs), and only with single word definitions. $_$_END_PRE AscToRTF can detect such definitions, subject to the current limitations - Only one word definition terms are detected - Only the first definition paragraph is detected. Whether or not subsequent paragraphs are aligned correctly will depend on the indentation policy applied to it. These limitations will hopefully be removed in later versions. Where definition paragraphs are detected the definition will be marked up as hanging paragraphs and (optionally) can have the definition term highlighted in bold. $_$_HELP_CHAPTER 2,"Text formatting" Text formatting =============== In addition to various types of formatted [[goto Automatically detected pre-formatted text,text layouts]], the software can detect a number of special types of text formatting, including the following. - [[goto Centred text detection,Centred text]] - [[goto Quoted line detection,Quoted lines (such as in emails)]] - [[goto Emphasis detection,Emphasised text]] - [[goto Unix emphasis character detection,Unix emphasis characters]] Centred text detection ---------------------- *New in version 2.0* AscToRTF can be made to attempt automatic detection of centred text. When enabled the indentation and length of each line is compared to the nominal page width within a specified tolerance (see [[GOTO "page width"]] and [[GOTO "Automatic centring tolerance"]]) If the line appears centred (and meets a few other conditions) then it will be rendered centred in the output. This option is normally left switched off, as it is fairly prone to errors, not least because the calculation is sensitive to getting the page width calculation correct. When it goes wrong you are liable to find the document centres lines that shouldn't be. Quoted line detection --------------------- AscToRTF recognises that, especially in Internet files, it is increasingly common to quote from other text sources such as e-mail. The convention used in such cases is to insert a quote character such as ">" at the start of each line. Consequently, AscToRTF adds a line break at the end of such lines to preserve the line structure of the original, and marks it up in italics to differentiate the quoted text Such text is marked up using the "Quotes" Style. See "[[GOTO the use of RTF stylesheets]]" Emphasis detection ------------------ AscToRTF can look for text emphasised by placing asterisks (*) either side of it, or underscores (_). AscToRTF will convert the enclosed text to *bold* and _italic_ respectively using *Bold* and *italic* tags respectively. AscToRTF 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 AscToRTF 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 --------------------------------- AscToRTF 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 AscToRTF 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). $_$_HELP_CHAPTER 2,"Hyperlinks and section references" Adding hyperlinks ================ The software can add active hyperlinks to the following :- - [[goto Cross-reference detection,Cross-references to numbered sections]] - [[goto URL detection,URLs of various types]] - [[goto Usenet Newsgroup detection,Usenet newsgroups]] - [[goto E-mail address detection,email addresses]] - [[goto User-specified keywords]] Contents List detection ----------------------- Unlike [AscToHTM], AscToRTF leaves any detected contents list intact and unchanged. However, since headings are marked up in a Heading style, it should be possible to create a TOC in Word from the marked up headings. This being the case, the original text TOC is redundant and best deleted. See [[goto adding a contents list]] Cross-reference detection ------------------------- AscToRTF can convert cross-references to other sections into hyperlinks to those sections. Unfortunately this is currently only possible for second, third, fourth... level numeric headings (n.n, n.n.n, n.n.n.n etc) This is because the error rate becomes too high on single numbers/letters or roman numerals. This _may_ be refined in future releases, although it's hard to see how that would work. It is possible to use AscToRTF tags though, for example the [[goto Pre-processor command: GOTO,GOTO command]] and [[goto Pre-processor command: POPUP,POPUP command]] can create links to named sections. For example $_$_BEGIN_PRE See [[OT]]goto cross-reference detection[[CT]] $_$_END_PRE becomes See [[goto cross-reference detection]] URL detection ------------- AscToRTF can convert any URLs in the document to hyperlinks. This includes http and FTP URLs and any web addresses beginning with www. The domain name part of the URL will be checked against the known domain name structures and country codes to check it falls within an allowed group. So www.somewhere.thing won't be allowed as ".thing" isn't a proper top level domain. URLs that use IP addresses or some more obscure methods of specifying domain names will also be recognised, but the link will be changed wherever to either a domain name or an IP address. This will de-obfuscate any obscure references so beloved by spammers. Unlike [AscToHtm], AscToRTF will only convert hyperlinks to a full URLs (i.e. those where a site name is supplied). If a URL like "\home\index.html" is detected it is left unconverted. This is because it is less likely that the relationship between source and target can be relied on. Usenet Newsgroup detection -------------------------- AscToRTF can convert any newsgroup names it spots into hyperlinks to those newsgroups. Because this is prone to error, AscToRTF currently only converts newsgroups in known USENET hierarchies such as rec.gardens by default. This can be overcome either by a) placing "news:" in front of the newsgroup name (e.g. news:this.is.a.newsgroup.honest) b) relaxing this condition via a document policy (see [[goto Only use known groups]]). c) specifying the newsgroup hierarchy as recognised via a policy (see [[goto Recognised USENET groups]]). E-mail address detection ------------------------ AscToRTF can convert any email addresses into hypertext mailto: links. As with [[goto URL detection]], the domain name is checked to see it falls into a recognised group. User-specified keywords ----------------------- AscToRTF can convert use-specified keywords into hyperlinks. The words or phrase to be converted must lie on a single line in the source document. Care should be taken to ensure keywords are unambiguous. Normally I mark my keywords in [] brackets if authoring for conversion by AscToRTF See the discussion in [[goto Using link dictionary files]]. $_$_HELP_CHAPTER 2,"Headings and section titles" $_$_HELP_SUBJECT "Introduction to detecting headings" Headings and section titles =========================== AscToRTF 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), AscToRTF will use the standard "Heading n" styles. In addition to this, AscToRTF will insert a named bookmark to allow hyperlink jumps to this point. These bookmarks are used for example in any cross-reference hyperlinks that AscToRTF generates, and also by any [[goto Pre-processor command: GOTO,GOTO]] tags. 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 ----------------------------- AscToRTF can treat wholly capitalised lines as headings. It also allows for such headings to be spread over more than one line. Underlined heading detection ---------------------------- AscToRTF 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 -------------------------- _New in version 2.0_ 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 markup, although it will still be added to, and accessible from any hyperlinked contents list you generate for the document. At present such headings are not auto-detected... you need to switch on the [[goto Expect Embedded headings]] policy. Key phrase headings ------------------- _New in version 2.0_ The program can now look for lines that start with particular words or phrases (such as "Chapter", "Part", Title") of your choice and treat these lines as headings. Previously this only worked in a limited way if the heading line was also *numbered* ("Chapter 1") etc. To use this feature, set the policy [[goto Heading Key phrases]] Numbered paragraph detection ---------------------------- Some types of documents use what look like section numbers to number paragraphs (e.g. legal documents, or sets of rules). AscToRTF can recognize this, and mark up such lines by placing the number in bold, and not using the "Heading n" style on the whole line. Mail and USENET headers ----------------------- Some documents, especially those that were originally email or USENET posts, come with header lines, usually in the form of a number of lines with a keyword followed by a colon and then some value. AscToRTF can recognize these (to a limited extent). Where these are detected the program will parse the header lines to extract the Subject, Author and Date of the article concerned. A heading containing this information will then be generated to replace all the unsightly header lines. $_$_HELP_CHAPTER 2,"Pre-formatted text, diagrams and tables" Pre-formatted text ================== The software can detect various forms of pre-formatted text. This is text laid out in such a way that the spacing used is critical. Spacing is not normally preserved in conversion to RTF, so the correct detection and handling of these special types of text is quite important. Types of text recognised include the following - [[goto Line detection,Lines]] - [[goto Form feed page markers]] - [[goto User defined pre-formatted text]] - [[goto Automatically detected pre-formatted text]] - [[goto Table detection,Tables]] - [[goto Code sample detection,Code samples]] - [[goto ASCII art and diagram detection,Diagrams and ASCII art]] - [[goto Text block detection,Text blocks]] - [[goto Other formatted text]] Line detection -------------- Lines are interpreted in context. If they appear to be underlining text, or part of some pre-formatted structure such as a table, then they are treated as such. Otherwise they become horizontal rules. An attempt is made to interpret half-lines etc as such, although the effect is only approximate. Form feed page markers ---------------------- Form feeds or page breaks become page breaks in the RTF User defined pre-formatted text ------------------------------- AscToRTF allows users to define their own regions of pre-formatted text, using the BEGIN_PRE and END_PRE pre-processor tags (see [[GOTO Using the pre-processor]]). Such areas are marked up in the "Preformatted" style (see "[[GOTO the use of RTF stylesheets]]"), which uses a non-proportional font to preserve the relative spacing. For example :- $_$_BEGIN_PRE The use of BEGIN_PRE and END_PRE preprocessor commands (see 7.1) in the text documents tells AscToHTM that this portion of the document has been formatted by the user and should be left unchanged. $_$_END_PRE $_$_HELP_CHAPTER 3,"Automatically detected pre-formatted text" $_$_HELP_SUBJECT "Introduction to detecting pre-formatted text" Automatically detected pre-formatted text ----------------------------------------- AscToRTF attempts to spot sections of preformatted text. This can vary from a single line (e.g. a line with a page number on the right-hand margin) to a complete table of data. Where such text is detected AscToRTF analyses the section to determine what type of pre-formatted text it is. Options include - Tables - Code samples - ASCII Art and diagrams - some other formatted text A number of policies allow you to control - whether or not the program looks for such text - how sensitivity it is to "pre-formatted" text - how inclined the program is to "extend" the region to adjacent lines - whether or not table generation should be attempted - various aspects of any table analysis that is carried out. See [[GOTO "Pre-formatted text"]] policies for full details. You can adjust the sensitivity of AscToRTF to pre-formatted text by setting the minimum number of lines required for a pre-formatted region using the [[goto Minimum size of automatic
 section]] policy.

RTF ignores all white space in the source document, thus any hand-crafted 
layout information would normally get lost.  When AscToRTF detects 
such regions it marks them up in fixed width font which tells RTF 
this region is pre-formatted.

When tables are detected, AscToRTF will attempt to generate the correct 
RTF table.

When AscToRTF gets the detection wrong you can use the AscToRTF 
[[goto Using the pre-processor,pre-processor]] to mark up regions of your document 
you wish preserved.


Table detection
...............
Tables are marked out by their use of white space, and a regular pattern
of gaps or vertical bars being spotted on each lines.  AscToRTF will
attempt to spot the table, its columns, its headings, its cell alignment
and entries that span multiple columns or rows.

Should AscToRTF wrongly detect the extent of a table, you can mark up
a section of text by using the [[goto Pre-processor command: TABLE,TABLE]] pre-processor 
markup (see the [Tag Manual]).  Alternatively you can try adding
blank lines before and after, as the analysis uses white space to
delimit tables.

You can alter the characteristics of all tables via the table policies
(see [[GOTO Formatting policies]]).

You can alter the characteristics of all or individual tables via the
table pre-processor commands (see [[goto Pre-processor command: TABLE,TABLE]]).

Or you can suppress the whole thing altogether via the 
[[goto Attempt TABLE generation]] policy

Tables will be marked up using the "Table" style.  See "[[GOTO the use of RTF stylesheets]]".

Code sample detection
.....................
AscToRTF attempts to recognize code fragments in technical documents.
The code is assumed to be "C++" or "Java"-like, and key indicators
are, for example, the presence of ";" characters on the end of lines.

Should AscToRTF wrongly detect the extent of a code fragment, you can
mark up a section of text by using the [[goto Pre-processor command: CODE,CODE]] pre-processor 
markup.

Or you can suppress the whole thing altogether via the policy
[[goto Expect code samples]].

Code samples will be marked up using the "Code" style. 
See "[[GOTO the use of RTF stylesheets]]".

ASCII art and diagram detection
...............................
AscToRTF attempts to recognize ASCII art and diagrams in documents.
Key indicators include large numbers of non-alphanumeric characters
and the use of white space.

However, some diagrams use the same mix of line and alphabetic
characters as tables, so the two sometimes get confused.

Should AscToRTF wrongly detect the extent or type of a diagram,
you can mark up a section of text by using the [[goto Pre-processor command: DIAGRAM,DIAGRAM]] 
pre-processor markup.

Diagrams are marked up using the "Diagram" style. 
See "[[GOTO the use of RTF stylesheets]]".

Text block detection
....................
_New in version 2.0_

If AscToRTF detects a block of text at a large indent, it will now
place that text in such a way as to preserve as faithfully as 
possible the original indent.


Other formatted text
....................
If AscToRTF detects formatted text, but decides that it is neither
table, code or art (and it knows what it likes), then the text may be
put out "as normal", but with the original line structure preserved.

In such regions other markup (such as bullets) may not be processed 
such as it would be elsewhere.


$_$_HELP_CHAPTER 2,"Adding features to the document"
Adding features to the document
===============================
As well as detection features present in the source text, the 
software allows you to add in features that you would expect 
in the output file that can't be inferred from the input

These include the following.

	- [[goto Adding a Document Title,Document title]]
	- [[goto Adding a contents list,A working contents list]]


Adding a Document Title
-----------------------
AscToRTF can calculate - or be told - the title of a document.  This
will be placed in document properties section in the header of 
each RTF file produced.

The Title is calculated as in the order shown below.  If the first	
algorithm returns a value, the subsequent ones are ignored.

1) If a [[goto Pre-processor command: TITLE,TITLE command]] is placed in the
   source text, that value is used

2) If the [[goto Document Details,Document title]] policy is set then this value
   is used.

3) Finally, if none of the above result in a title the text
   "Converted from " is used.


Adding a Contents list
----------------------
AscToRTF can detect the presence of a contents list in the original
document, or it can insert a field code that will generate a contents
list from the headings that it observes.  This is possible because
AscToRTF marks headings up in the Headings style.  
See [[goto The use of RTF stylesheets]]

This contents field added can be recalculated in Word by pressing F9.

There are a number of policies that give you control over how and 
where a contents list is generated (see [[goto contents policies]]).

_Contents lists placement_

By default the contents list will be placed at the top of the output
file.  You can cause contents lists to be placed wherever you want 
by using the CONTENTS_LIST preprocessor command (see [[goto pre-processor directives]]).  

_Contents list detection_
AscToRTF can detect contents lists in a number of ways

- By detecting "table of contents" "end contents" or something similar 
  in the text.

- By spotting the numbering sequence has been repeated twice.  AscToRTF 
  will assume the first set is the contents list.

- By spotting [[goto Using the pre-processor,pre-processor]] markup.

This is often a hit-and-miss procedure, and is liable to error.

Should the analysis fail, you can attempt to correct it via the 

[[goto contents policies,Contents lists]] policies.


$_$_HELP_CHAPTER 2,"AscToRTF's use of stylesheets"
$_$_HELP_SUBJECT "Stylesheets used by AscToRTF"
The use of RTF stylesheets
==========================
AscToRTF supports the use of stylesheets.  That is the marking up
of text in particular styles.  AscToRTF uses this to identify how
the text was analysed, thus headings acquire a "Headings" style, and
bulleted lists are marked up in the Bullet Style.

Initially most of these styles are the same, but if you use a word
processor that supports RTF stylesheets (such as Word), you'll be
able to globally change attributes line font face and colour.  For
example you could turn all code samples green by changing the attributes
of the code style.

Styles are implemented in a hierarchy, with style attributes being
inherited from their parents.  Later versions of AscToRTF may allow
style attributes to be selected before conversion.

The style hierarchy is as follows

$_$_BEGIN_DIAGRAM
      Normal 				(generic normal text style)
	|
    	+-- 1 Body 			(main body text)
    	|       |
    	|       +--- 11 ShortLine 	(short lines)
    	|       +--- 12 Bullet 		(bullets and numbered lists)
    	|       +--- 13 Quoted 		("quoted" text as found in emails)
    	|       +--- 14 Hanging 	(hanging paragraphs)
    	|       +--- 15 Definition 	(definitions)
    	|
    	+-- 2 Table			(Table text)
    	+-- 3 Preform			(preformatted text)
    	+-- 4 Diagram			(diagrams)
    	+-- 5 Code			(code samples)
    	|
	+-- 6 Heading			(generic heading style)
	|	|
	|	+--- 61 Heading1	(level 1 headings)
	|	+--- 62 Heading2	(level 2 headings)
	|	+--- 63 Heading3	(level 3 headings)
	|	+--- 64 Heading4	(level 4 headings)
	|	+--- 65 Heading5	(level 5 headings)
	|
	+-- 7 TOC  			(generic TOC style)
	|	|
	|       +--- 71 TOC1		(level 1 TOC entry)
	|       +--- 72 TOC2		(level 2 TOC entry)
	|       +--- 73 TOC3		(level 3 TOC entry)
	|       +--- 74 TOC4		(level 4 TOC entry)
	|       +--- 75 TOC5		(level 5 TOC entry)
	o
$_$_END_DIAGRAM

      The default implementations of these styles are as follows:-

      _Body_			Uses the user-supplied font.  Created 
      				justified text by default.

      _ShortLine_		Same as _Body_, but with a \par at the end 
            			of each line to preserve the original line structure.  
      				These paragraphs have zero spacing before
      				and after, to closely mimic the original text 
      				file structure.

      _Bullet_			Styling is the same as _Body_, but the bullet 
            			itself is output using a hanging indent with a 
      				tab after the bullet.

      _Quoted_			Text is placed in italics, and left justified.  
      				Each line is given a \par to preserve the original 
      				line structure.

      _Hanging_			The text is divided into two parts.  The first 
      				is placed on the left, and the "hanging" part is 
      				placed on the right, after a tab.  The position
       	     			of the tab stop is calculated according to 
      				the size of the text to be placed on the left.
      				Often text that AscToHTM would put in a table comes
      				out as a hanging list.

      _Definition_		Much like _Hanging_.  The definition term is on left, 
            			the rest is hung on the right after a tab.  Options 
      				exist to allow the definition term to be made bold.

      _Table_			The text is styled as in _Body_, but is placed into 
      				cells in a table.  Table analysis is complex, and 
            			deserves a document in its own right, but
      				in essence the text is placed in cells and 
      				aligned according to original placement and data 
      				type.  The whole process can sometimes go wrong.

      _Preformatted_		Preformatted text is output in a non-proportional font 
            			(usually Courier) with no spacing between lines and 
      				a \par on each line to preserve the line structure.  
      				A font size of 8pt is used as this best represents
      				80 characters across a page without wrapping.

      _Diagram_			Same as _Preformatted_.

      _Code_			Same as _Preformatted_.

      _Heading_			Heading itself is unused, but acts as a common parent 
      				for the actual styles "Heading 1", "Heading 2" etc.  
            			These are set to be the same as the Microsoft Word 
      				equivalents.

      _TOC_			The table of contents style TOC itself is unused, 
      				but acts as a common parent for the actual styles 
      				"TOC 1", "TOC 2" etc.  These are set to be the same 
            			as the Microsoft Word equivalents.



$_$_HELP_CHAPTER 1,"Using policy files"
Using policy files
******************
$_$_HELP_TOPIC_ID ID_POLICY_FILES
Document policies have two main uses; to correct any failure of 
analysis that AscToRTF makes, and to tell the program how to 
produce better RTF in ways that couldn't possibly be inferred 
from the original text.

Examples of the former may include specifying a nominal page 
width, and stating whether or not underlined section headings 
are expected etc.

Examples of the latter include adding colour and titles to 
the page, as well as requesting that a large document is split 
into several pages. 

$_$_SECTION MAKINGHTML
*Contents of this section*
$_$_CONTENTS_LIST 2,,2
$_$_SECTION MAKINGRTF
	[[goto analysis policies]]

	- [[goto General analysis policies,General Analysis]]
	- [[goto Headings Policies]]
	- [[goto bullet policies,Bullets]]
	- [[goto Pre-formatted text policies,Pre-formatted text]]
	- [[goto Table analysis policies,Table analysis]]

	[[goto output policies]]

	- [[goto File Structure policies,File generation]]

	- [[goto Document details]]
	- [[goto Formatting Policies,Formatting]]
	- [[goto RTF settings]]
	- [[goto Make Windows Help File policies,Make Windows Help File]]
	
	- [[goto Hyperlinks policies,Hyperlinks]]
	- [[goto Preprocessor policies,Preprocessor]]
	
	- [[goto Font policies,Fonts]]
	
	- [[goto Link Dictionary Edit Dialog,Link Dictionary]]
$_$_SECTION ALL

What are Policy files?
======================
$_$_HELP_TOPIC_ID ID_DEFINEPOLICYFILES
AscToRTF has a large number of options available to influence the 
analysis of your text files, and the output to RTF.  These options 
are called "policies" as they govern how the source file should 
be interpreted and converted.

Policies may be saved in text files, known as policy files.  These 
files have a ".pol" extension by default.  The policy files are 
usually updated by changing the policies and saving the changes 
in a new file.  Because they are text files you can also edit them 
directly, in a text editor.  The files have the format of one 
policy per line of

Text in the form

	PolicyText : 

The use of policy files allow a given set of options to be saved 
and reused for other conversions, or later conversions of the same file.
See [[goto Using policy files]] for more information.


$_$_HELP_CHAPTER 2,"Analysis policies"
$_$_HELP_SUBJECT "Introduction"
Analysis policies
=================
$_$_HELP_TOPIC_ID ID_CONV_POLICIES
Analysis policies are usually calculated by AscToRTF by making a 
first pass through your document.   The resulting policies are then 
used during the second, conversion pass to categorise all input 
lines so that they may be correctly converted to HTML.

You should only need to change these policies should the analysis fail.

	- [[goto 'What to look for' policies]]
	- [[goto General analysis policies,General Analysis]]
	- [[goto bullet policies,Bullets]]
	- [[goto File Structure policies,File generation]]
	- [[goto Headings Policies]]
	- [[goto Pre-formatted text policies,Pre-formatted text]]
	- [[goto Table analysis policies,Table analysis]]


$_$_HELP_CHAPTER 3,"What to look for" policies
$_$_HELP_SUBJECT "List of 'look for' policies"
'What to look for' policies
---------------------------
$_$_HELP_TOPIC_ID HIDD_LOOKFOR
These policies act as "broad stroke" policies enabling or disabling 
areas of functionality within the software by telling it what to look 
for and to try to detect.  

For example you can tell the program whether or not to bother looking 
for patterns of indentation, bullets, or numbered lists.  In many 
cases if you enable a policy you can further fine tune the conversion 
details on other policy sheets.

	- [[popup Look for indentation]]
	- [[popup Look for white space,Look for paragraphs]]
	- [[popup Look for short lines]]
	- [[popup Look for horizontal rules]]
	- [[popup Look for bullets and numbered lists]]
	- [[popup Look for definitions]]
	- [[popup Look for quoted lines]]
	- [[popup Look for emphasis]]
	- [[popup Look for underlined text]]
	- [[popup Look for mail and USENET headers]]
	- [[popup Look for character encoding]]
	- [[popup Look for preformatted text,Look for regions of preformatted text]]
	- [[popup Look for diagrams]]


Look for indentation
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_INDENTS
AscToRTF can attempt to detect the indentation pattern of your 
document and replicate it in the output file.  If you chose to 
disable this policy, all your text will be output with no 
indentations at all.

If the program is wrongly indenting your files, you can try 
adjusting the pattern of indentation on the 
[[goto General analysis policies,General Analysis]] tabbed policy sheet.

Look for white space
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_PARAS
By default AscToRTF will attempt to look for paragraphs in your 
source.  Usually this is signaled by a blank line between paragraphs, 
a leading indent on the first line of each paragraph, or (in 
extreme cases) a short line at the end of a paragraph.

If you don't want AscToRTF to detect paragraphs, disable this policy.

If AscToRTF is wrongly detecting paragraphs, try adjusting the 
paragraph analysis policies on the [[goto General analysis policies,General Analysis]]
tabbed policy sheet.

Look for short lines
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_SHORTLINES
By default AscToRTF will attempt to detect short lines and preserve 
their structure by adding a line break.  Disabling this will cause 
short lines to be merged into the surrounding paragraph's text.

If AscToRTF is wrongly handling your short lines, you can adjust 
the short line cutoff point or the page width (which is used in 
short line detection) in the Sizes section of the 
[[goto General analysis policies,General Analysis]] tabbed policy sheet.

Look for horizontal rules
.........................
$_$_HELP_TOPIC_ID ID_LOOKFOR_RULES
By default AscToRTF will treat a series of hyphens, minus signs, 
equal signs on the same line as a horizontal rule.  (On occasion it 
might be regarded as underlining a heading on the previous line).

You can disable this is you wish, or you can specify how many 
"line" characters it takes to make a horizontal rule.

Look for bullets and numbered lists
...................................
$_$_HELP_TOPIC_ID ID_LOOKFOR_BULLETS
By default AscToRTF will try to detect bullet points and numbered 
lists.  This can sometimes go wrong if you have lines that look to 
the program like bullet points.

You can disable this behaviour should you wish.  Alternatively you 
can fine tune the detection of bullets on the [[goto bullet policies,"bullet analysis"]] 
tabbed policy sheet.

Look for definitions
....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_DEFINITIONS
By default AscToRTF will try to detect definitions and notes, 
usually in the form of a single word and a hanging paragraph. 

This can often go wrong, so you can use this policy to disable 
this feature.

Look for quoted lines
.....................
$_$_HELP_TOPIC_ID ID_LOOKFOR_QUOTES
By default AscToRTF will try to identify "quoted" lines.  
Quoted lines are lines that have had a single character 
(often ">" or "!") inserted at the start.  This is common 
practice when quoting email in a reply.  AscToRTF places 
such text in italics.

You can disable this behaviour should you wish.

Look for emphasis
.................
*New in version 2.0*

AscToRTF will try to look for text that has been marked up
with underscores and asterisks to signify bold an italic text.
For example
$_$_CHANGE_POLICY look for emphasis : no
	*This is bold* and _this is italic_
$_$_CHANGE_POLICY look for emphasis : no
becomes
	*This is bold* and _this is italic_


Look for underlined text
........................
*New in version 2.0*

AscToRTF will try to detect where a line of text has been "underlined" 
by following it by a same length row of dashes, hyphens, equal signs
etc.  This text will then be regarded as a candidate for being an
underlined heading or - if those are not allowed - underlined text.

If you have tables and reports, you may want to switch this policy
off since the line at the end of a table may appear to under- or
over-line the last line of text in the table.

Look for mail and USENET headers
................................
$_$_HELP_TOPIC_ID ID_LOOKFOR_MAILHEAD

AscToRTF will try to look for email and USENET headers.  Where
these are recognised they can be simplified so that only
the To, Form and Subject lines are shown in the output.

You can disable this behaviour should you wish.

Look for character encoding
..............................
Specifies whether or not the software should attempt to detect alternative
character sets, such as those used for languages such as Greek, Turkish,
Chinese etc.

The software does this by doing a statistical analysis on the characters used
in the source file.  This process isn't perfect, and when it fails you will
need to manually set the correct character set using the [[GOTO Character encoding]]
policy.

If you find the program is wrongly detecting the character encoding, disable
this policy and/or manually set it using the [[GOTO Character encoding]] policy

Note: Not all character sets are supported by RTF.

Look for preformatted text
..........................
$_$_HELP_TOPIC_ID ID_LOOKFOR_PREFORM
By default AscToRTF will try to identify regions of preformatted 
text.  Once identified AscToRTF will try to decide if it's a 
diagram, table or some other form of preformatted text.  If it thinks 
it's a table it will attempt to place the text in an appropriate 
table structure.

You can disable the search for preformatted text, or if you allow 
preformatted text, disable table generation.  (This may be 
appropriate if you have a large number of ASCII diagrams in 
your text).

The search for preformatted text can be refined via the 
[[goto Pre-formatted text policies,Pre-formatted text]] and [[goto Table analysis policies,Table analysis]] 
tabbed policy sheets.

The output of tables can be fine-tuned via the 
output policy [[goto Formatting policies,Formatting]] tabbed policy sheet.

Look for diagrams
.................
Specifies whether or not regions of preformatted text that are detected
should be considered as candidate diagrams.  Text that contains numbers
of characters such as "|", "-", ">" and "<" may be considered to be
an ASCII diagram.

If you find the program is wrongly treating tables as diagrams
then disable this policy.


$_$_HELP_CHAPTER 3,"General analysis policies"
General analysis policies
-------------------------
$_$_HELP_TOPIC_ID HIDD_ANALYSIS
These policies aid AscToRTF's analysis by describing in detail what 
the contents of the document being converted are

*Sizes*

	- [[popup Page Width]]
	- [[popup TAB Size]]
	- [[popup Short line length]]
	- [[popup Min Chapter Size]]

*Paragraphs*

	- [[popup Blank lines between paragraphs]]
	- [[popup New paragraph offset]]

*Definitions*

	- [[popup Search for definitions,Search for definitions in source text]]
	- [[popup hanging indent position(s),Definition paragraph indent levels]]
	- [[popup recognize hyphen characters]]
	- [[popup recognize colon characters]]
	- [[popup Other definition characters]]

*Layout*

	- [[popup indent position(s), Indentation levels]]


Page Width
..........
$_$_HELP_TOPIC_ID ID_PAGEWIDTH
This indicates the width (in characters) of your nominal output 
page.  This width is calculated from the observed line lengths 
in the original document.

This width is used in short line calculation, and determining 
whether a given line contains a definition term or not 
(definition character near the start of the line).

In documents that contain line feeds this should be automatically 
detected.

In other documents you may need to set this manually.

TAB size
........
$_$_HELP_TOPIC_ID ID_TABSIZE
This indicates the size (in characters) of your tabs.  AscToRTF 
converts all tabs to spaces on conversion before analysis.  By 
default a tab size of 8 characters is assumed.

The tab size can influence the analysis of paragraph indentations 
and other layout.  Provided they are used consistently there 
shouldn't be a problem.  However where tabs and spaces are used 
in combination, mistakes can arise.  

This is particularly true in tables of data.  AscToRTF does not 
expect tab-separated table cells, instead converting the tabs 
to spaces and analysing the results.

If your source document has been created with an editor with a 
different tab size, you should change this value should you 
start to experience strange layout conversion problems.

Short Line Length
.................
$_$_HELP_TOPIC_ID ID_SHORTLINE
This policy is used to determine what is a "short line".  Short 
lines are treated specially by AscToRTF by adding a paragraph
marker on the end.  They can also be used to detect ends of 
paragraphs in those documents that don't have blank lines between 
paragraphs.

Normally AscToRTF will determine whether or not a line is short 
by comparing it to the page width, given the current context.

The default value is 0 characters (indicating a comparison to 
Page Width should be used).  Set this to any value you like.  
A value of 80 is likely to make every line in your original 
document have a paragraph marker on the end.

Min Chapter Size
................
$_$_HELP_TOPIC_ID ID_MINCHAPTER
This policy tells AscToRTF what the smallest chapter size may be.  
This is used when trying to determine if a numbered line is a 
chapter heading.  AscToRTF tries to avoid treating numbered lists 
as a series of small chapters using this policy.

The default value is 8 lines.  Change this only if you suspect 
small chapters are being ignored, or large list items are being 
treated as chapter headings.


Blank Lines between paragraphs
..............................
$_$_HELP_TOPIC_ID ID_BLANKLINES

AscToRTF can detect whether or not it should expect blank lines 
between paragraphs.  Documents without blank lines between 
paragraphs will be harder to convert, and errors are more likely.  
Unfortunately text documents exported from Word for Windows 
often have this property.

Where there are no blank lines, AscToRTF relies of spotting the 
last line of a paragraph (usually shorter), and (in some 
documents) the presence of a [[popup New paragraph offset,"hanging indent"]] at the 
start of each new paragraph. 

This should be automatically detected.

New Paragraph Offset
....................
$_$_HELP_TOPIC_ID ID_NEWPARA
Some documents start the first line of a new paragraph with an 
offset of a number of characters.  This is especially true in text 
files saved from Word for Windows documents.

AscToRTF can sometimes confuse such paragraphs as being two different 
levels of indentation.  Use this policy to eliminate such confusion.

This should be automatically detected


Search for definitions
......................
$_$_HELP_TOPIC_ID ID_ALLOWDEFINITIONS
This policy can be used to disable the search for definitions.  
Sometimes this leads to unexpected results with text that is 
not part of a definition being treated as such.  In such cases 
you can adjust the definition policies, but if this still 
fails, use this to disable the search completely.

See also [[popup one-line definitions]] and [[popup definition paragraphs]]

Hanging indent position(s)
..........................
$_$_HELP_TOPIC_ID ID_DEFNINDENTS

This policy identifies the indentations used for the follow-on 
text in [[popup definition paragraphs]].  These indentation 
levels need not be the same as the indentation levels used for 
normal text, though of course often they are.

This should be detected automatically, but if your document has 
only a few examples it's possible AscToRTF will ignore them.  
In such cases you may need to set this policy manually.

_Note, this policy appears on-screen as "Definition paragraph indent levels"_

Recognize hyphen characters
...........................
$_$_HELP_TOPIC_ID ID_HYPHENDEFNS
This policy specifies whether or not hyphen (-) characters are 
used in [[popup one-line definitions]].

If the hyphen character only occurs in definitions, then set the 
nearby always flag, otherwise AscToRTF will have to guess whether 
a particular character is part of a definition or not.  This is 
sometimes a source of conversion errors.

If this policy is selected, it will result in a suitable "Definition Char" 
line being added to the policy file.

This should be detected automatically.

Recognize colon characters
..........................
$_$_HELP_TOPIC_ID ID_COLONDEFNS
This policy specifies whether or not colon (:) characters are 
used in [[popup one-line definitions]].

If the colon character only occurs in definitions, then set the 
nearby always flag, otherwise AscToRTF will have to guess 
whether a particular character is part of a definition or not.  
This is sometimes a source of conversion errors.

If this policy is selected, it will result in a suitable "Definition Char" 
line being added to the policy file.

This should be detected automatically.

Other definition Characters
...........................
$_$_HELP_TOPIC_ID ID_DEFNCHARS
This policy specifies which other characters are used in 
[[popup one-line definitions]].

This may be detected automatically, but more likely you'll need 
to specify it yourself.

Each character selected as a potential delimiter will result in a
"Definition Char" line being added to the policy file.

Indent position(s)
..................
$_$_HELP_TOPIC_ID ID_INDENTS
AscToRTF recognises multiple levels of indentation.  This policy 
shows the character levels at which indentation has been detected.

AscToRTF converts all tab characters into multiple spaces in input.  
These indentation positions are the positions that result after 
that conversion.  Depending on your tab settings these might not 
be exactly the positions you would expect.

Normally these levels are correctly detected automatically, but 
should you wish to set them manually you may need to experiment 
slightly to see how AscToRTF has handled your tabs.



Bullet policies
---------------
$_$_HELP_TOPIC_ID HIDD_BULLETS
AscToRTF should be able to detect the use of bullets on a 
reasonably sized document.  These policies describe the type 
of bullets expected.

	- [[popup Look for bullets, Automatically detect bullets and numbered lists]]


*Expected Bullet types*

	- [[popup expect numbered bullets, numbered bullets]]
	- [[popup expect alphabetic bullets, alphabetic bullets]]
	- [[popup expect roman numeral bullets, roman numeral bullets]]


*Bullet characters*

	- [[popup "Recognise '-' as a bullet",recognize hyphen character as a bullet point]]
	- [[popup "Recognise 'o' as a bullet",'recognize an "o" character as a bullet point']]
	- [[popup Other bullet point characters]]


Look for bullets
................
$_$_HELP_TOPIC_ID ID_AUTODETECT_BULLETS
This policy states whether or not the program should attempt to 
automatically detect bullets and numbered lists.  This should 
normally be left on unless your document has no such features, 
but the program (wrongly) thinks it has.

This policy appears on the Bullets dialog as "Automatically detect 
bullets and numbered lists", but is identical to the "Look for bullets"
policy on the [[goto 'What to look for' policies]] tabbed property sheet.

Expect Numbered bullets
.......................
$_$_HELP_TOPIC_ID ID_NUMBERBULLETS
This policy states whether or not numbered bullet points are 
expected.  The numbered bullets can be followed by any 
punctuation, thus 1., 2) and (3) will all be recognised, but 
RTF will not necessarily support this in the markup produced.

This should be automatically detected.

Expect alphabetic bullets
.........................
$_$_HELP_TOPIC_ID ID_ALPHABULLETS
This policy states whether or not alphabetic bullet points are 
expected.  The numbered bullets can be followed by any punctuation, 
thus a., b) and (c) will all be recognised, but RTF will not 
necessarily support this in the markup produced.

Both upper and lower case bullets are recognised (and supported 
in the markup).

This should be automatically detected


Expect roman numeral bullets
............................
$_$_HELP_TOPIC_ID ID_ROMANBULLETS
This policy states whether or not roman numeral bullet points 
are expected.  The numbered bullets can be followed by any 
punctuation, thus i., ii) and (iii) will all be recognised, but 
RTF will not necessarily support this in the markup produced.

Both upper and lower case bullets are recognised (and supported 
in the markup), although the range of roman numeral values 
supported is limited.

This should be automatically detected.

Recognise 'o' as a bullet
.........................
$_$_HELP_TOPIC_ID ID_MINUSBULLETS
This policy states whether or not bullet points starting with 
the hyphen character '-' are expected.

This policy appear on-screen as "Recognize hyphen character as a bullet point"

This should be automatically detected.

Recognise '-' as a bullet
.........................
$_$_HELP_TOPIC_ID ID_OBULLETS
This policy states whether or not bullet points starting with 
the lower case 'o' are expected.

This policy appear on-screen as "Recognize 'o' character as a bullet point"

This should be automatically detected.

Other bullet point characters
.............................
$_$_HELP_TOPIC_ID ID_OTHERBULLETS
This policy lists any other characters that are to be recognised 
as bullet characters.

Each bullet character entered will appear in the policy file as
it's own "Bullet Char" line.

This should be automatically detected, but may sometimes need to 
be manually entered.


$_$_HELP_CHAPTER 3,"Contents policies"
Contents policies
-----------------
$_$_HELP_TOPIC_ID HIDD_CONTENTS

This dialog shows both analysis and output policies connected with contents list detection and generation.

	*Analysis*
		- [[popup Expect contents list]]
		
$_$_BEGIN_IGNORE
		
!	*Output*
!		- [[popup Generate a contents list]]
!	
!	See the discussion on contents list generation in the [[goto Documentation available]]
$_$_END_IGNORE

Expect contents list
....................
$_$_HELP_TOPIC_ID ID_EXPECTCONTENTS
This policy specifies whether or not the document already 
contains a contents list.  If it does, AscToRTF will attempt 
to convert the existing list into a series of hyperlinks.

This should be detected automatically, but occasionally you 
will need to set this policy manually.

See the discussion on contents list generation in the 
[[goto Documentation available]]

$_$_BEGIN_IGNORE	
!	Generate a contents list
!	........................
!	$_$_HELP_TOPIC_ID ID_MAKECONTENTS
!	This policy specifies whether or not AscToRTF should generate a 
!	contents list.  This lost will be generated from either an 
!	existing list in the source documents, or from the observed headings.
!	
!	A link to "contents list" will be added to the main RTF file.
!	
!	See the discussion on contents list generation in the 
!	[[goto Documentation available]]
!	
$_$_END_IGNORE

$_$_HELP_CHAPTER 3,"File Structure policies"
File Structure policies
-----------------------
$_$_HELP_TOPIC_ID HIDD_FILESTRUCT
These policies aid AscToRTF's analysis by describing some of the 
file structure that would affect the analysis.

	- [[popup Keep it simple, Expect only a simple layout]]


*Expected File contents*
	- [[popup Expect Code samples,'Expect "C"-code samples']]
	- [[popup Input file contains DOS characters, Contains DOS characters]]
	- [[popup Input file contains PCL codes, Contains PCL printer codes]]
	- [[popup Input file contains Japanese characters, Contains non-European (e.g. Japanese) characters]]
	- [[popup Input file contains MIME encoding, Contains mime-encoded quotable characters]]
	- [[popup Input file has change bars, File has change bars]]
	- [[popup Input file has page markers, File has Page markers]]
	- [[popup Page marker size (in lines)]]


*Text Attributes*
	- [[popup Text justification]]
	- [[popup Input file is double spaced, File is double spaced]]


*Text to ignore*
        - [[popup Lines to ignore at start of file, Number of lines to ignore at start of document]]
        - [[popup Lines to ignore at end of file, Number of lines to ignore at end of document]]

Keep it simple
..............
$_$_HELP_TOPIC_ID ID_SIMPLE
AscToRTF puts a lot of effort into detecting overall structure 
such as headings etc.

In documents that don't have any such structure, AscToRTF is 
liable to convert any line with a number at the start into a 
heading.

To prevent this, you can mark the document as simple, that is 
with no global structure.  In a simple document AscToRTF will 
attempt far less analysis.

This policy appears on-screen as "Expect only a simple layout".

AscToRTF attempts to automatically identify simple documents,
but you may still need to set this policy manually.

Expect Code samples
...................
$_$_HELP_TOPIC_ID ID_EXPECTCODE
AscToRTF can markup C-like code fragments in 
...
tags to preserve the layout and readability of the quoted code. This may be automatically detected, but occasionally needs to be manually corrected. Input file contains DOS characters .................................. $_$_HELP_TOPIC_ID ID_DOSCHARS AscToRTF can convert files that use the DOS (OEM) character set. By default the file is assumed to be in the ANSI character set, but some files may have originated under DOS. This may be automatically detected, but usually needs to be manually set. Input file contains PCL codes ............................. $_$_HELP_TOPIC_ID ID_PCL_CODES _New in version 2.0_ Indicates that the input file contains PCL printer codes. When set, the program will make whatever sensible use it can of these codes, otherwise they will be removed. Please note that the PCL printer codes offer a rich command language that may be used to drive graphical printers. As such the emulation possibilities in a *text* converter are limited, and it is quite likely that files that make heavy use of such codes will fail dramatically to convert. That said, those codes that are not recognised will be eliminated from the output. Input file contains Japanese characters ....................................... $_$_HELP_TOPIC_ID ID_JAPANCHARS *** not implemented yet *** Files using non-ASCII character sets (Japanese, Korean etc) will be incorrectly converted. This may be fixed (as far as possible) in later versions. Appears on-screen as "Contains non-European (e.g. Japanese) characters" Input file contains MIME encoding ................................. $_$_HELP_TOPIC_ID ID_MIMECHARS AscToRTF can convert mime-encoded quotable characters. These will usually appear in files that were originally part of an email message. Such files use the "=" character to escape special characters. So for example "=20" should be interpreted as a space. This appears on-screen as "Contains mime-encoded quotable characters" This may be automatically detected in files where the "=" is used to break up long lines, but more usually you will need to manually set this. Input file has change bars .......................... $_$_HELP_TOPIC_ID ID_CHANGEBARS AscToRTF can strip out change bars in documents that contain them. Change bars are usually a vertical bar '|' placed in the leftmost or rightmost column. Currently this is not automatically detected, and so will need to be manually switched on. Input file has page markers ........................... $_$_HELP_TOPIC_ID ID_PAGEMARKER AscToRTF has a limited ability to remove page markers. These are normally a few lines following a form feed (FF) character, containing page numbers etc. This will commonly occur with files generated from older software packages. Page marker size (in lines) ........................... $_$_HELP_TOPIC_ID ID_PAGE_MARKERSIZE The number of lines after each form feed (FF) that should be ignored. These lines will not be copied to the output. Text Justification .................. $_$_HELP_TOPIC_ID ID_TEXTJUSTIFICATION AscToRTF recognises documents that are left justified (default), right justified, centred or both left and right justified (confusingly known as "justified"). The program cannot currently mark up the text in a matching style, but this policy is important in the analysis. For example "justified" documents are padded with extra white space which could be interpreted as pre-formatted text where the document not recognised as being justified. Normally this policy is correctly detected automatically. Input file is double spaced ........................... $_$_HELP_TOPIC_ID ID_DOUBLESPACED AscToRTF will normally treat a blank line as a break between paragraphs. Some files have extra CR/LF characters (usually if they've come from a different computer, or from a printer package). In such cases AscToRTF will see every second line as blank, and this will affect the analysis, usually by turning each line of data into a separate paragraph. If you have such a file, use this policy to mark the file as double spaced to get better results. Lines to ignore at start of file ................................ $_$_HELP_TOPIC_ID ID_IGNORE_AT_START _New in version 2.0_ This specifies how many lines from the input files should be ignored at the start of the file. These lines will be discarded from the output. This can be useful when converting file copied from a news feed or whatever that adds a small data header to the file. Lines to ignore at end of file .............................. $_$_HELP_TOPIC_ID ID_IGNORE_AT_END _New in version 2.0_ This specifies how many lines from the input files should be ignored at the end of the file. Up to 40 lines may be ignored in this way. These lines will be discarded from the output. This can be useful when converting file copied from a news feed or whatever that adds a small data footer to the file. $_$_HELP_CHAPTER 3,"Headings policies" Headings policies ----------------- $_$_HELP_TOPIC_ID HIDD_HEADINGS These policies determine the headings structure that the document is expected to have. Normally these are calculated correctly by AscToRTF, but due to the complexity of heading detection, you may sometimes need to correct the analysis. At the top of the dialog you can specify what type of headings you expect to see. Any combination is allowed, although usually documents use just one type of heading. - [[popup Expect Numbered headings]] - [[popup Expect Underlined headings]] - [[popup Expect Capitalised headings]] - [[popup Expect Embedded headings]] - [[popup Heading Key phrases]] - [[popup Use first line as heading]] - [[popup Center first heading]] - [[popup Check indentation for consistency, Check indentations of headings are consistent]] If numbered headings are expected, it may be possible to expect headings at multiple levels, and to also expect a contents list. Each level of heading will have it's own set of policies which are shown on this dialog. The policies are shown in text form, but are edited via [[goto the heading details dialog]] Note: This area of functionality is continually under review. See also the discussion in detecting [[goto headings and section titles]]. Expect numbered headings ........................ $_$_HELP_TOPIC_ID ID_NUMBERED_HEADINGS This policy specifies whether or not numbered headings are expected in the document. Numbered headings may be found at multiple levels, and their details may be edited via [[goto The heading details dialog]] This should be calculated correctly by AscToRTF. But is prone to error, getting confused by numbered bullets and the like. In such cases you may need to set this policy manually. Expect underlined headings .......................... $_$_HELP_TOPIC_ID ID_UNDERLINED_HEADINGS This policy specifies whether or not underlined headings are expected. Note, where the headings themselves are numbered, the underlining will be taken into account, and you should set the [[popup expect numbered headings]] policy instead. AscToRTF uses the character in the underlining to determine the heading level, thus text underlined with equals signs is given prominence over text with single underline characters such as minus signs, tildes or underscores. Expect capitalised headings ........................... $_$_HELP_TOPIC_ID ID_CAP_HEADINGS This policy specifies whether or not CAPITALISED headings are expected. Note, where the headings themselves are numbered, this policy need not be set, and instead you should set the [[popup expect numbered headings]] policy instead. Expect Embedded headings ........................ $_$_HELP_TOPIC_ID ID_EMBEDDED_HEADINGS _New in version 2.0_ This policy specifies whether or not "embedded" headings are expected, i.e.. the heading is "embedded" in the first paragraph. Such headings are expected to be a complete sentence or phrase in UPPER CASE at the start of a paragraph. At present such headings are not auto-detected... you need to switch this policy. Heading Key phrases ................... $_$_HELP_TOPIC_ID ID_KEYPHRASE_HEADINGS _New in version 2.0_ If specified, then any line that begins with one of the key phrases will be regarded as a heading. The syntax is
,
... where each set of details is
= , [] and = [|] That is, each set of
can optionally specify a . If omitted this will default to 1,2,3 for the first, second, third set of details etc. Note, this is a *logical* heading level, and will be apparent in the contents list. Each set of
must supply a set of , and each set of phrases would must have at least one phrase with extra phrases added if wanted, separated by vertical bars. So for example Part, Chapter, Section would treat lines beginning with the words "Part", "Chapter" and "Section" as level 1,2, and 3 headings. The key phrases are case-sensitive in order to reduce the likelihood of false matches with lines that just happen to have these phrases at the start of the line. So PART|Part, Chapter, Section Would allow either "PART" or "Part" to be matched. "PART|Part,1" , "Chapter,2" , "Section,2" Would make lines beginning with "Part" level-1 headings, while both "Chapter" and "Section" would become level 2. This would be the same as "PART|Part,1" , "Chapter|Section,2" Note, spaces may form part of a match phrase, but because of their use in the tag syntax commands and vertical bars may not. If false matches occur, (e.g. the word "Part" appears in the body of the text) edit the source text so that the offending word is no longer at the start of the line. Use first line as heading ......................... *New in version 2.0* When this option is selected, the first line in the document will be treated as a heading. This can be a useful option to select when the first line of your document is a document title line, but doesn't conform to the headings style used in the rest of the document. See also [[goto use first line as title]] Center first heading .................... *New in version 2.0* When this option is selected, the first heading in the document is centred. This may be an appropriate choice when the first heading is in fact to be treated as a document title. See also [[goto use first line as heading]] Check indentation for consistency ................................. $_$_HELP_TOPIC_ID ID_HEADINDENTS The program performs a number of consistency checks when detecting headings. Amongst these is a check that all headings of the same type occur at the same indentation. This check can help distinguish between numbered headings and numbered lists. However, if you have numbered headings that are different indentations - e.g. because they are centred on the page - then this check will cause them to be rejected as headings. In such cases you can manually disable this check. This policy appears on-screen as "Check indentations of headings are consistent" The heading details dialog .......................... $_$_HELP_TOPIC_ID HIDD_HEADDTLS This dialog is reached through one of the edit buttons on the main [[goto Headings Policies]] dialog. This allows you to edit details of a particular type or level of heading. *Position of section number on the line* - [[popup Indentation of heading lines]] - [[popup Heading prefix words]] *Section number formatting* - [[popup Heading numbering scheme]] - [[popup Heading separator characters]] - [[popup Heading trailing letters]] *Bracketing* - [[popup Heading bracket characters]] Indentation of heading lines ............................ $_$_HELP_TOPIC_ID ID_HEAD_INDENT AscToRTF uses checks on indentation levels to reject lines with numbers on that could be confused with headers. This is the indentation level (in characters) that heading of this types are expected to be found at. Heading prefix words .................... $_$_HELP_TOPIC_ID ID_HEAD_PREFIX Some documents put words like "chapter", "subject" and "section" in front of the section number. These are known as prefix words. Heading numbering scheme ........................ $_$_HELP_TOPIC_ID ID_HEAD_NUMBERTYPE This is the numbering scheme expected for headings at this level. At present AscToRTF can't cope with mixed types like "II-2.b". This may be addressed in later versions. Heading separator characters ............................ $_$_HELP_TOPIC_ID ID_HEAD_SEPARATOR This shows the separator expected between parts of the heading number. *** Not currently supported *** Heading trailing letters ........................ $_$_HELP_TOPIC_ID ID_HEAD_TRAILALPHA This shows whether we expect trailing letters after the section number, as in "1.1b". *** Not currently supported *** Heading bracket characters .......................... $_$_HELP_TOPIC_ID ID_HEAD_BRACKETS This shows what bracket characters (if any) we expect before and after the section number as in "[2.2]" or "3.2.1)". *** Not currently supported *** Pre-formatted text policies ........................... $_$_HELP_TOPIC_ID HIDD_PREFORMAT These policies specify how AscToRTF detects pre-formatted text. Detecting pre-formatted regions - [[popup Minimum size of automatic
 section]]

See the section on [[goto pre-formatted text]] for more details.

Minimum size of automatic 
 section
.......................................
$_$_HELP_TOPIC_ID ID_MINPRESIZE
This policy specifies the minimum number of consecutive 
pre-formatted lines that must be detected before the text is 
placed in fixed width font.

AscToRTF detects heavily formatted lines, and then looks at 
their neighbours to see if they too could be part of a 
pre-formatted text.

Once a group of lines is identifies, it will only be marked 
up as pre-formatted if the minimum is exceeded.

The default value is 0.  Set this value larger if AscToRTF is 
marking text as pre-formatted when it shouldn't do.

Note: 	The 
 is a reference to the shared ancestry of this 
software with the text to HTML converter from which it evolved.

$_$_HELP_CHAPTER 3,"Table analysis policies"
Table analysis policies
-----------------------
$_$_HELP_TOPIC_ID HIDD_TABANAL
These policies specify how AscToRTF detects possible tables and 
analyses the data in them into columns and rows.

	- [[popup Attempt TABLE generation]]

*Detection*

	- [[popup Table extending factor, Extend preformatted regions]]

*Analysing rows*

	- [[popup Could be blank line separated,Could table have blank lines between rows]]
	
*Analysing columns*

	- [[popup Default table layout, Table Layout]]
	- [[popup Expect sparse tables,Is the table expected to have sparse columns]]
	- [[popup Ignore table header during analysis,Ignore table header when analysing columns]]
	- [[popup Column merging factor, Merge together "poor" columns]]
	- [[popup Minimum TABLE column separation, Minimum number of spaces between table columns]]

See the section on [[goto pre-formatted text]] for more details.


Attempt TABLE generation
........................
$_$_HELP_TOPIC_ID ID_ATTEMPT_TABLE
This policy specifies whether or not you want RTF table 
generation attempted for regions of apparently pre-formatted 
text.  AscToRTF will attempt to analyse such regions, preferring 
to fit them into a RTF table.  However, if this is not possible, 
or if AscToRTF decides the pre-formatted region is something 
else (like a diagram or a piece of code) then a RTF table will 
not be generated.

Disabling this policy tells AscToRTF not to attempt this 
analysis, usually leading to pre-formatted text being placed 
in simple fixed width font markup instead.

Table extending factor
......................
$_$_HELP_TOPIC_ID ID_EXTEND_TABLE
When the program encounters a strongly formatted line, it examines 
the adjacent lines to see if they too could form part of the 
same preformatted region.

This policy specifies the extend to which strongly preformatted 
lines should be used to "extend" to include adjacent lines as 
part of the same preformatted regions.  If set to 10, then all 
adjacent lines up to the next page break or section heading will 
be treated as part of the same region.  When set to 1 only those 
lines that are clearly heavily formatted themselves will be 
included.

This policy appears on-screen as "Extend preformatted regions"


Could be blank line separated
.............................
*New in version 2.0*

This option specifies whether or not tables are expected to have blank
lines between rows.  If they are, the software will be more likely to merge
the text for adjacent source lines into a single row in the output table.


Default Table Layout
....................
*New in version 2.0*

This option allows you to specify the default table layout for *all*
tables in the document.  The layout specifies the number of columns
and their end positions.  

This is the default layout and will normally be applied  to *all*
tables the document.  If a document has multiple tables you are
better off either using the preprocessor to mark up the source text
and supplying TABLE_LAYOUT commands, or supplying a "Layout" component
in a _Table Definition File_.

The format of the *Table Layout* policy is the same as that described in the
discussion of the [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] pre-processor
command.

See also [[goto TDF line: Layout]]


Expect sparse tables
....................
$_$_HELP_TOPIC_ID ID_TABLE_SPARSE
This policy is used to tell AscToRTF that you expect your tables 
to be quite sparse in places.  This can affect AscToRTF's analysis, 
as the algorithms are liable to merge "empty" columns with their 
less empty neighbours. 

Enabling this policy will usually result in your tables having 
more, emptier, columns.  

See also the [[popup Pre-processor command: TABLE_MAY_BE_SPARSE]].

Ignore table header during analysis
...................................
$_$_HELP_TOPIC_ID ID_IGNORE_HEADER
This policy specifies that the table header should be ignored when 
analysing the column structure of the table.

In some tables (usually "reports") the header can be quite complex, 
with titles spanning multiple columns, whereas the body of the 
table is much more structured.

In such cases including the table header in the analysis can lead 
to errors, so enabling this policy can simplify the analysis giving 
better chances of success.

This policy appears on-screen as "Ignore table header when analysing columns"


Column merging factor
.....................
$_$_HELP_TOPIC_ID ID_MERGE_POOR
Once the program has detected the column layout of a table, it 
reviews how well the data can be fitted into these columns.  If 
too many cells in a column are empty, or if too many cells 
"span" multiple columns, then the columns are deemed to be 
"poor", and may be merged together to form fewer, wider columns.

This factor determines the extent to which columns should be merged. 
A value of 10 means columns should be merged together whenever 
there is any doubt.  Use this if you are getting too many columns.  
A value of 1 means columns should never be merged. Use this if 
you are getting too few columns.

This policy appears on-screen as "Merge together "poor" columns".

Note, this policy can't guarantee you will the correct column 
structure, but it does give you a chance to influence the logic.

Minimum TABLE column separation
...............................
$_$_HELP_TOPIC_ID ID_MIN_TABLE_SEP
This policy specifies the minimum number of spaces that should be 
interpreted as a gap between columns in a potential table.  The 
default value is 1, but this value can sometimes lead to too many
columns, especially in small tables.  Larger values may lead to 
columns being merged together.

This policy appears on-screen as "Minimum number of spaces between table columns"

$_$_HELP_CHAPTER 2,"Output policies"
$_$_HELP_SUBJECT "Introduction"
Output policies
===============
$_$_HELP_TOPIC_ID ID_OUTPUT_POLICIES
These policies are used to control the output to RTF.  Generally 
these policies allow you to decide how the resulting RTF should 
look in a manner that cannot be inferred from the original document.

- [[goto File Structure policies,File generation]]

- [[goto Document details]]
- [[goto Formatting policies,Formatting]]
- [[goto RTF settings]]
- [[goto Make Windows Help file policies,Make Windows Help File]]

- [[goto Hyperlinks policies,Hyperlinks]]
- [[goto Preprocessor policies,Preprocessor]]

- [[goto Font policies,Fonts]]

- [[goto Link Dictionary Edit Dialog,Link Dictionary]]


$_$_HELP_CHAPTER 3,"File generating policies"
File generating policies
------------------------
$_$_HELP_TOPIC_ID HIDD_FILESPLIT
$_$_HELP_TOPIC_ID HIDD_FILESPLIT_RTF
_Line and file structures_
	- [[popup Preserve file structure using 
]]
	- [[popup Preserve line structure]]
	- [[popup Treat each line as a paragraph]]

_Diagnostics Files_
	- [[popup Generate diagnostics files, Generate log files]]
	- [[popup Generate sample policy file]]


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