$_$_TITLE Documentation for the AscToHTM conversion utility $_$_DESCRIPTION AscToHTM is a utility for converting plain text (ASCII) into HTML files. $_$_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 AscToHTM" AscToHTM Help Index ******************* $_$_HELP_TOPIC_ID HIDD_A2HDLG_DIALOG AscToHTM is a utility designed to convert plain text files into HTML pages. The program can be used to convert legacy text files to HTML as one-off conversions, or to help you author sets of HTML pages in text. 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 HTML generated by the program can be configured 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. This document describes AscToHTM 5.0, released in November 2004. The HTML version of this document has - of course - been produced using AscToHTM itself. No post-processing has been done to the HTML pages produced. The contents list, the navigation bar and all the hyperlinks have been generated from a single [[SOURCE_FILE]] and a number of configuration files. $_$_SECTION MAKINGRTFHELP There's a [[goto complete contents list for this document]] $_$_SECTION ALL 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. $_$_CONTENTS_LIST 2 $_$_HELP_CHAPTER 1,"Introduction" $_$_HELP_SUBJECT Overview Introduction ************ AscToHTM is an ASCII to HTML conversion tool. It has, of course, been used to generate the HTML version of this document from the text file [[source_file]]. The HTML version of this document is presented "as is". That is, *no post-production of the HTML has occurred*. This should give you a flavour of what AscToHTM is capable of. Any RTF version of this document will have been made by [AscToRTF], the sister product that shares the same text analysis engine. The WinHelp file that comes with the Windows version was also converted by [AscToRTF]. AscToHTM is made available for download via the Internet from [download location]. $_$_HELP_CHAPTER 2,"Expected uses of AscToHTM" Expected uses of AscToHTM ========================= AscToHTM can be used in a number of ways. - [[goto Placing text files quickly and easily on the web]] - [[goto Migration of "legacy" text to HTML]] - [[goto Facilitate mastering of HTML pages in ASCII]] - [[goto Automated conversions]] - [[goto Conversion of reports to HTML]] - [[goto Conversion print spool files to HTML]] - [[goto Convert Word documents]] - [[goto Pre-process text for import to Word]] - [[goto Pre-process text for printing]] - [[goto Add hyperlinks to fairly ordinary pages]] Placing text files quickly and easily on the web ------------------------------------------------ Plain text is still a very popular data format. It is easy to generate, and easy to read. However text files when placed on the web don't look as nice as normal web pages. AscToHTM will allow you to quickly add the HTML markup required to turn a plain text page into a nice looking HTML page. Because it is an automated conversion it will save you time, and ensure you avoid typos in HTML tags that could stop the page displaying wrongly in some web browsers. Migration of "legacy" text to HTML ---------------------------------- Large amounts of unconverted text exist. As people plan to put this information on the Web, conversion to HTML will become necessary. This can be a tedious and time-consuming task. AscToHTM will do much of the work for you. AscToHTM is priced to be worth an hour of two of your time. This means that the "pay back" time is negligible (we only mention this in case you have bean-counters to convince :). If you don't think AscToHTM will save you hours, then by all means don't buy it. Facilitate mastering of HTML pages in ASCII ------------------------------------------- The HTML created by AscToHTM may not be as pretty or as clever as that generated by a full blown HTML editor (read as "bloated"). But... It'll be easier to write, edit and spell-check, and it may have a hyperlinked contents list generated. Automated conversions --------------------- AscToHTM can be used to automatically convert text documents that you receive. For this we usually suggest you run in command line mode. Conversion of reports to HTML ----------------------------- Many people have legacy systems that generate printed reports that may be saved to file. AscToHTM can help extend the lifetime of such systems by turning their output to HTML. It may be you'll need some help in getting the best results from the program in such cases, since many reports consist of complex tables. Conversion print spool files to HTML ------------------------------------ Printer spool files are not strictly speaking plain text, but often - especially in older software systems - these files are plain text with a few printer controls added. Some users have had great success converting such files using asctohtm, and to support this we have added a limited ability to recognize and strip out Unix control characters, VT escape sequences and PCL printer codes. If you have a requirement in this area, contact the author at *infojafsoft.com* (replace "" by "@") to discuss whether the software can be made to meet your needs. Convert Word documents ---------------------- NOTE: AscToHTM *DOES NOT* convert Word's .doc or .rtf file formats. AscToHTM was _never_ intended to handle Word documents. We fully expect HTML export and import filters to appear (they have in Word '97), and we would advise anyone whose master document is in Word to search out these filters and give them a try. That said... a lot of people seem unhappy with what's already available, and AscToHTM does a reasonable job if you save the file as text with line breaks, though obviously tables and figures will get lost (in the case of tables, because Word throws them away). The main problem is that Word produces lousy looking text. This is one area where AscToHTM does a little better than "garbage in, garbage out" Pre-process text for import to Word ----------------------------------- (This is a bit cheeky, but does actually work.). Use AscToHTM to convert text to HTML, then import this into your word processing package. Since the text analysis engine in AscToHTM out-performs that in Word in many respects (URL, table and heading detection to name but three), you can often get better results than importing from text direct.. That's because AscToHTM's analysis engine is *smarter*. That's not just our view (see http://www.jafsoft.com/asctohtm/reviews.html) NOTE: The same text analysis engine is used in the text-to-RTF program [AscToRTF], which is more suited to this purpose. Pre-process text for printing ----------------------------- Use AscToHTM to convert text to HTML, then print the file from within Netscape or whatever. The result is a much nicer looking document with fonts'n'stuff. Add hyperlinks to fairly ordinary pages --------------------------------------- AscToHTM has a "link dictionary" feature that can be used to add hyperlinks to any word or phrase (see the [Policy Manual]). This can greatly enhance an otherwise dull set of text pages. $_$_HELP_CHAPTER 1,"Installation" Installation ************ The shareware version of AscToHTM is made available over the web from [a2h 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 [a2h updates] of AscToHTM over the last 4-5 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 AscToHTM =========================== The core AscToHTM software is actually developed under OpenVMS (the developer's OS of choice), and so AscToHTM is available under VMS as freeware, although it tends to lag behind the latest Windows version. For more details, visit http://www.jafsoft.com/asctohtm/a2hvms.html where you can download the latest OpenVMS installation OpenVMS Installation -------------------- Unzip the files. If you've taken an executable version, that's it. If you've taken an object library version, execute the build command file. You might want to define a foreign command to get better use out of the program. Have a cup of coffee and relax :) $_$_HELP_CHAPTER 1,"How it works" $_$_HELP_SUBJECT "Overview" How it works ************ AscToHTM 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 =============================== AscToHTM 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, AscToHTM tries to read the text file and mark it up in HTML 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 AscToHTM 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 AscToHTM generates the HTML file (there's nothing like stating the obvious :-) The HTML generated depends only on the original document, the calculated document policy, and any user policies supplied. [[GOTO Understanding the HTML generated]] describes the markup produced in more detail. Standards compliance ==================== Earlier versions of AscToHTM (before version [[TEXT 3.2]]) made no real attempt to be standards compliance. Now standards compliance is a stated goal or the program. Sadly I can't _guarantee_ standards compliance because the HTML generation is so complex that errors can and do occur, but it _is_ a goal, and usually documents will validate with few problems. Compliance has proved to be vital to get cross-browser compatibility, and to stand a chance of successfully applying CSS to created pages. Original versions of AscToHTM were (loosely) targeted at producing HTML [[TEXT 3.2]] code. Currently the software is targeted at "HTML [[TEXT 4.0]] Transitional", which allows CSS, but also permits tags (although these are deprecated). This is a compromise standard that is best placed to be well viewed by V3 and V4 browsers. $_$_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"]] - [[goto Drag'n'Drop execution]] $_$_SECTION ALL $_$_HELP_CHAPTER 2,"Running as a Windows application" $_$_HELP_SUBJECT "Overview" Running as a Windows application ================================ $_$_HELP_TOPIC_ID ID_RUN_WINDOWS $_$_SECTION MAKINGRTFHELP Main Dialog - [[goto File menu]] - [[goto Conversion Options menu]] - [[goto Analysis policies menu]] - [[goto Output policies menu]] - [[goto Settings menu]] - [[goto Language menu]] - [[goto View menu]] - [[goto Help menu]] - [[goto Update menu]] - [[goto Status window]] $_$_SECTION ALL Main Dialog ----------- AscToHTM 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 HTML 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 and an option to specify if you [[goto may overwrite files]] - 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* AscToHTM has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the HTML 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 5.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. Input file type ............... _(New in version 5.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 [[popup delimiter character]] 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. Delimiter character ................... _(New in version 5.0)_ When the [[popup input file type]] is set to "other-delimited table", then a field appears that allows you to enter the delimiter character that should be used to distinguish cells in each input line. Conversion type ............... $_$_HELP_TOPIC_ID ID_CONVERSION_TYPE The main screen of the program allows you to select the conversion type you wish to perform. These types will essentially create the same HTML, but in different ways, suited for different uses. The options include $_$_BEGIN_TABLE Output HTML to file(s) This is the default conversion type where the HTML will be output to either a single file, or a set of files if you elect to split a larger document. Output to a set of HTML Frames If you choose this option a set of HTML Frames will be created. Output to the Windows clipboard If you choose this option the HTML generated will be copied onto the Windows clipboard, and no HTML files will be created. $_$_END_TABLE May Overwrite Files ................... Depending on the [[popup conversion type]] you select, the main screen will also allow you to specify whether or not existing files name be overwritten. This protects against AscToHTM overwriting your files, but if you are repeatedly converting the same files you will need to either disable this option, delete all the existing files, or choose a different output location. If converting multiple files, the program will abort at the first attempt to overwrite an existing 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 HTML 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 HTML fragments File,Fragments file]] - [[goto Selecting the Link Dictionary File,Link Dictionary File]] - [[goto Selecting the Table Definition File,Table Definition File]] - [[goto Selecting the Text Command File,Text Command File]] Selecting the HTML Fragments File ................................. This option allows you to select the [[goto Using HTML fragments,Fragments file]] you wish to use. 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]] for where your pages are going to end up. 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 AscToHTM has many options known as "policies" to help you improve and correct the analysis it performs, and to customise the HTML 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 AscToHTM 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. Show Tool Tips Enable/disable the use of tool tips Show Status Dialog Enable/disable whether or not the [[goto Status window]] is shown during conversions Automatically view results Enable/disable whether or not the results should be displayed in your browser after the conversion Remember settings on exit Enable/disable whether or not your currently selected files and folders should be remembered for next time [[goto Tip of the day]] Enable/disable the "Tip of the day" feature $_$_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 pre-processor 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 See:- - [[popup Suppress INFO messages]] - [[popup Suppress program ERROR messages]] - [[popup Suppress TAG ERROR messages]] - [[popup Suppress URL messages]] - [[popup Suppress WARNING messages]] Drag and drop settings ...................... $_$_HELP_TOPIC_ID HIDD_SETTINGS_DRAG These options specify the behaviour of AscToHTM when invoked via drag and drop (i.e. by dropping a file icon on AscToHTM'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*[[br]] 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 AscToHTM 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. 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 AscToHTM 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 AscToHTM 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. Tip of the day .............. $_$_HELP_TOPIC_ID HIDD_TIPS The "Tip of the day" dialog will normally appear each time the program starts up. It will show a different tip each time it is displayed. Next and last buttons (labelled "<<" and ">>") can be used to review each tip in turn and the tip number is shown at the bottom should you want to take note and access the tip later. You can disable this feature by unchecking the "Show on Startup" tickbox, and you can always recall it via the option on the Settings Menu. $_$_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*. Thanks also go to Joan Marsh and Sandy McGregor for help with the earlier versions of the translation. 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* Dutch The Dutch translation is being undertaken by Jurrien Dokter, who can be contacted at *infoc-webpromo.nl* and runs the web site at http://www.c-webpromo.nl/ $_$_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' ................ AscToHTM 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*[[br]] 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"*[[br]] 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. AscToHTM 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. AscToHTM 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 _HTML doco (offline)_ Brings up the local copy of the HTML documentation in your preferred browser _HTML doco (online)_ Brings up the Internet copy of the HTML documentation in your preferred browser. _Register (online)_ In the 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,"Update menu" $_$_HELP_SUBJECT "Update menu options" Update menu ----------- $_$_HELP_TOPIC_ID ID_MENU_UPDATE The updates menu has the following option *Check for newer versions* This option will take you to the web site, where a check will be made to tell you if this is still the latest version of the software. $_$_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 AscToHTM 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. Once conversion is complete you can dismiss the window. You can automate this by ticking the "dismiss on completion" box. Should you wish to you can use the save to file button to save the messages displayed to file. This can be useful for reviewing messages, extracting URLs reported by the software (if showing URLs is enabled), or for sending details when requesting support. $_$_HELP_CHAPTER 2,"Running AscToHTM 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 AscToHTM from the command line inside a Command Line ("DOS") window. You can also run a [[goto console version]], a2hcons. The command line has the syntax $_$_BEGIN_PRE c:> a2hcons [ ...] [] [/qualifiers] $_$_END_PRE if running the console version, or $_$_BEGIN_PRE c:> AscToHTM [ ...] [] [/qualifiers] $_$_END_PRE 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: Ggenerally 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: /INDEX,/INDEX]] Generate a master index when converting multiple files [[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 ------------------------------- Specifies that the source file is a comma-delimited table. In this case each line will become a row in a table, and each value separated by a comma will become a cell in the table. Command line qualifiers: /CONSOLE --------------------------------- Specifies that the output should be direct to the output stream. This should normally be used with [[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 list 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 This qualifier will cause the program to generate DOS-compatible names in 8.3 format and a .HTM extension. 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: /INDEX ------------------------------- $_$_HELP_TOPIC_ID ID_QUAL_INDEX This qualifier will cause the program to create a master index or "directory page" file with hyperlinks to all the sections detected in the files converted. Only useful if you're converting multiple files at one time. See also the [[goto directory page policies]] Command line qualifiers: /LIST ------------------------------ These qualifiers cause AscToHTM 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 AscToHTM 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 AscToHTM.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 .html 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 AscToHTM 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 -------------------------------- Specifies that the source file is a tab-delimited table. In this case each line will become a row in a table, and each value separated by a tab will become a cell in the table. Command line qualifiers: /TABLE ------------------------------- Specifies that the source file is a plain text table. In this the program will do its best to analyse the table structure, and reproduce it. $_$_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 AscToHTM can make a useful addition to your "Send to" menu (available when you right-click on a file in explorer). To add AscToHTM to this menu, simply add a shortcut to your SendTo shortcuts folder. Under Windows 9x this is /Windows/SendTo under Windows XP this is /Documents and Settings//SendTo If you want to use a standard policy file (e.g. with a particular colour scheme), then create a simple .bat file with the command *AscToHTM %1 standard.pol* $_$_HELP_CHAPTER 2,Drag'n'Drop execution $_$_HELP_SUBJECT "Invoking the program via Drag'n'Drop operations" Drag'n'Drop execution ===================== Create an Icon for AscToHTM, and simply drag'n'drop files onto it. The results are identical to those obtained by typing in the filenames as if you were [[goto Running as a command line program]]. Alternatively, run the program as normal and then drag files onto the running program. You can configure the program's behaviour in drag'n'drop operation by using the Settings | Drag'n'Drop menu. Since AscToHTM can support arguments being passed on the command line. One useful way to use the program is to add an icon to the desktop, allowing you to "drop" files onto the icon to get them converted. If you use policy files, edit the icon properties so that the command line reads something like $_$_BEGIN_PRE "c:\program files\jafsoft\asctohtm.exe" "c:\mydir\mypolicy.pol" $_$_END_PRE This will ensure the policy file mypolicy.pol is used in the conversion. You may also need to set the working directory to something suitable. If you have multiple policy files (e.g. different colour schemes), simply create additional icons with different policy files. $_$_HELP_CHAPTER 1,"Getting the most from AscToHTM" Getting the most from AscToHTM ****************************** $_$_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 Using text definition blocks]] - [[goto Working with tables]] - [[goto Processing several files at once]] - [[goto Using wildcards]] - [[goto Using script files]] - [[goto Generating log files]] - [[goto Other tips and tricks]] $_$_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 a2hcons simply type c:> a2hcons Input_file.name at the command line. This will create a file :- input_file.html An output file which will have the same file name with a .html 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 (.html) 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 HTML file will be satisfactory. If there are problems, or if you wish to add to the created file, you can tailor the conversion by changing policies. In the Windows version, this is done by editing policies via the *Conversion Options* menu, which is fully described in the context-sensitive Windows Help file (press F1 at any point). The conversions options are also known as "policies", and these can be saved to a text policy file. Policy files are just text files with one option per line. If you're careful, they can be edited by hand in a text editor. It is the format of policies in a policy file that is shown and discussed in this document. Policy files created in the Windows version can also be used by the console version. Using policy files to improve the conversion -------------------------------------------- If your initial results are a little strange, then review the policies calculated by the program, and create a "policy file" to tell the program how to do the conversion differently. You can do this as follows :- a) _By creating a "sample" policy file_ You can create a sample .pol policy file that documents the policies used. Do this either by using the command line c:> a2hcons 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 .html file generated, you will now have an output policy file "input_file.pol" which describes the document policy file calculated by AscToHTM 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 AscToHTM. 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 AscToHTM generates Using link dictionary files --------------------------- In addition to adding hyperlinks for all URLs, email addresses, section references and contents list entries, AscToHTM 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. Link Dictionary Edit Dialog ........................... $_$_HELP_TOPIC_ID HIDD_LINKDICT_EDIT _Menu location: Conversion options -> Configuration files -> Link Dictionary_ [[br]] _(Enter a filename and then select "Edit")_ 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 See also [[goto Using link dictionary files]] Using multiple policy files --------------------------- If you wish to use AscToHTM 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 AscToHTM 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 -------------------------------------- AscToHTM 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. See [[GOTO Using the pre-processor]] and [[GOTO pre-processor in-line tags]] for more details. Using text definition blocks ---------------------------- Using pre-processor tags you can define "blocks" of text known as "definition blocks". Definition blocks allow blocks of output to be defined out of sequence, that is the content is defined in one location, and then may be instantiated at a number of different locations. A definition block has the form $_$_BEGIN_PRE $_$_DEFINE_BLOCK .. text that forms the block .. $_$_END_BLOCK $_$_END_PRE The text inside the block may contain in-line tags, but it cannot contain any other tag directives. To invoke a block use the [[popup Pre-processor command: EMBED_BLOCK, EMBED_BLOCK]] or [[POPUP Pre-processor command: INSERT_BLOCK, INSERT_BLOCK]] commands. One tag that is particularly useful inside blocks is the [[POPUP Pre-processor command: VARIABLE, VARIABLE]] tag. You can define variables throughout the document and then quote them inside a define block. A possible example of use would be the addition of "page" footers. You could define the text that goes inside a page footer, and include in it a variable called PAGE_NUMBER. You can then re-define the PAGE_NUMBER and output a new page boundary with the commands $_$_BEGIN_PRE $_$_DEFINE_VARIABLE PAGE_NUMBER 21 $_$_INSERT_BLOCK PAGE_FOOTER $_$_END_PRE having previously defined a PAGE_FOOTER block. It should perhaps be pointed out that "pages" are anathema to HTML, but should you want this feature this is a possible implementation. Working with tables ------------------- AscToHTM does a reasonable job of detecting and analysing Tables, but the following tips can be useful. - If the extent of the table is wrongly calculated, mark it up using [[goto Section delimiters, TABLE pre-processor commands]], or insert an extra blank line before and/or after the table. Tables will rarely bridge a two-line gap. - If the table extent is wrong, try adjusting the [[goto "Table extending factor"]] - If AscToHTM places a code fragment or diagram in TABLE markup, mark the source using [[goto Pre-processor command: CODE, CODE]] or [[goto Pre-processor command: CODE, DIAGRAM]] pre-processor commands - Avoid mixing tabs and spaces. This makes spotting column alignments positions more difficult. If you do mix them, check that the [[goto "TAB size"]] policy has a suitable value. - If you want the heading in bold, try drawing a line all the way across, separating header from data - If too many columns are created, adjust the [[goto "Minimum TABLE column separation"]] to be greater than 1, and ensure there are at least two spaces between columns. Alternatively "break formation" by inserting a space at the start of every second or third line. - If too few columns are created try adjusting the [[goto "Column merging factor]] policy. - If AscToHTM puts lines in tables when they shouldn't be, increase the [[goto "Minimum automatic 
 size"]] value.  This is a common problem in 
  email digests with people's .sigs in them.

- If you wish to fine-tune a particular table, use the pre-processor
  [[goto Table modifier commands]].

- If the table layout is approximately correct, switch off the table
  border (set the value to 0).  Often this will look acceptable, even
  though the analysis has gone wrong.


$_$_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, [[goto Using script files, use a script]]

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:> a2hcons @List.file [rest of command line]

Where the file "list.file" is a steering file which contains a list of
AscToHTM 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 a2hcons 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 directory page"
$_$_HELP_SUBJECT "Generating a directory page"
Generating a directory page
===========================
When converting several files at once, AscToHTM can be made to generate
a "Directory Page".  This is an HTML index of all the files converted
and their contents.

The policies available for controlling generation of a directory
page are explained in "[[GOTO Directory page policies]]".

The directory page will consist of an entry for each file converted,
in the order that files are converted (usually alphabetic).  Each entry
will (optionally) contain :-

- A link to the file being converted.  The link will either be the
  converted file's HTML title, or failing that, the filename itself.

- Links to each of the sections of the converted file as detected
  by AscToHTM.


$_$_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 2,"Other tips and tricks"
$_$_HELP_SUBJECT "Other tips and tricks"
Other tips and tricks
=====================
- Read the [FAQ]

- Browse the [Policy Manual] to gain a feel for what options the
  program support.  Similarly the [Tag Manual]

- If you can, try to use as much white space as possible, e.g. before
  paragraphs and new sections and at the end of the document.
  This makes it easier for AscToHTM to place things in context, reduces
  ambiguity and increases the chances of correct HTML being generated.

- Ensure you have consistency in your use of indentation, bullets etc.
  On the output pass AscToHTM rejects lines that "fail policy", so
  any inconsistencies are liable to lead to errors in the HTML.

- Try to avoid lines that may confuse AscToHTM.  For example numbers
  at the start of a line of text may be interpreted as a section
  heading.  If the number is out of sequence, or at an incorrect
  indentation this will "fail policy".  However, it may cause confusion
  and is best avoided wherever possible.  Where a number has to be at 
  the start of a line, try using an indentation level that doesn't 
  match that used by your headings.

- Review the messages displayed during conversion.  Often these
  will highlight problems perceived by the software.

- For tab- or comma- delimited tables, review the BEGIN_TABLE,
  BEGIN_DELIMITED_TABLE and BEGIN_COMMA_TABLE commands described
  in the [Tag Manual].  If you can add these to your source text
  you will get better results.



$_$_HELP_CHAPTER 1,"Understanding the HTML generated"
Understanding the HTML generated
********************************
Before converting files to HTML, AscToHTM 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 Contents list generation]]
	- [[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]]

In addition to the HTML generated as a result of analysis, you have the ability to 
customise and add to the HTML created.

- [[goto Adding HTML features to the document]]
	- [[goto Adding a Document Title]]
	- [[goto Adding a Contents list]]

	- [[goto Adding Headers and Footers to your output]]
	- [[goto Using HTML fragments]]
	- [[goto Splitting large files into a linked set of smaller files,Splitting up large files]]
	- [[goto Generating a set of Frames]]
	- [[goto Outputting HTML to the clipboard,Output to the Windows clipboard]]
		

$_$_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 Contents list generation]]
- [[goto Definition detection]]


Paragraph detection
-------------------
$_$_HELP_TOPIC_ID ID_PARAGRAPHS
AscToHTM 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
---------------------
AscToHTM performs statistical analysis on the document to determine
at what character positions indentations occur.  The software attempts to 
honour your indentation pattern by using 
 .. 
 
markup, however the effect can only ever be approximate.

In calculating the indent positions AscToHTM 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.

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

AscToHTM 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 AscToHTM 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
--------------------------
AscToHTM attempts to automatically detect bullets of several types:

- [[goto Numbered bullet detection,Numbered bullets, e.g. 1), 2)....]]
- [[goto Alphabetic bullet detection, Alphabetic bullets (upper and lower case)]]
- [[goto Roman Numeral bullet detection,Roman numeral bullets (upper and lower case)]]

- Hyphen ‘-‘ bullet points
- Small letter ‘o’ bullet points
- [[goto bullet chars, bullets using other characters]]

Should the analysis fail, you can override any and all of these via the analysis bullet 
policies

AscToHTM will use 
    ..
  • ..
 or 
    ..
  1. ..
    2.  markup for bullets.  
This has the effect of putting the bulleted text one level of indentation to the right of 
the current text.

*Bullet paragraphs*

	AscToHTM 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)	AscToHTM 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.  AscToHTM
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
.........................
AscToHTM 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
...........................
AscToHTM detects upper and lower case alphabetic bullets.  

Roman Numeral bullet detection
..............................
AscToHTM detects upper and lower case roman numeral bullets.


$_$_HELP_CHAPTER 3,"Contents Lists"
$_$_HELP_SUBJECT "Contents list generation"
Contents list generation
------------------------
AscToHTM can detect the presence of a contents list in the original
document, or it can generate a contents list for you from the headings
that it observes.  There are a number of policies that give you control
over how and where a contents list is generated (see [[GOTO Contents list policies]]).

There are four different situations in which contents lists may, or
may not be generated.  These are :-

- [[goto Contents lists in default conversions]]
- [[goto Contents lists in conversions to a single HTML file]]
- [[goto Contents lists in conversions to multiple HTML files]]
- [[goto Contents lists in conversions to frames]]

Contents lists in default conversions
.....................................
By default AscToHTM will not generate a contents list for a file unless
it already has one.

If it should detect a contents list in the document, then that list
is changed into hyperlinks to the named sections.  This only works
currently for files with numbered headings.

Where an existing list is detected, headings shown in the contents 
list are converted into links, and the link text is that in the 
original contents list, and not the text in the actual heading (often 
they are different).

Note:	AsctoHTM currently only detected numbered contents lists, and
	is occasionally prone to error when they are present.  If
	you experience problems, either delete the contents list
	and get AscToHTM to generate one for you, or mark up the
	existing list using the contents pre-processor commands
	(see [[goto Section delimiters, Pre-processor section delimiters]])

Contents lists in conversions to a single HTML file
...................................................
As described in [[goto Contents lists in default conversions]], AscToHTM will not generate 
a contents list by default unless it already has one.

*Requesting a contents list*

	You can request that a contents list is always generated, by
	using the [[goto "Add contents list"]] policy.  In this case a
	contents list is either

	a) made from the existing contents list, or

	b) generated from the observed headings.  in this case the contents
	   list will only be as good as the detection of headings in
	   the rest of the document permits.

*Forcing a generated contents list*

	You can force a generated list to be used by disabling the 
	[[goto "Use any existing contents list"]] policy.

	If an existing contents list is present, it is deleted from the
	output.  Normally it's best to either use the existing contents list,
	or to delete it from the source text and request a generated list.

*Contents lists placement*

	By default the contents list is placed at the top of the output
	file.  In earlier versions of AscToHTM the contents list was always
	placed in a separate file.

	You can cause contents lists to be placed wherever you want by using
	the [[goto pre-processor command: CONTENTS_LIST, CONTENTS_LIST]] preprocessor command.  If you do this,
	then contents lists is placed *only* where you place CONTENTS_LIST
	markers.

*Generating a contents list in a separate file*

	If you select the [[goto "Generate external contents file"]] policy
	the contents list is placed in a separate file, and a hyperlink
	to that file called "Contents List" is placed at the top of the HTML
	page generated from the document.

	You can choose the name of the external file using the 
	[[goto "External contents list filename"]] policy.  If omitted, the file
	is called "Contents_", where  is the name of
	the document being converted.

Contents lists in conversions to multiple HTML files
....................................................
AscToHTM can be made to split the output into many files.  At present
this is only possible at detected section headings.  Each generated
page usually has a navigation bar, which includes a hyperlink back
to the following section in any contents list.

The behaviour is identical to that in [[goto Contents lists in conversions to a single HTML file]]
expect that

      a) the output is now split into several files.

      b) the options to generate an external contents list in a separate
	 file are no longer available.

      c) if the contents list is being generated, it is now placed at the
	 foot of the first document, rather than at the top (unless the
	 [[goto pre-processor command: CONTENTS_LIST, CONTENTS_LIST preprocessor command]] is used)

	 This is usually *before* the first heading (which now starts the
	 second document), and *after* any document preamble.

Note:	Where the original contents list is used when splitting files
	it is possible that not every file is directly accessible
	from the contents list, and that the back links to the contents
	list may not function as expected.  In such cases you can
	go from the contents list to a major section, and then use
	the navigation bars to page through to the minor section.

Contents lists in conversions to frames
.......................................
Contents list generation for the main document will proceed as described
in the previous sections.  

When making a set of frames, you can elect to have a contents 
frame generated (the default behaviour), and this will have a 
generated list placed in a frame on the left.  This can mean you 
have a contents list in the contents frame on the left, and also
at the top of the first page in the main document.  For this reason the
main frame often starts by displaying the second page.

The number of levels shown in the contents frame list can be controlled 
by policy.  Alternatively you can replace the whole contents of the 
contents frame by defining a CONTENTS_FRAME [[goto using html fragments, HTML fragment]].


[[LINKPOINT "Definitions"]]
$_$_HELP_CHAPTER 3,"Definitions"
$_$_HELP_SUBJECT "Definition detection"
Definition detection
--------------------
AscToHTM 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

AscToHTM 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).

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

AscToHTM offers the option of marking up the definition term in
bold.  This is not the default behaviour however.

Definition paragraphs
.....................
AscToHTM 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 AscToHTM currently only copes with single
      		paragraphs (i.e. not with continuation paragraphs), and
      		only with single word definitions.
$_$_END_PRE

AscToHTM 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 can be marked up in 
     
... 
    ..
     
    ..
     
     and (optionally) can have the definition 
term highlighted in  ...  markup.


$_$_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
----------------------
AscToHTM can be made to [[goto Allow automatic centring, 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
---------------------
AscToHTM 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, AscToHTM 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


Emphasis detection
------------------
AscToHTM can look for text emphasised by placing asterisks (*) either
side of it, or underscores (_).  AscToHTM will convert the enclosed text
to *bold* and _italic_ respectively using *Bold* and *italic* tags 
respectively.

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

For example the following two paragraphs :-

$_$_CHANGE_POLICY Look for *this* and _that_ emphasis : no
$_$_BEGIN_PRE
	Here are *bold* and _italic_ words.  The phrase _The Guardian Newspaper_ 
	would appear in italics.  The words *_this_* and _*that*_ would appear in 
	bold italics.

	The program can cope with phrases such as _Alice in
	Wonderland_ which span more than one line.
$_$_END_PRE
$_$_CHANGE_POLICY Look for *this* and _that_ emphasis : yes

Becomes 

	Here are *bold* and _italic_ words.  The phrase _The Guardian Newspaper_ 
	would appear in italics.  The words *_this_* and _*that*_ would appear in 
	bold italics.

	The program can cope with phrases such as _Alice in
	Wonderland_ which span more than one line. 


Unix emphasis character detection
---------------------------------
AscToHTM 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 AscToHTM 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]]

You can control which features get hyperlinks added by modifying the
available [[goto hyperlink policies]]


Contents List detection
-----------------------
AscToHTM can detect the presence of a contents list in the original
document, or it can generate a contents list for you from the headings
that it observes.  There are a number of policies that give you control
over how and where a contents list is generated (see [[GOTO Contents list policies]]).

AscToHTM will attempt to detect contents list 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.  AscToHTM will 
  assume the first set is the contents list.
- By spotting 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 list policies]]

In addition to converting existing contents lists, AscToHTM can generate a contents 
list from the observed headings.

The various situations in which a contents list may, or may not be created
are described in [[goto Contents list generation]]


Cross-reference detection
-------------------------
AscToHTM 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 AscToHTM 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
-------------
AscToHTM 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.


Usenet Newsgroup detection
--------------------------
AscToHTM can convert any newsgroup names it spots into hyperlinks to
those newsgroups.  Because this is prone to error, AscToHTM 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
------------------------
AscToHTM 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
-----------------------
AscToHTM 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 AscToHTM

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
===========================
AscToHTM 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), AscToHTM will use
the standard "Heading n" styles.

In addition to this, AscToHTM will insert a named bookmark to allow 
hyperlink jumps to this point.  These bookmarks are used for example 
in any cross-reference hyperlinks that AscToHTM generates, and
also by any [[goto Pre-processor command: GOTO, GOTO]] tags.

The configuration of these options is described under [[goto Headings Policies]].  

$_$_SECTION MAKINGRTFHELP
- [[popup Numbered heading detection]]
- [[popup Capitalised heading detection]]
- [[popup Underlined heading detection]]
- [[popup Embedded heading detection]]
- [[popup Key phrase headings]]
- [[popup Numbered paragraph detection]]
- [[popup Mail and USENET headers]]

- [[popup Heading policies in a policy file]]
$_$_SECTION ALL


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
-----------------------------
AscToHTM can treat wholly capitalised lines as headings.  It also
allows for such headings to be spread over more than one line.


Underlined heading detection
----------------------------
AscToHTM 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.

The level of heading associated with an underlined heading depends on the
underline character as follows:-

$_$_BEGIN_TABLE
  	'****'		        level 1
        '====','////'		level 2
        '----','____','~~~~'	level 3
        '....'			level 4
$_$_END_TABLE

The actual *markup* that each heading gets may depend on your policies.
In particular level 3 and level 4 headings may be given the same size
markup to prevent the level 4 heading becoming smaller than the text it
is heading.  However the _logical_ different will be maintained, e.g.
in a generated contents list, or when choosing the level of heading at which
to split large files into many HTML pages.


Embedded heading detection
--------------------------
The program can look for headings "embedded" in the first paragraph.
Such headings are expected to be a complete sentence or phrase in
UPPER CASE at the start of a paragraph.  Where detected the heading
will be marked up in bold, rather than  markup, although it will
still be added to, and accessible from any hyperlinked contents list
you generate for the document.

At present such headings are not auto-detected... you need to
switch on the [[goto Expect Embedded headings]] policy.


Key phrase headings
-------------------
The program can now look for lines that start with particular words
or phrases (such as "Chapter", "Part", Title") of your choice and
treat these lines as headings.  Previously this only worked in a
limited way if the heading line was also *numbered* ("Chapter 1") etc.

To use this feature, set the policy [[goto Heading Key phrases]]


Numbered paragraph detection
----------------------------
Some types of documents use what look like section numbers to number
paragraphs (e.g. legal documents, or sets of rules).

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

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


Heading policies in a policy file
---------------------------------
AscToHTM has the following section heading policies that will normally be
correctly calculated on the analysis pass :-

      - [[popup Expect Numbered Headings]]
      - [[popup Expect Underlined Headings]]
      - [[popup Expect Capitalised Headings]]
      - [[popup Expect Embedded Headings]]
      - [[popup Heading key phrases]]

      - [[popup Check indentation for consistency]]

      - [[popup Expect Second Word Headings]]
      - [[popup First Section Number]]
      - [[popup Smallest allowed  tag]]
      - [[popup Largest allowed  tag]]

      - [[popup Preserve underlining of headings]]

Section headers are far and away the most complex things the analysis
pass has to detect, and the most likely area for errors to occur.

AscToHTM will also document to a policy file the headings it finds.
This is still to be finalised, but currently has the format

$_$_BEGIN_PRE
      We have 4 recognised headings
          Heading level 0 = "" N at indent 0
          Heading level 1 = "" N.N at indent 0
          Contents level 0 = "" N at indent 0
          Contents level 1 = "" N.N at indent 2
$_$_END_PRE

AscToHTM will read in such lines from a policy text file, but does not
yet fully supported editing these via the Windows interface.  

The syntax is explained below, but this will probably change in future
releases.  You can edit these lines in your policy file, and through 
the policy options in Windows.

The lines are currently structured as follows

$_$_BEGIN_TABLE
        Line component          Value
        --------------------------------------------
        xxxx                    Either "Heading" or "Contents" according
                                to the part of the policy being described

        Level n                 Level number, starting at 0 for chapters
                                1 for level 1 headings etc.

        "Some_word"             Any text that may be expected to occur before
                                the heading number.  E.g. "Chapter" or "Section"
                                or "[".  The case is unimportant.

        N.Nx                    The style of the heading number.  This will
                                ultimately (in later versions) be read
                                as a series of number/separator pairs.

                                The proposed format is
                                  "N" = number
                                  "i" / "I" = lower/upper case roman numeral
                                with an 'x' at the end signalling that trailing
                                letters may be expected (e.g. 5.6a, 5.6b)

        at indent n             The indentation that this heading is expected
                                at.  This is important in helping to eliminate
                                false candidates.
$_$_END_TABLE


$_$_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 HTML, 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 
     tags in the HTML, as HTML doesn't
really support the concept of (layout) pages.


User defined pre-formatted text
-------------------------------
AscToHTM 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 
     tags which uses a non-proportional font to 
preserve the relative spacing.

For example :-

$_$_BEGIN_PRE
      The use of BEGIN_PRE and END_PRE pre-processor 
        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
-----------------------------------------
AscToHTM 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 AscToHTM 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 AscToHTM to pre-formatted text by
setting the minimum number of lines required for a pre-formatted region
using the [[goto Minimum automatic 
     size]] policy.

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

When tables are detected, AscToHTM will attempt to generate the correct 
HTML table.

When AscToHTM gets the detection wrong you can use the AscToHTM 
[[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.  AscToHTM will
attempt to spot the table, its columns, its headings, its cell alignment
and entries that span multiple columns or rows.

Should AscToHTM 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 Table generation 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

Code sample detection
.....................
AscToHTM 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 AscToHTM wrongly detect the extent of a code fragment, you can
mark up a section of text by using the [[goto Pre-processor command: CODE, CODE]] pre-processor 
markup.

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

ASCII art and diagram detection
...............................
AscToHTM 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 AscToHTM wrongly detect the extent or type of a diagram,
you can mark up a section of text by using the [[goto Pre-processor command: DIAGRAM, DIAGRAM]] 
pre-processor markup.

Text block detection
....................
_(New in version 5.0)_

If AscToHTM 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 AscToHTM 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 1,"Adding HTML features to the document"
Adding HTML 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]]


$_$_HELP_CHAPTER 2,"Adding a document title"
$_$_HELP_SUBJECT "How to add a title"
Adding a Document Title
=======================
AscToHTM can calculate - or be told - the title of a document.  This
will be placed in document properties section in the header of 
each HTML 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 "Use first line as heading"]] policy is set 
   then the first heading (if any) encountered is used as the title.

   Note: 	Depending on your document structure, this is prone to give
		bland tiles like "Introduction" , "Overview" and "Summary"

3) If the [[goto "Use first line as title"]] policy is set 
   then the first line in the file is used as the title.

4) If the [[goto "Document title"]] policy is set then this value
   is used.

   Note:	If this is the value you want, ensure the other policies
		outlined above are disabled.

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


$_$_HELP_CHAPTER 2,"Adding a contents list"
$_$_HELP_SUBJECT "How to add a contents list"
Adding a Contents list
======================
AscToHTM 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. 

There are a number of policies that give you control over how and 
where a contents list is generated (see [[goto contents list 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 [[goto Pre-processor command: CONTENTS_LIST, CONTENTS_LIST]] pre-processor command.  

_Contents list detection_
AscToHTM 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.  AscToHTM 
  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 list policies,Contents lists]] policies.


$_$_HELP_CHAPTER 2,"Adding Headers and Footers to your output"
$_$_HELP_SUBJECT "How to add Headers and Footers"
Adding Headers and Footers to your output
=========================================
$_$_HELP_TOPIC_ID ID_ADD_HEADERS
AscToHTM can be made to add HTML headers and footers to each page of HTML 
generated.  Although there are policies that allow you to specify special header and 
footer files, in later versions of the software we recommend the use of 
[[goto Using HTML fragments,HTML fragments]]

Using a HTML Fragments file, you can define the reserved fragment names
HTML_HEADER and HTML_FOOTER and these will be copied into the output.  You
can even embed HTML [[goto fragment tags]] into these definitions, to allow for
some customisation.  Other reserved names allow you to customize the headers
and footers when converting files into a set of frames.

For example the definition

$_$_BEGIN_PRE
	$_$_DEFINE_HTML_FRAGMENT HTML_FOOTER
	
    
	
    © JafSoft 2004
    
	
    Converted by [[VERSION]] from this [[SOURCE_FILE]] on [[TIMESTAMP]]
    
	$_$_END_BLOCK
$_$_END_PRE

defines a fragment that will add a line at the end of the page and then
a copyright notice and a line of text showing the version number of the
conversion program used, a link to the original text source file (assumed
to be a local link) and the date the conversion was performed.
	
See [[goto Using HTML fragments]] for a fuller description. 


$_$_HELP_CHAPTER 2,"Customizing the HTML through use of 'HTML Fragments'"
$_$_HELP_SUBJECT "Introduction to HTML fragments"
Customising the HTML by using 'HTML fragments'
=============================================
$_$_HELP_TOPIC_ID ID_HTML_FRAGMENTS
From version 4 onwards the program allows you to define “HTML fragments”, that is 
fragments of HTML that can be used by the software to override the standard HTML 
that it produces.   This allows you to customise the headers, footers, horizontal rules, 
contents list and more.

See [[goto Using HTML fragments,HTML fragments]]


$_$_HELP_CHAPTER 2,"Splitting large files into many cross-linked pages"
$_$_HELP_SUBJECT "Introduction to file splitting"
Splitting large files into a linked set of smaller files
========================================================
$_$_HELP_TOPIC_ID ID_SPLITTING_FILES
By default AscToHTM creates a single HTML file.  However it is possible to get the 
software to split large files into smaller files, all linked together.  For this to be 
possible the program has to first detect headings in the file.  Once this is done, you 
can choose at what level of heading you want to split the file into pages.

This feature is described more fully in the [FAQ] that is part of the [[goto Documentation available,HTML documentation]]

See [[goto how file splitting works]]


How file splitting works
------------------------
The program can only split into files at headings it recognises (see
"[[GOTO Headings and section titles,Detecting Headings]]").  Before splitting the file you first need to 
check that the program is correctly determining where the headings are, and 
what type they are.  

Headings can be numbered, capitalised or underlined.  To tell if the 
program is correctly detecting the headings

a) Look at the HTML to see if 
    , 
     etc. tags are being added
   to the correct text.

b) If the headings are wrong, check the [[goto Headings Policies]] are being set 
   correctly. 
   
c) Once the headings are begin correctly diagnosed, you can use the
   [[goto File Splitting policies]] to switch on file splitting and to
   tailor the conversion

Note that the [[goto split level]] is set to 1 to split at "chapter" headings, 2 
to split at "chapter and major section" headings etc.

Underlined headings tend to start at level 2, depending on the underline
character (see "[[GOTO Underlined heading detection]]")

Hopefully this will give you some pointers, but if you still can't get it to
work, please mail a copy of the source file (and any policy file you're
using) to *infojafsoft.com* and I'll see what I can advise.


$_$_HELP_CHAPTER 2,"Turning large files into a set of HTML FRAMES"
$_$_HELP_SUBJECT "Introduction to creating FRAMES output"
Generating a set of Frames
==========================
$_$_HELP_TOPIC_ID ID_ADD_FRAMES
You can use the Conversion Type to select the option of placing your document into a 
set of HTML frames.   This will consist of a master document containing the 
necessary  tags to define the frames, and then a number of supporting 
documents.  The main conversion files will be created as before, and will be 
displayed in the main frame. 

$_$_SECTION MAKINGRTFHELP
In this section: 
- [[goto Frames Overview]]
- [[goto The "header" and "footer" frames]]
- [[goto Using HTML fragments to override frame contents]]
- [[goto NOFRAMES tag and NOFRAMES link]]

$_$_SECTION ALL


Frames Overview
---------------
The program has the ability to generate a set of frames from your source 
file.  The program works to a model set of frames as shown below, but 
you have a great degree of control over how the frames are laid out, 
and what their contents are.

$_$_BEGIN_DIAGRAM
      +------------------------------------------------------------+
      |                       Header frame                         |
      |                        (optional)                          |
      +-------------+----------------------------------------------+
      |  NOFRAMES   |                                              |
      |    link     |                                              |
      |             |                                              |
      |             |                                              |
      |             |                                              |
      |  Contents   |               Main                           |
      |   Frame     |               Frame                          |
      | (optional)  |                                              |
      |             |                                              |
      |             |                                              |
      |             |                                              |
      |             |                                              |
      |             |                                              |
      +-------------+----------------------------------------------+
      |                       Footer frame                         |
      |                        (optional)                          |
      +------------------------------------------------------------+
$_$_END_DIAGRAM

The master  document
..............................
Frames are implemented under HTML by having a document that describes
the frame layout by using one or more nested  tags.
These tags group together  tags that identify other HTML files 
that describe the contents of the individual frames or panes.  The 
HTML page containing the  doesn't normally contain any visible 
content.  The source of this HTML page looks something like this :-

$_$_BEGIN_PRE
      
        
        
          
          
        
        
        
          <BODY>
          <p>This browser does not support FRAMES<p>
          <p>Visit <A TARGET="_top" 
      		      HREF="noframes_main.html">this link</A></p>
          </BODY>
        
      
$_$_END_PRE

This example produces a layout similar to that shown in the diagram
in the [[goto Frames Overview]].  There are four frames as follows :-

      - "header" at the top of the screen with content taken from the
         HTML page header.html

      - "footer" at the bottom of the screen with content taken from the
         HTML page footer.html

      - the two frames "contents" and "main" side by side in the middle
        of the screen, between the "header" and "footer" frames.  The
        "contents" frame is on the left, the "main" frame on the right.
        The contents of these frames are held in the html files 
        "contents.html" and "main.html".

The  tag describes the content to be displayed if the browser
doesn't support frames.  This is less common now, but is still important
as many search engines don't understand frames, and will only index
the pages linked to in the <NOFRAMES> tag.

In HTML the frame names and source file names can be whatever you like.
AscToHTM uses the frame names "header", "footer", "contents" and
"main", but will vary the source file names according to the name of
your input filename.

Depending on the details of your conversion, not all of the above
frames are generated, in which case the <FRAMESET> tags will look 
slightly different.  

You don't need to worry about any of this as AscToHTM will determine 
what layout is required and will generate the necessary HTML <FRAMESET>
code.

By default if you convert a file called "myfile.txt" the files created
are named as follows:-

	myfile_frame.html		- Master <FRAMESET> file

	myfile_header_frame.html	- "header" source file.
	myfile_contents_frame.html	- "contents" source file.
	myfile_footer_frame.html	- "footer" source file.

	myfile.html			- "main" source file.


The "main" frame
................
The "main" frame will contain the conversion of your source file.
If you elect to split a document into many pages, then this will
show the start page (which will have links to any next/previous page).

See also [[goto Splitting large files into a linked set of smaller files,Splitting up large files]]


The "contents" frame
....................
If your document has recognised headings, then the program is 
able to generate a contents list (see 5.6.2).  In such cases a
"contents" frame is generated and the contents list is 
placed in a file called "myfile_contents_frame.html".

If no contents list can be generated, then no contents frame is 
created unless you supply a CONTENTS_FRAME [HTML fragment] to be
used as the contents of the "contents" frame.

The contents frame is placed to the left of the main frame.  
It will include a hyperlink labelled "NOFRAMES" (see [[goto NOFRAMES tag and NOFRAMES link]]) 
and the generated contents list.  This is different from the <NOFRAMES>
tag described in [[goto The master <FRAMESET> document]].

You can use policies (see [[goto Using policies to control the frame structure]]) to suppress the 
creation of a contents frame or to control the following:-

      - width of the frame
      - colours of background and text
      - number of levels shown in the generated contents list
      - whether a "NOFRAMES" link is shown, and what URL it links to
      
You can also customize the frame's appearance using the following 
HTML fragments (see [[goto Using HTML fragments to override frame contents]])

      - CONTENTS_FRAME
      - START_TOC / END_TOC

See also [[goto Using HTML fragments to override frame contents]]


The "header" and "footer" frames
--------------------------------
The software cannot "detect" headers and footers in your source text,
so you will only get a header or footer frame if you supply the HTML
yourself.  Header and footer frames can be useful as they provide you
with the opportunity to supply titles, navigation links or copyright 
notices that are always visible.

Prior to version 4 the software already had the ability to add HTML 
headers and footers to each page generated using HTML supplied in
separate files identified by policy values.  From version 4 onwards
[HTML fragments] may also be used.

NOTE: 	We recommend that, where possible, you use [HTML fragments]
	to define any header and footer HTML

It's expected that you may want to convert the same source into both 
frames and non-frames forms, using the same policy file.  Given this
the program has the ability to "promote" the HTML headers and footers
used in non-frames production into their own always-visible frames.  
Equally there may be times when this behaviour is not wanted.

The relationships between headers and footers used in non-frames
conversion and those used in frames-based conversion are quite complex.  
In the following sections we describe how headers (footers) are 
calculated.  The logic is described for headers, but applies equally
well to footers if you make the necessary name changes.

Non-frames use of HTML headers
..............................
In non-frames conversion each page created will get a HTML header if

a) The policy [[goto "HTML header file"]] is set
b) The [HTML fragment] HTML_HEADER is defined

If both are set, the HTML_HEADER fragment is used in preference.

The selected header is referred to as the "standard" header in the
discussion in the next two sections.

Note:	For HTML footers the fragment HTML_FOOTER is used, and the 
	policy [[BR]] [[goto "HTML footer file"]] is tested.

"main" frame header
...................
In frames conversion the HTML header added to each page is determined
by three things

- Any "standard" HTML header defined for non-frames conversion 
  (see [[goto Non-frames use of HTML headers]])
- the policy [[goto "Use main header in header frame"]]
- whether or not a [HTML fragment] MAIN_FRAME_HEADER is defined

If the fragment MAIN_FRAME_HEADER is defined, then that is used.

If the fragment MAIN_FRAME_HEADER is not defined, and there is no
"standard" header, then the main frame gets no HTML header.

If the fragment MAIN_FRAME_HEADER is not defined, and the policy is *not*
set then the "standard" header is used as in non-frames conversion.

If the fragment MAIN_FRAME_HEADER is not defined, and the policy is set 
then the "standard" header is promoted into its own "header" frame, 
and the main frame gets no HTML header.

Note:	For HTML footers the fragment MAIN_FRAME_FOOTER is used, and 
	the policy [[BR]] [[goto "use main footer in footer frame"]] is tested.
 
"header" frame 
..............
In frames conversion whether or not a "header" frame is created
is determined by three things

- Any "standard" HTML header defined for non-frames conversion 
  (see [[goto Non-frames use of HTML headers]])
- the policy [[goto "Use main header in header frame"]]
- whether or not a [HTML fragment] HEADER_FRAME is defined

If the fragment HEADER_FRAME is defined, then that is used as the contents
of a "header" frame.

If the fragment HEADER_FRAME is not defined, and there is no "standard"
header, then no "header" frame is created. 

If the fragment HEADER_FRAME is not defined, and the policy is not set,
then no "header" frame is created. 

If the fragment HEADER_FRAME is not defined, and the policy is set, then
the "standard" header is used as the contents of the "header" frame.  
In other words "standard" header is promoted from the "main" frame into 
its own "header" frame.

Note:	For HTML footers the fragment FOOTER_FRAME is used, and 
	the policy [[BR]] [[goto "use main footer in footer frame"]] is tested.


Using policies to control the frame structure
---------------------------------------------
A large number of policies influence frames generation.  These are
described more fully in the [Policy Manual].

      _general_

	[[goto Place document in frames]]
	[[goto Output frame name]]

	[[goto Add Frame border]]

	[[goto New frame link window name]]
	[[goto Open frame links in new window]]

      _contents frame_

	[[goto Add contents frame if possible]]

	[[goto Add NOFRAMES links]]
	[[goto NOFRAMES link URL]]

	[[goto Number of levels in contents frame]]

	[[goto Contents Frame width]]
	[[goto Contents frame background colour]]
	[[goto Contents frame text colour]]

      _main frame_

	[[goto First frame page number]]

A number of [[GOTO file generation policies"]] affect the main frame's
appearance, including :-

	[[goto "Split level"]] [[BR]]
	[[goto "Min HTML File size"]] [[BR]]
	[[goto "Add navigation bar"]] [[BR]]

      _header and footer frames_

	[[goto Use main header in header frame]]
	[[goto Header Frame depth]]
	[[goto Header frame background colour]]
	[[goto Header frame text colour]]

	[[goto Use main footer in footer frame]]
	[[goto Footer Frame depth]]
	[[goto Footer frame background colour]]
	[[goto Footer frame text colour]]


Using HTML fragments to override frame contents
-----------------------------------------------
[[goto Using HTML fragments, HTML fragments]] were introduced in version 4 as a means of allowing
users to customize some the HTML generated by the software.  This 
feature is heavily used in frames generation.

The fragment names used in frames production includes

$_$_BEGIN_TABLE
      HEADER_FRAME	If defined, this fragment is used as the
			contents of a header frame at the top of the screen

      FOOTER_FRAME	If defined, this fragment is used as the 
			contents of a footer frame at the bottom of the
			screen

      CONTENTS_FRAME	If defined, this fragment is used as the contents
			of the "contents" frame on the left of the screen.
			If not defined the "contents" frame will contain a 
			generated contents list

      MAIN_FRAME_FOOTER If defined, this fragment is used as the
      			HTML footer of each page that appears in the 
			main frame, overriding any HTML_FOOTER or value
			defined via policy file.

      MAIN_FRAME_HEADER If defined, this fragment is used as the
      			HTML header of each page that appears in the 
			main frame, overriding any HTML_HEADER or value
			defined via policy file.
$_$_END_TABLE

Other HTML fragments may have an effect.  For example :-

$_$_BEGIN_TABLE
      START_TOC		A fragment to be output before any generated
			table of contents.  If not defined the default 
			behaviour is to output the title "Table of Contents"

      END_TOC		A fragment to be output after any generated table
			of contents.  If not defined the default behaviour
			is to simply put out a horizontal rule <HR>
$_$_END_TABLE

See also [[goto Using HTML fragments]]


NOFRAMES tag and NOFRAMES link
------------------------------
There are several reasons why providing a non-frames alternative to your
pages is a good idea.  These include

      - Not all browsers support frames.  This is rarer these days, but there
        are still people who use text-based or non-visual browsers that can 
        get confused by frames.

      - Not all people like frames.  This is understating it, as many people
        *loathe* frames.  This is because frames pages are hard to bookmark
        and the navigation can confuse some people.

      - Many search engines won't access the HTML pages used inside frames.
      	This means your pages will go un-indexed, making it hard for people
        to find them.

To help with these problems the software supplies a <NOFRAMES> tag
in the main <FRAMESET> document, and a visible "NOFRAMES" hyperlink
in the contents frame.

The "NOFRAMES" hyperlink
........................
The program can place a hyperlink in the contents frame.  This link
is labelled "NOFRAMES" and will link to the first main page.  This
will allow users who don't like frames to view your pages in a non-frames
window.  You can control this link to a limited extent using policies.

See also [[goto Using policies to control the frame structure]]

The <NOFRAMES> tag
..................
HTML provides a tag whose contents is displayed to any browser
that doesn't support the <FRAMESET> tag.  The program will automatically
generate a <NOFRAMES> tag that displays a message saying the page 
requires frames, and offering a link to the first main page.  This
will allow users with non-frames browsers, and search engines to access
your main pages.

Generating frames and non-frames versions
.........................................
You should consider whether or not your pages are suitable for both
frames and non-frames viewing.  If they are, then you can use the first
page displayed in the main frame as your NOFRAMES hyperlink target.  This
is, in fact, the default behaviour.

There are a number of reasons that you might want to maintain two sets
of pages :-

      - You don't want to have the non-frames version split into as many small
        pages as the frames version (different [[goto "Split level"]]
        policy v