$_$_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 values) - You want to place different headers and footers on the two versions to allow for different methods of navigation. If you do want two sets of files, simply convert the file twice with and without frames generation selected. You can either move the files into different directories, or change the output filename for one of the sets. Other than these changes you should be able to use the same policy file. If you create two sets of files, make sure you set the [[goto NOFRAMES link URL]] policy to point to the first non-frames HTML page. $_$_HELP_CHAPTER 2,"Placing your HTML output on the clipboard" $_$_HELP_SUBJECT "Using the clipboard" Outputting HTML to the clipboard ================================ $_$_HELP_TOPIC_ID ID_CLIPBOARD You can use the Conversion Type to select the option of placing the generated HTML onto the Windows clipboard, ready for use in other Windows applications. In this case the HTML generated will omit the <HTML>, <HEAD> and <BODY> tags as these are not suitable when pasting into an existing HTML document. Using AscToHTM in this way can be a very powerful technique which allows you to merge converted HTML with more traditionally authored content. This approach becomes even more powerful if you use a Clipboard extender like ClipMate to remember and organise everything to the clipboard. You could convert a few files, and then use Clipmate to recall the pasted HTML at your leisure for insertion into your other HTML. ClipMate is produced by ThornSoft and can be downloaded from their website at http://www.thornsoft.com/ $_$_HELP_CHAPTER 1,"Using policy files" Using policy files ****************** $_$_HELP_TOPIC_ID ID_POLICY_FILES Document policies have two main uses; to correct any failure of analysis that AscToHTM makes, and to tell the program how to produce better HTML in ways that couldn't possibly be inferred from the original text. Examples of the former may include specifying a nominal page width, and stating whether or not underlined section headings are expected etc. Examples of the latter include adding colour and titles to the page, as well as requesting that a large document is split into several pages. $_$_HELP_CHAPTER 2,"What are policy files?" $_$_HELP_SUBJECT "Introduction" What are Policy files? ====================== $_$_HELP_TOPIC_ID ID_DEFINEPOLICYFILES AscToHTM has a large number of options available to influence the analysis of your text files, and the output to HTML. These options are called "policies" as they govern how the source file should be interpreted and converted. Policies may be saved in text files, known as policy files. These files have a ".pol" extension by default. The policy files are usually updated by changing the policies and saving the changes in a new file. Because they are text files you can also edit them directly, in a text editor. The files have the format of one policy per line of Text in the form $_$_BEGIN_PRE PolicyText : <policy value> $_$_END_PRE The use of policy files allow a given set of options to be saved and reused for other conversions, or later conversions of the same file. $_$_HELP_CHAPTER 2,"Policy Names, values and scope" $_$_HELP_SUBJECT "Introduction" Policy Name, values and scope ============================= This section discusses the following - [[goto Policy Names and descriptions]]. How policies are named - [[goto Policy values]]. The various types of values policies can have - [[goto Policy scope]]. How policies value "scope" within the conversion. Some policies can be assigned different values at different times, others can't. Policy Names and descriptions ----------------------------- Each policy has a name, which also acts as a short description. This description is used in the policy files, and must be matched *exactly* in the policy file if the policy is to be recognised. This means that if the policy text is misspelt, then you must normally match the misspelling. However there is an exception to this rule see [[goto British and American spellings of Colour]] British and American spellings of Colour ........................................ Although the program is developed by a British Author, as far as possible I've tried to support use of British and American English in the policy names. So, for example, the word "colour" may usually be spelt "color" in policies such as :- Policy values ------------- Each policy has a data value. The type of values a policy can take will vary from policy to policy. For most policies the special value "(none)" will be accepted, meaning that this policy should be ignored and/or assigned a suitable default value. Yes/No policy values .................... The commonest type of data value is simple a "Yes/No" value. That is the value is either "Yes" or "no". In practice only the first letter is required. For backwards compatibility the values "true" and "false" may also be used. Numerical policy values ....................... Many policy values require numeric values. Sometimes the value will be constrained, e.g. must be positive, or it must lie within a certain range. Values that lie outside the accepted range will be reported in error, and the policy will be ignored. Text policy strings ................... Many policies are simple text strings, e.g. the Title of the HTML pages being produced. In such cases the whole value will be used, but any spaces before or after the value will be ignored. HTML colour policies .................... Some policies accept colour values. These values should be HTML colours which - for example - may be placed in the various attributes of the <BODY> tag. You can enter any value acceptable to HTML. Normally a value is expressed as a 6-digit hexadecimal value in the range 000000 (black) to FFFFFF (white), but certain colours such as "white", "blue", "red" etc may also be recognised by HTML. The program simply transcribes your value into the output file. A value of "none" signals the defaults are to be used. By default AscToHTM changes the background colour to be white (the true HTML default is a light gray whose value is "C0C0C0"). Section/Heading levels ...................... Some policies require section or heading level values. The program numbers heading levels as follows :- $_$_BEGIN_TABLE Heading level Type of heading ---------------------------------------- 1 Chapter headings 2 Major sections 3 sub-sections 4 sub-sub-sections $_$_END_TABLE In a document with numbered sections "1" would be a chapter, "1.2" a major section, "1.2.3" a sub-section and "1.2.3.4" a sub-sub-section etc. In documents with underlined sections the heading level is determined by the underlining character. $_$_BEGIN_TABLE Chapters '*' Major sections '+','=' or'/' Sub-sections '-','_' or '~' Sub-sub-sections '.' $_$_END_TABLE Lists of names .............. A few policies require a list of named values. In such cases the values are either :- - *space-separated*. Each value should contain no white-space characters, but may contain underscores etc. - *Comma-separated*. Each value should be separated by a comma. The values may contain white-space. If they also include a comma then place the value in double quotes. Policy scope ------------ Each policy has its own scope. Policies are scoped in two different ways:- - *Analysis or Output*. Policies may apply to the analysis of the input text or the generation of the output files. - *Fixed or Dynamic*. A _Fixed_ policy may not be varied during the conversion of the file, that is it is applied equally to all parts of the file being converted. A _Dynamic_ policy may be changed a number of times during the conversion (by embedding changes of values in the source document itself). This can be used to alter the conversion process locally in different parts of the file. Dynamic policies can be made to have different values at different points in the document by using the [[goto Pre-processor command: CHANGE_POLICY, CHANGE_POLICY]] pre-processor command. $_$_SECTION MAKINGRTFHELP In this section:- - [[goto Dynamic analysis policy]] - [[goto Dynamic output policy]] - [[goto Fixed analysis policy]] - [[goto Fixed output policy]] $_$_SECTION ALL Dynamic analysis policy ....................... Dynamic analysis policies are policies that affect the analysis of the file, that may be varied during the processing of the file. This is achieved by embedding new values in the file itself (see 3.4) For example adding the line(s) $_$_BEGIN_PRE $_$_CHANGE_POLICY Look for short lines : no ... $_$_CHANGE_POLICY Look for short lines : yes $_$_END_PRE uses the policy [[goto look for short lines]] to prevent the software looking for short lines for the enclosed part of the document. Dynamic output policy ..................... Dynamic output policies are policies that affect the generation of the output file(s) that may be varied during the processing of the file. This is achieved by embedding new values in the file itself (see 3.4) For example adding the lines $_$_CHANGE_POLICY Recognised USENET groups : (none) $_$_BEGIN_PRE uk.railways $_$_CHANGE_POLICY Recognised USENET groups : uk $_$_CHANGE_POLICY Recognised USENET groups : uk uk.railways $_$_CHANGE_POLICY Recognised USENET groups : (none) $_$_END_PRE to your source uses the policy [[goto Recognised USENET groups]] to switch on the recognition of "uk.railways" as a newsgroup for a few lines, where this is normally disabled by default. Fixed analysis policy ..................... Fixed analysis policies are policies that affect the analysis of the file, and that may not be varied during the processing of the file, usually because what they describe should apply to the whole file. For example the indentation pattern used in the file is usually fixed in this way. Fixed output policy ................... Fixed output policies are policies that affect the generation of the output file, and that may not be varied during the processing of the file, usually because they must be consistent, or because they're output near the top of the document. For example the [[goto Active Link Colour]] is put in the <HEAD> portion of the HTML file, and cannot be varied throughout the file. $_$_HELP_CHAPTER 2,"Ways of specifying policy values" Ways of specifying policy values ================================ You can specify policies in a number of different ways used separately or in combination. Placing policies in a "policy file" ----------------------------------- One of the more useful ways to use policies is to save them to a "policy file", which you can then later reload. In this way your customizations for a particular document or type of document can be saved and reused. Saving and loading policy files ............................... The program allows you to save policies to file so that you can later reload them. This allows you to easily define different ways of doing conversions, either for different types of files, or to produce different types of output. The policy files have a .pol extension by default, and are simple text files, with one policy on each line. You can, if you wish, edit these policies in a text editor... this is sometimes easier that using all the dialogs in the Windows version. When editing policies, it is important not to change the key phrase (the bit before the ":" character), as this needs to be matched exactly by the program. For best results, it is advisable to put in your policy file only those policies you want to fix. This leaves the program to calculate document-by-document policies that suit the files being converted. Note: Avoid using "full" policy file for your conversions. Such files prevent the program from adjusting to each source file, often leading to unwanted results. Creating policy files for your document ....................................... The normal way to create a policy file is by setting options and them saving them using the "save policy file" dialog. This will offer you the choice of creating [[popup partial policy files]] or [[popup full policy files]]. Alternatively, you can set the [[goto "Output policy file"]] policy or the /POLICY=<file> command line qualifier which will generate a full policy file resulting from the analysis of the converted document. Once a file is generated you can either edit it in a text editor - deleting policies that are of little interest to you, and editing those that are - or reload them into the program, change them and save them again. Partial policy files .................... Partial policy files are files which have values for some, not all, policies. These are recommended, because the it leaves AscToHTM free to adjust all the other policies not set in the file, allowing it to adapt to the details of the document being concerned. For example, you should only set the indentation policy if you *know* what indents you are using, or if you want to override those calculated by AscToHTM. Normally it is best to omit this policy, and allow AscToHTM to work it out itself. When you save a policy file from inside AscToHTM, a partial policy file will contain - all policies loaded from the current policy file (if any) - all policies changed in AscToHTM during the current session (if any) Full policy files ................. A "full" policy file contains a value for almost every possible policy. NOTE: Such files are usually only useful for documentation and analysis reasons, and should *almost never* be expected to be reloaded as input into a conversion, as this would totally fix the conversion details. Changing policies via the user interface ---------------------------------------- In the Windows version of the program many (but not all) policies can have their values changed via options available from the _"Conversion Options"_ menu. Changing policies by using command line options ----------------------------------------------- A small number of policies can be set from the command line. These include $_$_BEGIN_TABLE Command line Equivalent policy ----------------------------------------------------------------------- /CONTENTS [[goto Add contents list]] $_$_SECTION MERRILL /CU [[goto Input file is a composition unit]] $_$_SECTION ALL /DOS [[goto Use DOS filenames]] /FRAMES [[goto Place document in frames]] /INDEX[=filename] [[goto Make Directory]] /LIST[=filename] [[goto Generate diagnostics files]] /POLICY[=filename] [[goto Output policy file]] /SILENT [[goto Display messages]] /SIMPLE [[goto Keep it simple]] $_$_SECTION MERRILL /TAGS [[goto Show Tags in output]] $_$_SECTION ALL $_$_END_TABLE Changing policies by using preprocessor directives -------------------------------------------------- A number of policies have equivalent preprocessor directives. These directives are special keywords and values placed in your source text at some point to influence the conversion at that point, or from that point onwards. See [[goto Using the pre-processor]] for full details. Directives all begin with the text "$_$_" followed by the keyword placed at the start of a line. The directive appears on a line by itself, and the rest of the line is interpreted as the directive's data value. NOTE: The "$_$_" must be at the start of the line, otherwise it will be ignored. In addition to individual directives, the [[popup Pre-processor command: CHANGE_POLICY,CHANGE_POLICY]] directive can be used to embed policy changes into your document to apply from that point onwards. Changing policies by editing a Policy file ------------------------------------------ All policies can be changed by editing the policy file directly, and a few policies can *only* be changed in this manner, as they are not supported by the user interface (see [[goto Policies that need to be added manually]]). Policy file are plain text files with one policy per line in the form $_$_BEGIN_PRE <policy_name> : <policy_value> $_$_END_PRE Comments and blank lines are permitted in the policy file, and if the file was created by AscToHTM then "[Section Names]" are shown as well. These section names are only there for your convenience, and have no effect on the parsing of the policy file. Policy lines may be placed in the file in any order, and for the most part shouldn't be repeated. When editing a policy line, you must use the exact name as listed in the [[goto Alphabetical list of policies available in AscToHTM]]in order for the policy to be correctly recognised. Any policy name that doesn't match will lead to an error message being displayed in the Status Window when the policy file is loaded. Once you have edited the policy file, you should save your changes and then re-run AscToHTM and tell it the name of the policy file to use. Here's an example policy file $_$_BEGIN_PRE [File generation] Split level : 1 Add navigation bar : Yes [Style] Document Style Sheet : manual.css $_$_END_PRE $_$_HELP_CHAPTER 2,"Generating a policy file for your document" $_$_HELP_SUBJECT "How to create a policy file" Generating a policy file for your document ========================================== The normal way to create a policy file is by setting options and them saving them using the "save policy file" dialog. This will offer you the choice of creating a [[goto Partial policy files, partial policy file]] or a [[goto full policy files, full policy file]] Alternatively, you can set the [[goto "Output policy file"]] policy which will generate a full policy file resulting from the analysis of the converted document. Once a file is generated you can either edit them in a text editor - deleting policies that are of little interest to you, and editing those that are - or reload them into the program, change them and save them again. Naming policy files ------------------- Whenever the [[goto "Output policy file"]] policy is set the generated "full" policy file is usually called <filename>.pol where <filename> is the name of the file being created. When this happens any existing file of that name will be overwritten. For this reason we *strongly* advise you adopt a naming convention of the form in_<filename>.pol or i<filename>.pol or place your input policies in a different directory and ensure they are backed up. $_$_HELP_CHAPTER 1,"Policies supported by AscToHTM" Policies supported by AscToHTM ****************************** This chapter details all the policy options supported by AscToHTM. There is an [[goto Alphabetical list of policies available in AscToHTM]] available. The policies themselves are grouped together according to the area of functionality they support as follows :- [[goto Analysis policies]][[br]] [[goto "'What to look for' policies"]][[br]] [[goto General analysis policies]][[br]] [[goto Bullet policies]][[br]] [[goto Contents list policies]][[br]] [[goto File structure policies]][[br]] [[goto Headings policies]][[br]] [[goto Pre-formatted text policies]][[br]] [[goto Table analysis policies]][[br]] [[goto Output policies]][[br]] [[goto Added HTML policies]][[br]] [[goto Advanced HTML policies]][[br]] [[goto Colour policies]][[br]] [[goto CSS policies]][[br]] [[goto Directory page policies]][[br]] [[goto File generation policies]][[br]] [[goto File splitting policies]][[br]] [[goto Font policies]][[br]] [[goto Frames policies]][[br]] [[goto Hyperlink policies]][[br]] [[goto Pre-processor policies]][[br]] [[goto Style policies]][[br]] [[goto Table generation policies]][[br]] [[goto Configuration file policies]][[br]] [[goto Other policies]][[br]] [[goto Settings policies]][[br]] [[goto Policies set elsewhere in the user interface]][[br]] [[goto Policies that need to be added manually]][[br]] $_$_HELP_CHAPTER 2,"Complete alphabetical list of policies available in AscToHTM" $_$_HELP_SUBJECT "Complete list of policies" Alphabetical list of policies available in AscToHTM =================================================== The following is a list of all the policies supported by this version of AscToHTM:- $_$_BEGIN_DELIMITED_TABLE $_$_TABLE_HEADER_COLS 0 Policy name Default value GUI location ----------------------------------------------------------------------------------------------- [[popup Active Link Colour]] "" [[goto Colour policies]] [[popup Add <BR> to lines with URLs]] No [[goto Hyperlink policies]] [[popup Add contents frame if possible]] Yes [[goto Frames policies]] [[popup Add contents list]] No [[goto Contents List policies]] [[popup Add emphasis and bold markup]] Yes [[goto Style policies]] [[popup Add Frame border]] Yes [[goto Frames policies]] [[popup Add mail headers to contents list]] Yes [[goto Contents List Policies]] [[popup Add navigation bar]] No [[goto File Splitting policies]] [[popup Add NOFRAMES links]] Yes [[goto Frames policies]] [[popup Allow automatic centring]] No [[goto Style policies]] [[popup Allow definitions inside PRE]] Yes [[goto Pre-processor policies]] [[popup Allow email beginning with numbers]] No [[goto Hyperlink policies]] [[popup Attempt TABLE generation]] Yes [[goto Table analysis policies]] [[popup Author URL]] "" [[goto Added HTML policies]] [[popup Automatic centring tolerance]] 2 [[goto Style policies]] [[popup Background Colour]] "" [[goto Colour policies]] [[popup Background Image]] "" [[goto Added HTML policies]] [[popup Base FONT Size in pts]] 10 (deprecated) [[popup Bookmark URL]] "" [[goto Added HTML policies]] [[popup Break up long HTML lines]] Yes [[goto File generation policies]] [[popup Bullet char]] "" [[goto Bullet policies]] [[popup Center first heading]] No [[goto Headings policies]] [[popup Character encoding]] "" [[goto Advanced HTML policies]] [[popup Check domain name syntax]] Yes [[goto Hyperlink policies]] [[popup Check indentation for consistency]] Yes [[goto Headings policies]] [[popup Colour data rows]] No [[goto Table Generation Policies]] [[popup Column boundaries have zero width]] No [[goto Table analysis policies]] [[popup Column merging factor]] 5 [[goto Table analysis policies]] [[popup Comment generation code]] 0 [[goto Advanced HTML policies]] [[popup Contents frame background colour]] "" [[goto Frame colours dialog]] [[popup Contents frame text colour]] "" [[goto Frame colours dialog]] [[popup Contents Frame width]] 0 [[goto Frames policies]] [[popup Contents style code]] 0 [[goto Policies that need to be added manually]] [[popup Convert TABLE X-refs to links]] No [[goto Table Generation Policies]] [[popup Copyright URL]] "" [[goto Added HTML policies]] [[popup Could be blank line separated]] Yes [[goto Table analysis policies]] [[popup Create FTP links]] Yes [[goto Hyperlink policies]] [[popup Create Gopher links]] Yes [[goto Hyperlink policies]] [[popup Create hyperlinks]] Yes [[goto Hyperlink policies]] [[popup Create mailto links]] Yes [[goto Hyperlink policies]] [[popup Create NEWS links]] Yes [[goto Hyperlink policies]] [[popup Create Telnet links]] Yes [[goto Hyperlink policies]] [[popup Cross-refs at level]] 2 [[goto Hyperlink policies]] [[popup Default Font]] "Times New Roman,,10" [[goto Font policies]] [[popup Default TABLE alignment]] (none) [[goto Table Generation Policies]] [[popup Default TABLE border colour]] "" [[goto Table Generation Policies]] [[popup Default TABLE border size]] 0 [[goto Table Generation Policies]] [[popup Default TABLE caption]] "" [[goto Policies that need to be added manually]] [[popup Default TABLE cell alignment]] (none) [[goto Table Generation Policies]] [[popup Default TABLE cell padding]] 2 [[goto Table Generation Policies]] [[popup Default TABLE cell spacing]] 2 [[goto Table Generation Policies]] [[popup Default TABLE colour]] "" [[goto Table Generation Policies]] [[popup Default TABLE delimiter character]] "" [[goto Policies set elsewhere in the user interface]] [[popup Default TABLE even row colour]] E0F0E0 [[goto Table Generation Policies]] [[popup Default TABLE header cols]] 0 [[goto Policies that need to be added manually]] [[popup Default TABLE header rows]] 0 [[goto Table Generation Policies]] [[popup Default table html attributes]] "" [[goto Table Generation Policies]] [[popup Default table html cell attributes]] "" [[goto Table Generation Policies]] [[popup Default TABLE layout]] "" [[goto Table analysis policies]] [[popup Default TABLE odd row colour]] F0F0F0 [[goto Table Generation Policies]] [[popup Default TABLE width]] "" [[goto Table Generation Policies]] [[popup Definition char]] '-' (weak) [[goto General analysis policies]] [[popup Definitions file]] "" [[goto Configuration file Policies]] [[popup Delta FONT size in pts]] 0 (deprecated) [[popup Directory Description]] "" [[goto Directory Page Policies]] [[popup Directory filename]] "" [[goto Directory Page Policies]] [[popup Directory footer file]] "" [[goto Directory Page Policies]] [[popup Directory header file]] "" [[goto Directory Page Policies]] [[popup Directory Keywords]] "" [[goto Directory Page Policies]] [[popup Directory return hyperlink text]] "Directory" [[goto Directory Page Policies]] [[popup Directory Script file]] "" [[goto Directory Page Policies]] [[popup Directory Title]] "" [[goto Directory Page Policies]] [[popup Display messages]] Yes [[goto Settings Policies]] [[popup Document Base URL]] "" [[goto Advanced HTML policies]] [[popup Document Description]] "" [[goto Added HTML policies]] [[popup Document Keywords]] "" [[goto Added HTML policies]] [[popup Document Style Sheet]] "" [[goto CSS policies]] [[popup Document Title]] "" [[goto Added HTML policies]] [[popup DOS filename root]] "" [[goto File generation policies]] [[popup Error reporting level]] 5 [[goto Settings Policies]] [[popup Expect alphabetic bullets]] Yes [[goto Bullet policies]] [[popup Expect blank lines between paras]] Yes [[goto General analysis policies]] [[popup Expect Capitalised Headings]] Yes [[goto Headings policies]] [[popup Expect code samples]] No [[goto File Structure policies]] [[popup Expect Contents List]] Yes [[goto Contents List policies]] [[popup Expect embedded Headings]] Yes [[goto Headings policies]] [[popup Expect multiple COLSPAN values]] No [[goto Table analysis policies]] [[popup Expect Numbered bullets]] Yes [[goto Bullet policies]] [[popup Expect Numbered Headings]] Yes [[goto Headings policies]] [[popup Expect Roman Numeral bullets]] Yes [[goto Bullet policies]] [[popup Expect Second Word Headings]] No [[goto Policies that need to be added manually]] [[popup Expect sparse tables]] No [[goto Table analysis policies]] [[popup Expect Underlined Headings]] Yes [[goto Headings policies]] [[popup External contents list filename]] "" [[goto Contents List policies]] [[popup First frame page number]] 1 [[goto Frames policies]] [[popup First Section Number]] 1 [[goto Policies that need to be added manually]] [[popup Fixed Font]] "Courier,,8" [[goto Font policies]] [[popup Footer frame background colour]] "" [[goto Frame colours dialog]] [[popup Footer Frame depth]] 0 [[goto Frames policies]] [[popup Footer frame text colour]] "" [[goto Frame colours dialog]] [[popup Fragments file]] "" [[goto Configuration file Policies]] [[popup Generate diagnostics files]] No [[goto File generation policies]] [[popup Generate external contents file]] No [[goto Contents List policies]] [[popup Hanging paragraph position(s)]] 0 [[goto General analysis policies]] [[popup Header frame background colour]] "" [[goto Frame colours dialog]] [[popup Header Frame depth]] 0 [[goto Frames policies]] [[popup Header frame text colour]] "" [[goto Frame colours dialog]] [[popup Heading Font]] "Arial,,10" [[goto Font policies]] [[popup Heading key phrases]] "" [[goto Headings policies]] [[popup Headings Colour]] "" [[goto Style policies]] [[popup Highlight Definition Text]] No [[goto Style policies]] [[popup HTML footer file]] "" [[goto Advanced HTML policies]] [[popup HTML header file]] "" [[goto Advanced HTML policies]] [[popup HTML Script file]] "" [[goto Advanced HTML policies]] [[popup Hyperlinks on numbers]] No [[goto Contents List policies]] [[popup Ignore multiple blank lines]] No [[goto Style policies]] [[popup Ignore table header during analysis]] No [[goto Table analysis policies]] [[popup Include document section(s)]] (none) [[goto Pre-processor policies]] [[popup Indent headings in Directory]] Yes [[goto Directory Page Policies]] [[popup Indent position(s)]] 0 [[goto General analysis policies]] [[popup Input file contains DOS characters]] No [[goto File Structure policies]] [[popup Input file contains Japanese characters]] No [[goto File Structure policies]] [[popup Input file contains Mime encoding]] No [[goto File Structure policies]] [[popup Input file contains PCL codes]] No [[goto File Structure policies]] [[popup Input file contains UNICODE characters]] No [[goto File Structure policies]] [[popup Input file has change bars]] No [[goto File Structure policies]] [[popup Input file has page markers]] No [[goto File Structure policies]] [[popup Input file is double spaced]] No [[goto File Structure policies]] [[popup Keep it simple]] No [[goto File Structure policies]] [[popup Keep original table lines in output]] No [[goto Table Generation Policies]] [[popup Largest allowed <Hn> tag]] 2 [[goto Style policies]] [[popup Lines to ignore at end of file]] 0 [[goto File Structure policies]] [[popup Lines to ignore at start of file]] 0 [[goto File Structure policies]] [[popup Link Dictionary file]] "" [[goto Configuration file Policies]] [[popup Look for *this* and _that_ emphasis]] Yes [[goto 'What to look for' policies]] [[popup Look for bullets]] Yes [[goto 'What to look for' policies]] and [[goto Bullet policies]] [[popup Look for character encodings]] Yes [[goto 'What to look for' policies]] [[popup Look for diagrams]] Yes [[goto 'What to look for' policies]] [[popup Look for hanging paragraphs]] Yes [[goto 'What to look for' policies]] [[popup Look for horizontal rulers]] Yes [[goto 'What to look for' policies]] [[popup Look for indentation]] Yes [[goto 'What to look for' policies]] [[popup Look for MAIL and USENET headers]] Yes [[goto 'What to look for' policies]] [[popup Look for preformatted text]] Yes [[goto 'What to look for' policies]] [[popup Look for quoted text]] Yes [[goto 'What to look for' policies]] [[popup Look for short lines]] Yes [[goto 'What to look for' policies]] [[popup Look for underlined text]] Yes [[goto 'What to look for' policies]] [[popup Look for white space]] Yes [[goto 'What to look for' policies]] [[popup Make Directory]] No [[goto Directory Page Policies]] [[popup Max length of candidate table lines]] 256 [[goto Table analysis policies]] [[popup Max length of heading links]] 0 [[goto Hyperlink policies]] [[popup Maximum level to show in contents]] 0 [[goto Contents List policies]] [[popup Maximum number of files per index page]] 0 [[goto Directory Page Policies]] [[popup Min chapter size]] 8 [[goto General analysis policies]] [[popup Min HTML file size]] -1 [[goto File Splitting policies]] [[popup Minimise HTML file size]] No [[goto File Splitting policies]] [[popup Minimum automatic <PRE> size]] -1 [[goto Pre-formatted text policies]] [[popup Minimum ruler length]] 4 [[goto 'What to look for' policies]] [[popup Minimum TABLE column separation]] 1 [[goto Table analysis policies]] [[popup New browser window name]] other [[goto Hyperlink policies]] [[popup New frame link window name]] _top [[goto Frames policies]] [[popup New Paragraph Offset]] -1 [[goto General analysis policies]] [[popup NOFRAMES link URL]] "" [[goto Frames policies]] [[popup Number of levels in contents frame]] 0 [[goto Frames policies]] [[popup Number of words to include in filename]] 1 [[goto File Splitting policies]] [[popup Omit <HEAD> and <BODY> from output]] No [[goto Advanced HTML policies]] [[popup Only allow explicit FTP links]] Yes [[goto Hyperlink policies]] [[popup Only allow pages to be viewed in frames]] Yes [[goto Frames policies]] [[popup Only use known groups]] Yes [[goto Hyperlink policies]] [[popup Open frame links in new window]] Yes [[goto Frames policies]] [[popup Open links in new browser window]] No [[goto Hyperlink policies]] [[popup Output file extension]] [[goto File generation policies]] [[popup Output frame name]] *_frame.html [[goto Frames policies]] [[popup Output policy file]] No [[goto File generation policies]] [[popup Output policy filename]] "" [[goto File generation policies]] [[popup Page marker size (in lines)]] 0 [[goto File Structure policies]] [[popup Page Width]] 80 [[goto General analysis policies]] [[popup Place document in frames]] No [[goto Frames policies]] [[popup Preserve file structure using <PRE>]] No [[goto File generation policies]] [[popup Preserve line structure]] No [[goto File generation policies]] [[popup Preserve New Paragraph Offset]] Yes [[goto General analysis policies]] [[popup Preserve underlining of headings]] Yes [[goto Style policies]] [[popup recognize '-' as a bullet]] Yes [[goto Bullet policies]] [[popup recognize 'o' as a bullet]] Yes [[goto Bullet policies]] [[popup Recognised USENET groups]] "" [[goto Hyperlink policies]] [[popup Search for definitions]] Yes [[goto General analysis policies]] [[popup Short line length]] -1 [[goto General analysis policies]] [[popup Shortcut Icon URL]] "" [[goto Added HTML policies]] [[popup Show file titles in directory]] Yes [[goto Directory Page Policies]] [[popup Smallest allowed <Hn> tag]] 5 [[goto Style policies]] [[popup Split at page markers]] No [[goto File Splitting policies]] [[popup Split level]] -1 [[goto File Splitting policies]] [[popup Suppress all colour markup]] No [[goto Colour policies]] [[popup Suppress INFO messages]] No [[goto Settings Policies]] [[popup Suppress program ERROR messages]] No [[goto Settings Policies]] [[popup Suppress TAG ERROR messages]] No [[goto Settings Policies]] [[popup Suppress URL messages]] Yes [[goto Settings Policies]] [[popup Suppress WARNING messages]] No [[goto Settings Policies]] [[popup TAB size]] 8 [[goto General analysis policies]] [[popup Table extending factor]] 5 [[goto Table analysis policies]] [[popup Table Font]] "Times New Roman,,10" [[goto Font policies]] [[popup Table of contents Font]] "Arial,,10" [[goto Font policies]] [[popup Text Colour]] "" [[goto Colour policies]] [[popup Text command file]] Yes [[goto Configuration file Policies]] [[popup Text justification]] LEFT [[goto File Structure policies]] [[popup Treat each line as a paragraph]] No [[goto File generation policies]] [[popup Unvisited Link Colour]] "" [[goto Colour policies]] [[popup Use <CODE>..</CODE> markup]] No [[goto Policies that need to be added manually]] [[popup Use <DL> markup for defn. paras]] Yes [[goto Style policies]] [[popup Use <EM> and <STRONG> markup]] Yes [[goto Style policies]] [[popup Use <P> markup for paragraphs]] Yes [[goto Style policies]] [[popup Use any existing contents list]] Yes [[goto Contents List policies]] [[popup Use CSS to implement fonts]] Yes [[goto Font policies]] [[popup Use DOS filenames]] No [[goto File generation policies]] [[popup Use first heading as Title]] No [[goto Added HTML policies]] [[popup Use .HTM extension]] No [[goto File generation policies]] [[popup Use first line as heading]] No [[goto Headings policies]] [[popup Use first line as Title]] No [[goto Added HTML policies]] [[popup Use main footer in footer frame]] Yes [[goto Frames policies]] [[popup Use main header in header frame]] Yes [[goto Frames policies]] [[popup Use numbered sequence in file names]] No [[goto File Splitting policies]] [[popup Use Preprocessor]] Yes [[goto Pre-processor policies]] [[popup Visited Link Colour]] "" [[goto Colour policies]] $_$_END_TABLE $_$_BEGIN_IGNORE ! ! Policies not shown, but theoretically supported ... ! ! (tagging) Directive delimiter ! (tagging) Start tag delimiter ! (tagging) End tag delimiter ! (debug) Monitor tag generation ! (deleted) Maximum number of links per index page ! (deleted?) Scope COLOUR tags globally ! (not implemented) CENTER whole document ! (not implemented) Indent whole document ! (command) Concatenate results into one file ! (command) Create a log file ! (command) Output directory ! (command) Output log filename ! (command) Show Tags in output ! (gui) Input directory ! (gui) Input file type ! (headings) We have nn recognised headings ! (implicit/internal) Create embedded style sheet ! (merrill) Add anchors to contents list ! (merrill) Add TABLE WIDTH markup ! (merrill) Avoid tag breaks ! (merrill) Folio block structure ! (merrill) Colour REDLINE sections ! (merrill) Colour tables with DOT_LEADERS ! (merrill) Contents anchors level ! (merrill) HTML version to be targeted ! (merrill) Indentation markup code ! (merrill) Input file is a composition unit ! (merrill) Label style classes ** consider inclusion, or switching to TRUE ** ! ** (needs extending before being switched on ** ! (merrill) List markup code ! (merrill) Remove redundant tags ! (merrill) Rule set to be used ! (merrill) Use of HTML 4.0 entities code ! (merrill) Use of Microsoft entities code ! (merrill) Use percentage widths in tables ! (merrill) Suppress <Hn> markup for headings ! (merrill) Use incremental indentation markup ! (merrill/non-gui) <P> inside list usage code ! (merrill/deprecated) Suppress all font markup ! (merrill/deprecated) Add FONT face markup ! (merrill/deprecated) Add FONT markup ! (merrill/deprecated) Add FONT size markup ! (merrill/deprecated) Add FONT style markup ! (merrill/deprecated) Apply FONT to empty table cells ! (rtf mostly) Font stretch factor (in percent) $_$_END_IGNORE $_$_HELP_CHAPTER 2,"Analysis policies" $_$_HELP_SUBJECT "Introduction" Analysis policies ================= $_$_HELP_TOPIC_ID ID_CONV_POLICIES _Menu location: Configuration Options -> Analysis Policies_ Analysis policies are usually calculated by AscToHTM by making a first pass through your document. The resulting policies are then used during the second, conversion pass to categorise all input lines so that they may be correctly converted to HTML. You should only need to change these policies should the analysis fail. - [[goto 'What to look for' policies]] - [[goto bullet policies,Bullets]] - [[goto Contents List Policies,Contents]] - [[goto File Structure policies,File generation]] - [[goto Headings Policies]] - [[goto General analysis policies,General Analysis]] - [[goto Pre-formatted text policies,Pre-formatted text]] - [[goto Table analysis policies,Table analysis]] $_$_HELP_CHAPTER 3,"What to look for" policies $_$_HELP_SUBJECT "List of 'look for' policies" 'What to look for' policies --------------------------- $_$_HELP_TOPIC_ID HIDD_LOOKFOR _Menu location: Configuration Options -> Analysis Policies -> What to look for_ These policies act as "broad stroke" policies enabling or disabling areas of functionality within the software by telling it what to look for and to try to detect. For example you can tell the program whether or not to bother looking for patterns of indentation, bullets, or numbered lists. In many cases if you enable a policy you can further fine tune the conversion details on other policy sheets. - [[popup Look for indentation]] - [[popup Look for white space,Look for paragraphs]] - [[popup Look for hanging paragraphs]] - [[popup Look for short lines]] - [[popup Look for horizontal rulers]] - [[popup Minimum ruler length]] - [[popup Look for bullets and numbered lists]] - [[popup Look for definitions]] - [[popup Look for quoted text]] - [[popup Look for *this* and _that_ emphasis,Look for emphasis]] - [[popup Look for underlined text]] - [[popup Look for mail and USENET headers]] - [[popup Look for character encodings]] - [[popup Look for preformatted text,Look for regions of preformatted text]] - [[popup Look for diagrams]] Look for indentation .................... $_$_HELP_TOPIC_ID ID_LOOKFOR_INDENTS _Menu location: Configuration Options -> Analysis Policies -> What to look for_ AscToHTM can attempt to detect the indentation pattern of your document and replicate it in the output file. If you chose to disable this policy, all your text will be output with no indentations at all. If the program is wrongly indenting your files, you can try adjusting the pattern of indentation on the [[goto General analysis policies,General Analysis]] tabbed policy sheet. Look for white space .................... $_$_HELP_TOPIC_ID ID_LOOKFOR_PARAS _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will attempt to look for paragraphs in your source. Usually this is signaled by a blank line between paragraphs, a leading indent on the first line of each paragraph, or (in extreme cases) a short line at the end of a paragraph. If you don't want AscToHTM to detect paragraphs, disable this policy. If AscToHTM is wrongly detecting paragraphs, try adjusting the paragraph analysis policies on the [[goto General analysis policies,General Analysis]] tabbed policy sheet. Look for hanging paragraphs ........................... _(New in version 5.0)_ _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will attempt to look for paragraphs whose first line is offset relative to the rest of the paragraph. Where this happens, lines at different indentations will be treated as a single paragraph. Where this fails to happen a first line of a paragraph may be treated as a separate indented paragraph. If you don't want AscToHTM to detect these offsets, disable this policy. See the discussion in [[goto Hanging paragraph indent detection]] See also [[popup hanging paragraph position(s)]] Look for short lines .................... $_$_HELP_TOPIC_ID ID_LOOKFOR_SHORTLINES _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will attempt to detect short lines and preserve their structure by adding a line break. Disabling this will cause short lines to be merged into the surrounding paragraph's text. If AscToHTM is wrongly handling your short lines, you can adjust the short line cutoff point or the page width (which is used in short line detection) in the Sizes section of the [[goto General analysis policies,General Analysis]] tabbed policy sheet. Look for horizontal rulers .......................... $_$_HELP_TOPIC_ID ID_LOOKFOR_RULES _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will treat a series of hyphens, minus signs, equal signs on the same line as a horizontal rule. (On occasion it might be regarded as underlining a heading on the previous line). You can disable this is you wish, or you can specify how many "line" characters it takes to make a horizontal rule. Minimum ruler length .................... _Menu location: Configuration Options -> Analysis Policies -> What to look for_ Specifies the minimum length of any line to be considered as a horizontal rule when the program is looking for such lines (see [[GOTO "Look for horizontal rulers"]]) Lines in the source text that consist only of "rule-like" characters, and which exceed this minimum length will be marked up as Rules, rather than as the original character sequence. Look for bullets and numbered lists ................................... $_$_HELP_TOPIC_ID ID_LOOKFOR_BULLETS _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will try to detect bullet points and numbered lists. This can sometimes go wrong if you have lines that look to the program like bullet points. You can disable this behaviour should you wish. Alternatively you can fine tune the detection of bullets on the [[goto bullet policies,"bullet analysis"]] tabbed policy sheet. Look for definitions .................... $_$_HELP_TOPIC_ID ID_LOOKFOR_DEFINITIONS _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will try to detect definitions and notes, usually in the form of a single word and a hanging paragraph. This can often go wrong, so you can use this policy to disable this feature. Look for quoted text .................... $_$_HELP_TOPIC_ID ID_LOOKFOR_QUOTES _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will try to identify "quoted" lines. Quoted lines are lines that have had a single character (often ">" or "!") inserted at the start. This is common practice when quoting email in a reply. AscToHTM places such text in italics. You can disable this behaviour should you wish. Look for *this* and _that_ emphasis ................................... _Menu location: Configuration Options -> Analysis Policies -> What to look for_ AscToHTM will try to look for text that has been marked up with underscores and asterisks to signify bold an italic text. For example $_$_CHANGE_POLICY Look for *this* and _that_ emphasis : no *This is bold* and _this is italic_ $_$_CHANGE_POLICY Look for *this* and _that_ emphasis : yes becomes *This is bold* and _this is italic_ _This appears on-screen as "Look for emphasis"_ Look for underlined text ........................ _Menu location: Configuration Options -> Analysis Policies -> What to look for_ AscToHTM will try to detect where a line of text has been "underlined" by following it by a same length row of dashes, hyphens, equal signs etc. This text will then be regarded as a candidate for being an underlined heading or - if those are not allowed - underlined text. If you have tables and reports, you may want to switch this policy off since the line at the end of a table may appear to under- or over-line the last line of text in the table. Look for mail and USENET headers ................................ $_$_HELP_TOPIC_ID ID_LOOKFOR_MAILHEAD _Menu location: Configuration Options -> Analysis Policies -> What to look for_ AscToHTM will try to look for email and USENET headers. Where these are recognised they can be simplified so that only the To, Form and Subject lines are shown in the output. You can disable this behaviour should you wish. Look for character encodings ............................ _Menu location: Configuration Options -> Analysis Policies -> What to look for_ Specifies whether or not the software should attempt to detect alternative character sets, such as those used for languages such as Greek, Turkish, Chinese etc. The software does this by doing a statistical analysis on the characters used in the source file. This process isn't perfect, and when it fails you will need to manually set the correct character set using the [[GOTO Character encoding]] policy. If you find the program is wrongly detecting the character set, disable this policy and/or manually set it using the [[GOTO Character encoding]] policy Look for preformatted text .......................... $_$_HELP_TOPIC_ID ID_LOOKFOR_PREFORM _Menu location: Configuration Options -> Analysis Policies -> What to look for_ By default AscToHTM will try to identify regions of preformatted text. Once identified AscToHTM will try to decide if it's a diagram, table or some other form of preformatted text. If it thinks it's a table it will attempt to place the text in an appropriate table structure. You can disable the search for preformatted text, or if you allow preformatted text, disable table generation. (This may be appropriate if you have a large number of ASCII diagrams in your text). The search for preformatted text can be refined via the [[goto Pre-formatted text policies,Pre-formatted text]] and [[goto Table analysis policies,Table analysis]] tabbed policy sheets. The output of tables can be fine-tuned via the output policy [[goto Table generation policies,Tables]] tabbed policy sheet. Look for diagrams ................. _Menu location: Configuration Options -> Analysis Policies -> What to look for_ Specifies whether or not regions of preformatted text that are detected should be considered as candidate diagrams. Text that contains numbers of characters such as "|", "-", ">" and "<" may be considered to be an ASCII diagram. If you find the program is wrongly treating tables as diagrams then disable this policy. $_$_HELP_CHAPTER 3,"General analysis policies" General analysis policies ------------------------- $_$_HELP_TOPIC_ID HIDD_ANALYSIS _Menu location: Configuration options -> Analysis Policies -> General Layout_ These policies aid AscToHTM's analysis by describing in detail what the contents of the document being converted are *Sizes* - [[popup Page Width]] - [[popup TAB Size]] - [[popup Short line length]] - [[popup Min Chapter Size]] *Paragraphs* - [[popup Expect blank lines between paras,Blank lines between paragraphs]] - [[popup New paragraph offset]] *Definitions* - [[popup Search for definitions,Search for definitions in source text]] - [[popup Hanging paragraph position(s),Definition paragraph indent levels]] - [[popup recognize hyphen characters]] - [[popup recognize colon characters]] - [[popup Definition Char,Other definition characters]] *Layout* - [[popup indent position(s), Indentation levels]] Page Width .......... $_$_HELP_TOPIC_ID ID_PAGEWIDTH _Menu location: Configuration options -> Analysis Policies -> General Layout_ This indicates the width (in characters) of your nominal output page. This width is calculated from the observed line lengths in the original document. This width is used in short line calculation, and determining whether a given line contains a definition term or not (definition character near the start of the line). In documents that contain line feeds this should be automatically detected. In other documents you may need to set this manually. TAB size ........ $_$_HELP_TOPIC_ID ID_TABSIZE _Menu location: Configuration options -> Analysis Policies -> General Layout_ This indicates the size (in characters) of your tabs. AscToHTM converts all tabs to spaces on conversion before analysis. By default a tab size of 8 characters is assumed. The tab size can influence the analysis of paragraph indentations and other layout. Provided they are used consistently there shouldn't be a problem. However where tabs and spaces are used in combination, mistakes can arise. This is particularly true in tables of data. AscToHTM does not expect tab-separated table cells, instead converting the tabs to spaces and analysing the results. If your source document has been created with an editor with a different tab size, you should change this value should you start to experience strange layout conversion problems. Short Line Length ................. $_$_HELP_TOPIC_ID ID_SHORTLINE _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy is used to determine what is a "short line". Short lines are treated specially by AscToHTM by adding a paragraph marker on the end. They can also be used to detect ends of paragraphs in those documents that don't have blank lines between paragraphs. Normally AscToHTM will determine whether or not a line is short by comparing it to the page width, given the current context. The default value is 0 characters (indicating a comparison to Page Width should be used). Set this to any value you like. A value of 80 is likely to make every line in your original document have a <BR> tag on the end. Min Chapter Size ................ $_$_HELP_TOPIC_ID ID_MINCHAPTER _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy tells AscToHTM what the smallest chapter size may be. This is used when trying to determine if a numbered line is a chapter heading. AscToHTM tries to avoid treating numbered lists as a series of small chapters using this policy. The default value is 8 lines. Change this only if you suspect small chapters are being ignored, or large list items are being treated as chapter headings. Expect blank lines between paras ................................ $_$_HELP_TOPIC_ID ID_BLANKLINES _Menu location: Configuration options -> Analysis Policies -> General Layout_ AscToHTM can detect whether or not it should expect blank lines between paragraphs. Documents without blank lines between paragraphs will be harder to convert, and errors are more likely. Unfortunately text documents exported from Word for Windows often have this property. Where there are no blank lines, AscToHTM relies of spotting the last line of a paragraph (usually shorter), and (in some documents) the presence of a [[popup New paragraph offset,"hanging indent"]] at the start of each new paragraph. This should be automatically detected. New Paragraph Offset .................... $_$_HELP_TOPIC_ID ID_NEWPARA _Menu location: Configuration options -> Analysis Policies -> General Layout_ Some documents start the first line of a new paragraph with an offset of a number of characters. This is especially true in text files saved from Word for Windows documents. AscToHTM can sometimes confuse such paragraphs as being two different levels of indentation. Use this policy to eliminate such confusion. This should be automatically detected Search for definitions ...................... $_$_HELP_TOPIC_ID ID_ALLOWDEFINITIONS _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy can be used to disable the search for definitions. Sometimes this leads to unexpected results with text that is not part of a definition being treated as such. In such cases you can adjust the definition policies, but if this still fails, use this to disable the search completely. See also [[popup one-line definitions]] and [[popup definition paragraphs]] Hanging paragraph position(s) ............................. $_$_HELP_TOPIC_ID ID_DEFNINDENTS _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy identifies the indentations used for the follow-on text in [[popup definition paragraphs]]. These indentation levels need not be the same as the indentation levels used for normal text, though of course often they are. This should be detected automatically, but if your document has only a few examples it's possible AscToHTM will ignore them. In such cases you may need to set this policy manually. _This appears on-screen as "Definition paragraph indent levels"_ Recognize hyphen characters ........................... $_$_HELP_TOPIC_ID ID_HYPHENDEFNS _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy specifies whether or not hyphen (-) characters are used in [[popup one-line definitions]]. If the hyphen character only occurs in definitions, then set the nearby always flag, otherwise AscToHTM will have to guess whether a particular character is part of a definition or not. This is sometimes a source of conversion errors. If this policy is selected, it will result in a suitable [[goto Definition Char]] line being added to the policy file. This should be detected automatically. Recognize colon characters .......................... $_$_HELP_TOPIC_ID ID_COLONDEFNS _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy specifies whether or not colon (:) characters are used in [[popup one-line definitions]]. If the colon character only occurs in definitions, then set the nearby always flag, otherwise AscToHTM will have to guess whether a particular character is part of a definition or not. This is sometimes a source of conversion errors. If this policy is selected, it will result in a suitable [[goto Definition Char]] line being added to the policy file. This should be detected automatically. Definition Char ............... $_$_HELP_TOPIC_ID ID_DEFNCHARS _Menu location: Configuration options -> Analysis Policies -> General Layout_ This policy specifies a character that may be used in [[popup one-line definitions]]. This may be detected automatically, but more likely you'll need to specify it yourself. This specifies the characters used to detect "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 The character can be marked as "Strong" or "weak". Strong means such characters *always* signal a definition. Weak means they only sometimes do this, depending on the position relative to the [[GOTO Page Width]]. For example for the above example you'd expect policy lines in the form $_$_BEGIN_PRE Definition Char : '=' (strong) Definition Char : ':' (strong) $_$_END_PRE _This appears on-screen as "Other definition characters", and each character entered into that field will get it's own "Definition Char" policy line_ The user interface presents this more cleanly than the text in the policy file does, and the latter may be changed in later versions. Indent position(s) .................. $_$_HELP_TOPIC_ID ID_INDENTS _Menu location: Configuration options -> Analysis Policies -> General Layout_ AscToHTM recognises multiple levels of indentation. This policy shows the character levels at which indentation has been detected. AscToHTM converts all tab characters into multiple spaces in input. These indentation positions are the positions that result after that conversion. Depending on your tab settings these might not be exactly the positions you would expect. Normally these levels are correctly detected automatically, but should you wish to set them manually you may need to experiment slightly to see how AscToHTM has handled your tabs. $_$_HELP_CHAPTER 3,"Bullet policies" Bullet policies --------------- $_$_HELP_TOPIC_ID HIDD_BULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ AscToHTM should be able to detect the use of bullets on a reasonably sized document. These policies describe the type of bullets expected. - [[popup Look for bullets, Automatically detect bullets and numbered lists]] *Expected Bullet types* - [[popup expect numbered bullets, numbered bullets]] - [[popup expect alphabetic bullets, alphabetic bullets]] - [[popup expect roman numeral bullets, roman numeral bullets]] *Bullet characters* - [[popup "recognize '-' as a bullet",recognize hyphen character as a bullet point]] - [[popup "recognize 'o' as a bullet",'recognize an "o" character as a bullet point']] - [[popup Bullet Char,Other bullet point characters]] See also the discussion on [[goto Bullets and list detection]] Look for bullets ................ $_$_HELP_TOPIC_ID ID_AUTODETECT_BULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy states whether or not the program should attempt to automatically detect bullets and numbered lists. This should normally be left on unless your document has no such features, but the program (wrongly) thinks it has. _This appears on the Bullets dialog as "Automatically detect bullets and numbered lists", but is identical to the "Look for bullets" policy on the [[goto 'What to look for' policies]] tabbed property sheet_ Expect Numbered bullets ....................... $_$_HELP_TOPIC_ID ID_NUMBERBULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy states whether or not numbered bullet points are expected. The numbered bullets can be followed by any punctuation, thus 1., 2) and (3) will all be recognised, but HTML will not necessarily support this in the markup produced. This should be automatically detected. Expect alphabetic bullets ......................... $_$_HELP_TOPIC_ID ID_ALPHABULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy states whether or not alphabetic bullet points are expected. The numbered bullets can be followed by any punctuation, thus a., b) and (c) will all be recognised, but HTML will not necessarily support this in the markup produced. Both upper and lower case bullets are recognised (and supported in the markup). This should be automatically detected Expect roman numeral bullets ............................ $_$_HELP_TOPIC_ID ID_ROMANBULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy states whether or not roman numeral bullet points are expected. The numbered bullets can be followed by any punctuation, thus i., ii) and (iii) will all be recognised, but HTML will not necessarily support this in the markup produced. Both upper and lower case bullets are recognised (and supported in the markup), although the range of roman numeral values supported is limited. This should be automatically detected. Recognize '-' as a bullet ......................... $_$_HELP_TOPIC_ID ID_MINUSBULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy states whether or not bullet points starting with the hyphen character '-' are expected. _This appears on-screen as "recognize hyphen character as a bullet point"_ This should be automatically detected. Recognize 'o' as a bullet ......................... $_$_HELP_TOPIC_ID ID_OBULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy states whether or not bullet points starting with the lower case 'o' are expected. _This appears on-screen as "recognize 'o' character as a bullet point"_ This should be automatically detected. Bullet Char ........... $_$_HELP_TOPIC_ID ID_OTHERBULLETS _Menu location: Conversion Options -> Analysis Policies -> Bullets and lists_ This policy lists any other characters that are to be recognised as bullet characters. _This appears on-screen as "Other bullet point characters"_ Each bullet character entered will appear in the policy file as it's own "Bullet Char" line as follows:- $_$_BEGIN_PRE Bullet Char : '<' $_$_END_PRE This should be automatically detected, but may sometimes need to be manually entered. $_$_HELP_CHAPTER 3,"Contents list policies" Contents list policies ---------------------- $_$_HELP_TOPIC_ID HIDD_CONTENTS _Menu location: Conversion options -> Analysis Policies -> Contents List_ [[br]] _Menu location: Conversion options -> Output Policies -> Contents List_ This dialog shows both analysis and output policies connected with contents list detection and generation. *Diagnostics* - [[popup Expect contents list]] *Output* - [[popup Add contents list]] - [[popup Maximum level to show in contents,Number of levels to show in contents list]] - Calculate contents list :- - [[popup Use any existing contents list,Generate contents from observed headings]] - [[popup Use any existing contents list,Generate contents from document's contents list]] - [[popup Generate external contents file,Place contents in an external file]] - [[popup External contents list filename]] - [[popup Hyperlinks on numbers,Contents list hyperlinks]] - [[popup Add mail headers to contents list]] Expect contents list .................... $_$_HELP_TOPIC_ID ID_EXPECTCONTENTS _Menu location: Conversion options -> Analysis Policies -> Contents List_ This policy specifies whether or not the document already contains a contents list. If it does, AscToHTM will attempt to convert the existing list into a series of hyperlinks. This should be detected automatically, but occasionally you will need to set this policy manually. See the discussion on [[goto contents list generation]] Add contents list ................. $_$_HELP_TOPIC_ID ID_MAKECONTENTS _Menu location: Conversion options -> Output Policies -> Contents List_ This policy specifies whether or not AscToHTM should generate a contents list. This lost will be generated from either an existing list in the source documents, or from the observed headings. A link to "contents list" will be added to the main HTML file. See the discussion on [[goto contents list generation]] Use any existing contents list .............................. _Menu location: Conversion options -> Output Policies -> Contents List_ This policy specifies whether or not you wish to use any existing contents list found in the source document. If you disable this option, any contents found will be discarded. A contents list will only be added if you select the [[GOTO Add contents list]] policy This option is not fully supported, as it depends on the software correctly detecting the contents list, and then matching the contents lines with headings in the document. If this option is disabled (the default) any contents list will be created from the headings detected in the document (this is the recommended option) On-screen this appears as a choice between calculating the contents from observed headings, or from the contents list in the document See the discussion on [[goto contents list generation]] Generate external contents file ............................... $_$_HELP_TOPIC_ID ID_CONTENTS_EXTERNAL _Menu location: Conversion options -> Output Policies -> Contents List_ This policy specifies that an external contents list file should be generated. This is not always possible. See the discussion on [[goto contents list generation]] External contents list filename ............................... _Menu location: Conversion options -> Output Policies -> Contents List_ When [[popup Generate external contents file]] is enabled, this specifies the name of the external contents list file. The default will be "contents_<input_filename>.html" Hyperlinks on numbers ..................... $_$_HELP_TOPIC_ID ID_CONTENTS_HYPERLINKS _Menu location: Conversion options -> Output Policies -> Contents List_ This policy specifies whether the hyperlink in a contents list entry should be placed on the section number, or the section title. _This appears on-screen as a choice between placing the link on the number or the title, but in the policy file this is simply a "Yes/No" option on placing the link on the number._ This is only relevant for documents with numbered section headings. Maximum level to show in contents ................................. $_$_HELP_TOPIC_ID ID_CONTENTS_LEVELS _Menu location: Conversion options -> Output Policies -> Contents List_ This policy specifies whether the hyperlink in a contents list entry should be placed on the section number, or the section title. This is only relevant for documents with numbered section headings. Add mail headers to contents list ................................. _(New in version 5.0)_ _Menu location: Conversion options -> Output Policies -> Contents List_ This policy specifies whether or not mail headers should be included in any generated contents list. For a mail digest this should be yes, but for larger documents with only a couple of mail headers the answer may be no. $_$_HELP_CHAPTER 3,"File structure policies" File structure policies ----------------------- $_$_HELP_TOPIC_ID HIDD_FILESTRUCT _Menu location: Conversion Options -> Analysis Policies -> File Structure_ These policies aid AscToHTM's analysis by describing some of the file structure that would affect the analysis. - [[popup Keep it simple, Expect only a simple layout]] *Expected File contents* - [[popup Expect Code samples,'Expect "C"-code samples']] - [[popup Input file contains DOS characters, Contains DOS characters]] - [[popup Input file contains UNICODE characters, Contains UNICODE characters]] - [[popup Input file contains PCL codes, Contains PCL printer codes]] - [[popup Input file contains Japanese characters, Contains non-European (e.g. Japanese) characters]] - [[popup Input file contains MIME encoding, Contains mime-encoded quotable characters]] - [[popup Input file has change bars, File has change bars]] - [[popup Input file has page markers, File has Page markers]] - [[popup Page marker size (in lines)]] *Text Attributes* - [[popup Text justification]] - [[popup Input file is double spaced, File is double spaced]] *Text to ignore* - [[popup Lines to ignore at start of file, Number of lines to ignore at start of document]] - [[popup Lines to ignore at end of file, Number of lines to ignore at end of document]] Keep it simple .............. $_$_HELP_TOPIC_ID ID_SIMPLE _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM puts a lot of effort into detecting overall structure such as headings etc. In documents that don't have any such structure, AscToHTM is liable to convert any line with a number at the start into a heading. To prevent this, you can mark the document as simple, that is with no global structure. In a simple document AscToHTM will attempt far less analysis. _This appears on-screen as "Expect only a simple layout"_ AscToHTM attempts to automatically identify simple documents, but you may still need to set this policy manually. Expect Code samples ................... $_$_HELP_TOPIC_ID ID_EXPECTCODE _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM can markup C-like code fragments in <PRE>...</PRE> tags to preserve the layout and readability of the quoted code. This may be automatically detected, but occasionally needs to be manually corrected. Input file contains DOS characters .................................. $_$_HELP_TOPIC_ID ID_DOSCHARS _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM can convert files that use the DOS (OEM) character set. By default the file is assumed to be in the ANSI character set, but some files may have originated under DOS. This may be automatically detected, but usually needs to be manually set. Input file contains UNICODE characters ...................................... _(New in version 5.0)_ _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM has some ability to detect files that contain Unicode characters or which are themselves encoded using Unicode. Where Unicode is detected on input, and UTF-8 file will be created as output, and extra care will be taken when processing file not to split any of the multi-byte character values. This should be automatically detected, but may sometimes needs to be set manually. See [[goto Working with Unicode]] Input file contains PCL codes ............................. $_$_HELP_TOPIC_ID ID_PCL_CODES _(New in version 5.0)_ _Menu location: Conversion Options -> Analysis Policies -> File Structure_ Indicates that the input file contains PCL printer codes. When set, the program will make whatever sensible use it can of these codes, otherwise they will be removed. Please note that the PCL printer codes offer a rich command language that may be used to drive graphical printers. As such the emulation possibilities in a *text* converter are limited, and it is quite likely that files that make heavy use of such codes will fail dramatically to convert. That said, those codes that are not recognised will be eliminated from the output. Input file contains Japanese characters ....................................... $_$_HELP_TOPIC_ID ID_JAPANCHARS _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM is designed to convert ASCII files, and is biased to parsing the structure of files written in European languages. However, this policy can tell the program that there are some non-ASCII characters (Japanese, Chinese, Korean etc) present. When this is the case certain conversions of exotic characters to HTML entities are disabled so that there is some prospect of the HTML still being readable in a browser. There is a limited ability for this policy to be auto-detected. Input file contains MIME encoding ................................. $_$_HELP_TOPIC_ID ID_MIMECHARS _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM can convert mime-encoded quotable characters. These will usually appear in files that were originally part of an email message. Such files use the "=" character to escape special characters. So for example "=20" should be interpreted as a space. _This appears on-screen as "Contains mime-encoded quotable characters"_ This may be automatically detected in files where the "=" is used to break up long lines, but more usually you will need to manually set this. Input file has change bars .......................... $_$_HELP_TOPIC_ID ID_CHANGEBARS _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM can strip out change bars in documents that contain them. Change bars are usually a vertical bar '|' placed in the leftmost or rightmost column. Currently this is not automatically detected, and so will need to be manually switched on. Input file has page markers ........................... $_$_HELP_TOPIC_ID ID_PAGEMARKER _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM has a limited ability to remove page markers. These are normally a few lines following a form feed (FF) character, containing page numbers etc. This will commonly occur with files generated from older software packages. Page marker size (in lines) ........................... $_$_HELP_TOPIC_ID ID_PAGE_MARKERSIZE _Menu location: Conversion Options -> Analysis Policies -> File Structure_ The number of lines after each form feed (FF) that should be ignored. These lines will not be copied to the output. Text Justification .................. $_$_HELP_TOPIC_ID ID_TEXTJUSTIFICATION _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM recognises documents that are left justified (default), right justified, centred or both left and right justified (confusingly known as "justified"). The program cannot currently mark up the text in a matching style, but this policy is important in the analysis. For example "justified" documents are padded with extra white space which could be interpreted as pre-formatted text where the document not recognised as being justified. Normally this policy is correctly detected automatically. Input file is double spaced ........................... $_$_HELP_TOPIC_ID ID_DOUBLESPACED _Menu location: Conversion Options -> Analysis Policies -> File Structure_ AscToHTM will normally treat a blank line as a break between paragraphs. Some files have extra CR/LF characters (usually if they've come from a different computer, or from a printer package). In such cases AscToHTM will see every second line as blank, and this will affect the analysis, usually by turning each line of data into a separate paragraph. If you have such a file, use this policy to mark the file as double spaced to get better results. Lines to ignore at start of file ................................ $_$_HELP_TOPIC_ID ID_IGNORE_AT_START _(New in version 5.0)_ _Menu location: Conversion Options -> Analysis Policies -> File Structure_ This specifies how many lines from the input files should be ignored at the start of the file. These lines will be discarded from the output. This can be useful when converting file copied from a news feed or whatever that adds a small data header to the file. Lines to ignore at end of file .............................. $_$_HELP_TOPIC_ID ID_IGNORE_AT_END _(New in version 5.0)_ _Menu location: Conversion Options -> Analysis Policies -> File Structure_ This specifies how many lines from the input files should be ignored at the end of the file. Up to 40 lines may be ignored in this way. These lines will be discarded from the output. This can be useful when converting file copied from a news feed or whatever that adds a small data footer to the file. $_$_HELP_CHAPTER 3,"Headings policies" Headings policies ----------------- $_$_HELP_TOPIC_ID HIDD_HEADINGS _Menu location: Conversion options -> Analysis Policies -> Headings_ These policies determine the headings structure that the document is expected to have. Normally these are calculated correctly by AscToHTM, but due to the complexity of heading detection, you may sometimes need to correct the analysis. At the top of the dialog you can specify what type of headings you expect to see. Any combination is allowed, although usually documents use just one type of heading. - [[popup Expect Numbered headings]] - [[popup Expect Underlined headings]] - [[popup Expect Capitalised headings]] - [[popup Expect Embedded headings]] - [[popup Heading Key phrases]] - [[popup Use first line as heading]] - [[popup Center first heading]] - [[popup Check indentation for consistency, Check indentations of headings are consistent]] If numbered headings are expected, it may be possible to expect headings at multiple levels, and to also expect a contents list. Each level of heading will have it's own set of policies which are shown on this dialog. The policies are shown in text form, but are edited via the [[goto Advanced Headings Policies Dialog]] Note: This area of functionality is continually under review. See also the discussion in detecting [[goto headings and section titles]]. Expect numbered headings ........................ $_$_HELP_TOPIC_ID ID_NUMBERED_HEADINGS _Menu location: Conversion options -> Analysis Policies -> Headings_ This policy specifies whether or not numbered headings are expected in the document. Numbered headings may be found at multiple levels, and their details may be edited via the [[goto Advanced Headings Policies Dialog]] This should be calculated correctly by AscToHTM. But is prone to error, getting confused by numbered bullets and the like. In such cases you may need to set this policy manually. Expect underlined headings .......................... $_$_HELP_TOPIC_ID ID_UNDERLINED_HEADINGS _Menu location: Conversion options -> Analysis Policies -> Headings_ This policy specifies whether or not underlined headings are expected. Note, where the headings themselves are numbered, the underlining will be taken into account, and you should set the [[popup expect numbered headings]] policy instead. AscToHTM uses the character in the underlining to determine the heading level, thus text underlined with equals signs is given prominence over text with single underline characters such as minus signs, tildes or underscores. Expect capitalised headings ........................... $_$_HELP_TOPIC_ID ID_CAP_HEADINGS _Menu location: Conversion options -> Analysis Policies -> Headings_ This policy specifies whether or not CAPITALISED headings are expected. Note, where the headings themselves are numbered, this policy need not be set, and instead you should set the [[popup expect numbered headings]] policy instead. Expect Embedded headings ........................ $_$_HELP_TOPIC_ID ID_EMBEDDED_HEADINGS _(New in version 5.0)_ _Menu location: Conversion options -> Analysis Policies -> Headings_ This policy specifies whether or not "embedded" headings are expected, i.e.. the heading is "embedded" in the first paragraph. Such headings are expected to be a complete sentence or phrase in UPPER CASE at the start of a paragraph. This policy specifies whether or not embedded headings are expected. An embedded heading is one where the heading is the first sentence in the first paragraph of the section itself. The program can only detect this if the heading is in capitals. An example might be :- $_$_BEGIN_PRE RULE 15.6 – TERMS AND CONDITIONS. The terms and conditions that apply are described in this section. They will apply... $_$_END_PRE In this case the text "RULE 15.6 – TERMS AND CONDITIONS" will be treated as the embedded heading. At present such headings are not auto-detected... you need to switch this policy. Heading Key phrases ................... $_$_HELP_TOPIC_ID ID_KEYPHRASE_HEADINGS _(New in version 5.0)_ _Menu location: Conversion options -> Analysis Policies -> Headings_ If specified, then any line that begins with one of the key phrases will be regarded as a heading. The syntax is $_$_BEGIN_PRE <details>, <details>... $_$_END_PRE where each set of details is $_$_BEGIN_PRE <details> = <phrases>, [<heading_level>] $_$_END_PRE and $_$_BEGIN_PRE <phrases> = <phrase_1> [|<phase_2>] $_$_END_PRE That is, each set of <details> can optionally specify a <heading_level>. If omitted this will default to 1,2,3 for the first, second, third set of details etc. Note, this is a *logical* heading level, and will be apparent in the contents list. Each set of <details> must supply a set of <phrases>, and each set of phrases would must have at least one phrase with extra phrases added if wanted, separated by vertical bars. So for example $_$_BEGIN_PRE Part, Chapter, Section $_$_END_PRE would treat lines beginning with the words "Part", "Chapter" and "Section" as level 1,2, and 3 headings. The key phrases are case-sensitive in order to reduce the likelihood of false matches with lines that just happen to have these phrases at the start of the line. So $_$_BEGIN_PRE PART|Part, Chapter, Section $_$_END_PRE Would allow either "PART" or "Part" to be matched. $_$_BEGIN_PRE "PART|Part,1" , "Chapter,2" , "Section,2" $_$_END_PRE Would make lines beginning with "Part" level-1 headings, while both "Chapter" and "Section" would become level 2. This would be the same as $_$_BEGIN_PRE "PART|Part,1" , "Chapter|Section,2" $_$_END_PRE Note, spaces may form part of a match phrase, but because of their use in the tag syntax commands and vertical bars may not. If false matches occur, (e.g. the word "Part" appears in the body of the text) edit the source text so that the offending word is no longer at the start of the line. Use first line as heading ......................... _(New in version 5.0)_ _Menu location: Conversion options -> Analysis Policies -> Headings_ When this option is selected, the first line in the document will be treated as a heading. This can be a useful option to select when the first line of your document is a document title line, but doesn't conform to the headings style used in the rest of the document. See also [[goto use first line as title]] Center first heading .................... _(New in version 5.0)_ _Menu location: Conversion options -> Analysis Policies -> Headings_ When this option is selected, the first heading in the document is centred. This may be an appropriate choice when the first heading is in fact to be treated as a document title. See also [[goto use first line as heading]] Check indentation for consistency ................................. $_$_HELP_TOPIC_ID ID_HEADINDENTS _Menu location: Conversion options -> Analysis Policies -> Headings_ The program performs a number of consistency checks when detecting headings. Amongst these is a check that all headings of the same type occur at the same indentation. This check can help distinguish between numbered headings and numbered lists. However, if you have numbered headings that are different indentations - e.g. because they are centred on the page - then this check will cause them to be rejected as headings. In such cases you can manually disable this check. _This appears on-screen as "Check indentations of headings are consistent"_ $_$_HELP_CHAPTER 3,"Advanced headings policies" Advanced headings policies dialog --------------------------------- $_$_HELP_TOPIC_ID HIDD_HEADDTLS _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ This dialog is reached through one of the edit buttons on the main [[goto Headings Policies]] dialog. This allows you to edit details of a particular type or level of heading. *Position of section number on the line* - [[popup Indentation of heading lines]] - [[popup Heading prefix words]] *Section number formatting* - [[popup Heading numbering scheme]] - [[popup Heading separator characters]] - [[popup Heading trailing letters]] *Bracketing* - [[popup Heading bracket characters]] See also [[goto Heading policies in a policy file]]. Indentation of heading lines ............................ $_$_HELP_TOPIC_ID ID_HEAD_INDENT _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ AscToHTM uses checks on indentation levels to reject lines with numbers on that could be confused with headers. This is the indentation level (in characters) that heading of this types are expected to be found at. Heading prefix words .................... $_$_HELP_TOPIC_ID ID_HEAD_PREFIX _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ Some documents put words like "chapter", "subject" and "section" in front of the section number. These are known as prefix words. Heading numbering scheme ........................ $_$_HELP_TOPIC_ID ID_HEAD_NUMBERTYPE _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ This is the numbering scheme expected for headings at this level. At present AscToHTM can't cope with mixed types like "II-2.b". This may be addressed in later versions. Heading separator characters ............................ $_$_HELP_TOPIC_ID ID_HEAD_SEPARATOR _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ This shows the separator expected between parts of the heading number. *Not currently supported* Heading trailing letters ........................ $_$_HELP_TOPIC_ID ID_HEAD_TRAILALPHA _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ This shows whether we expect trailing letters after the section number, as in "1.1b". *Not currently supported* Heading bracket characters .......................... $_$_HELP_TOPIC_ID ID_HEAD_BRACKETS _Menu location: Conversion options -> Analysis Policies -> Headings -> Advanced Options_ This shows what bracket characters (if any) we expect before and after the section number as in "[2.2]" or "3.2.1)". *Not currently supported* $_$_HELP_CHAPTER 3,"Pre-formatted text policies" Pre-formatted text policies --------------------------- $_$_HELP_TOPIC_ID HIDD_PREFORMAT _Menu location: Conversion options -> Analysis Policies -> Pre-formatted text_ These policies specify how AscToHTM detects pre-formatted text. *Detecting pre-formatted regions* - [[popup Minimum automatic <PRE> size]] See the section on [[goto pre-formatted text]] for more details. These policies specify how AscToHTM detects pre-formatted text. Minimum automatic <PRE> size ............................ $_$_HELP_TOPIC_ID ID_MINPRESIZE _Menu location: Conversion options -> Analysis Policies -> Pre-formatted text_ This policy specifies the minimum number of consecutive pre-formatted lines that must be detected before <PRE>...</PRE> markup is applied. AscToHTM detects heavily formatted lines, and then looks at their neighbours to see if they too could be part of a pre-formatted text. Once a group of lines is identifies, it will only be marked up as pre-formatted if the minimum is exceeded. The default value is 0. Set this value larger if AscToHTM is marking text as pre-formatted when it shouldn't do. $_$_HELP_CHAPTER 3,"Table analysis policies" Table analysis policies ----------------------- $_$_HELP_TOPIC_ID HIDD_TABANAL _Menu location: Conversion options -> Analysis policies -> Tables_ These policies specify how AscToHTM detects possible tables and analyses the data in them into columns and rows. - [[popup Attempt TABLE generation]] *Detection* - [[popup Table extending factor, Extend preformatted regions]] - [[popup Max length of candidate table lines,Maximum length of line to consider as a candidate table line]] *Analysing rows* - [[popup Could be blank line separated,Could table have blank lines between rows]] *Analysing columns* - [[popup Default table layout, Table Layout]] - [[popup Column boundaries have zero width]] - [[popup Expect sparse tables,Is the table expected to have sparse columns]] - [[popup Ignore table header during analysis,Ignore table header when analysing columns]] - [[popup Expect multiple COLSPAN values]] - [[popup Minimum TABLE column separation, Minimum number of spaces between table columns]] - [[popup Column merging factor, Merge together "poor" columns]] See the section on [[goto pre-formatted text]] for more details. Attempt TABLE generation ........................ $_$_HELP_TOPIC_ID ID_ATTEMPT_TABLE _Menu location: Conversion options -> Analysis policies -> Tables_ This policy specifies whether or not you want HTML table generation attempted for regions of apparently pre-formatted text. AscToHTM will attempt to analyse such regions, preferring to fit them into a HTML table. However, if this is not possible, or if AscToHTM decides the pre-formatted region is something else (like a diagram or a piece of code) then a HTML table will not be generated. Disabling this policy tells AscToHTM not to attempt this analysis, usually leading to pre-formatted text being placed in simple fixed width font markup instead. Table extending factor ...................... $_$_HELP_TOPIC_ID ID_EXTEND_TABLE _Menu location: Conversion options -> Analysis policies -> Tables_ When the program encounters a strongly formatted line, it examines the adjacent lines to see if they too could form part of the same preformatted region. This policy specifies the extend to which strongly preformatted lines should be used to "extend" to include adjacent lines as part of the same preformatted regions. If set to 10, then all adjacent lines up to the next page break or section heading will be treated as part of the same region. When set to 1 only those lines that are clearly heavily formatted themselves will be included. _This appears on-screen as "Extend preformatted regions"_ Max length of candidate table lines ................................... _(New in version 5.0)_ _Menu location: Conversion options -> Analysis policies -> Tables_ This specifies the maximum length of line that could be considered as a possible table line. Since some files output one paragraph per line, it is possible for some text to contain a lot of the "markers" used to detect table lines, and to be wrongly diagnosed as part of a table. This value is set to prevent that happening. The value should be set as low as reasonable for your files, however the current default value of 256 has been set to cope with observed legacy reports which were often designed to be printed on line printer paper Could be blank line separated ............................. _(New in version 5.0)_ _Menu location: Conversion options -> Analysis policies -> Tables_ This option specifies whether or not tables are expected to have blank lines between rows. If they are, the software will be more likely to merge the text for adjacent source lines into a single row in the output table. Default Table Layout .................... _(New in version 5.0)_ _Menu location: Conversion options -> Analysis policies -> Tables_ This option allows you to specify the default table layout for *all* tables in the document. The layout specifies the number of columns and their end positions. If there are no gaps between columns in the data then you will need to enable the [[popup Column boundaries have zero width]] options. This is the default layout and will normally be applied to *all* tables the document. If a document has multiple tables you are better off either using the pre-processor to mark up the source text and supplying TABLE_LAYOUT commands, or supplying a "Layout" component in a _Table Definition File_. The format of the *Table Layout* policy is the same as that described in the discussion of the [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] pre-processor command. See also [[goto TDF line: Layout]] Column boundaries have zero width ................................. _(New in version 5.0)_ _Menu location: Conversion options -> Analysis policies -> Tables_ When a [[GOTO Default TABLE layout]] is set, this specifies whether or not the boundaries between columns have zero size. By default the software assumes there is a single-character boundary (either a space or a delimiter character) between columns. Sometimes data comes from a source with *no* character between data columns. This policy should be set in such cases. Expect sparse tables .................... $_$_HELP_TOPIC_ID ID_TABLE_SPARSE _Menu location: Conversion options -> Analysis policies -> Tables_ This policy is used to tell AscToHTM that you expect your tables to be quite sparse in places. This can affect AscToHTM's analysis, as the algorithms are liable to merge "empty" columns with their less empty neighbours. Enabling this policy will usually result in your tables having more, emptier, columns. See also the [[popup Pre-processor command: TABLE_MAY_BE_SPARSE]]. Ignore table header during analysis ................................... $_$_HELP_TOPIC_ID ID_IGNORE_HEADER _Menu location: Conversion options -> Analysis policies -> Tables_ This policy specifies that the table header should be ignored when analysing the column structure of the table. In some tables (usually "reports") the header can be quite complex, with titles spanning multiple columns, whereas the body of the table is much more structured. In such cases including the table header in the analysis can lead to errors, so enabling this policy can simplify the analysis giving better chances of success. See also [[popup Expect multiple COLSPAN values]] _This appears on-screen as "Ignore table header when analysing columns"_ Expect multiple COLSPAN values .............................. _(New in version 5.0)_ _Menu location: Conversion options -> Analysis policies -> Tables_ When auto-detecting the column structure of tables, the software has to decide where the column boundaries are, and in doing this it looks for character positions that appear to contain mostly blank or non-text characters. The analysis can have problems if the table has a lot of data that spans multiple columns (in HTML this would require a COLSPAN value to merge the cells together). Tables with complex headers (e.g. financial tables merging results from many sources) or witchy internal headers often have this feature. If you have such tables and find that the analysis is failing to detect your columns (commonly merging columns together), try enabling this option which will relax the definition of what constitutes such a table. In such cases you should also review your use of the [[popup Column merging factor]] and [[popup Ignore table header during analysis]] policies. _This appears on-screen as "Expect cells that span multiple columns"_ Minimum TABLE column separation ............................... $_$_HELP_TOPIC_ID ID_MIN_TABLE_SEP _Menu location: Conversion options -> Analysis policies -> Tables_ This policy specifies the minimum number of spaces that should be interpreted as a gap between columns in a potential table. The default value is 1, but this value can sometimes lead to too many columns, especially in small tables. Larger values may lead to columns being merged together. _This appears on-screen as "Minimum number of spaces between table columns"_ Column merging factor ..................... $_$_HELP_TOPIC_ID ID_MERGE_POOR _Menu location: Conversion options -> Analysis policies -> Tables_ Once the program has detected the column layout of a table, it reviews how well the data can be fitted into these columns. If too many cells in a column are empty, or if too many cells "span" multiple columns, then the columns are deemed to be "poor", and may be merged together to form fewer, wider columns. This factor determines the extent to which columns should be merged. A value of 10 means columns should be merged together whenever there is any doubt. Use this if you are getting too many columns. A value of 1 means columns should never be merged. Use this if you are getting too few columns. _This appears on-screen as "Merge together "poor" columns"_ Note, this policy can't guarantee you will the correct column structure, but it does give you a chance to influence the logic. $_$_HELP_CHAPTER 2,"Output policies" $_$_HELP_SUBJECT "Introduction" Output policies =============== $_$_HELP_TOPIC_ID ID_OUTPUT_POLICIES _Menu location: Conversion options -> Output policies_ These policies are used to control the output to HTML. Generally these policies allow you to decide how the resulting HTML should look in a manner that cannot be inferred from the original document. - [[goto File generation policies,File generation]] - [[goto File generation policies,General]] - [[goto Directory Page policies, Directory page]] - [[goto File generation policies,File naming]] - [[goto File splitting policies, Splitting large files at section headings]] - [[goto Added HTML policies,Title description etc.]] - [[goto Colour Policies,Document colours]] - [[goto Contents list policies,Contents lists]] - [[goto Frames policies, Frames]] - [[goto Advanced HTML policies,Headers footers etc]] - [[goto Table generation policies,Tables]] - [[goto Hyperlink policies,Hyperlinks]] - [[goto Pre-processor policies,Pre-processor]] - [[goto CSS policies,CSS]] - [[goto Font policies,Fonts]] - [[goto Style policies,HTML styling]] $_$_HELP_CHAPTER 3,"Added HTML policies" Added HTML policies ------------------- $_$_HELP_TOPIC_ID HIDD_ADDEDHTML _Menu location: Conversion options -> Output policies -> Title description etc._ These policies allow you to “add value” to the HTML produced. That is, to specify details that cannot be inferred from the original text. *Title* - [[popup Use first heading as title]] - [[popup Use first line as title]] - [[popup Document title,Default document title]] *Meta tags* - [[popup Document description]] - [[popup Document keywords]] - [[popup Author URL]] - [[popup Bookmark URL]] - [[popup Copyright URL]] - [[popup Shortcut Icon URL]] *Other* - [[popup Background image]] NOTE: Although these policies 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 are usually placed in a separate file, which can be selected from the [[goto Advanced HTML policies,Advanced HTML options dialog]] by pressing the button further down this screen. A button will take you to the [[goto Advanced HTML policies,Advanced HTML options dialog]] Use first heading as title .......................... _Menu location: Conversion options -> Output policies -> Title description etc._ When this option is selected, the first heading detected in the document will also be used as the document's title, i.e. as the text that goes into the <TITLE>...</TITLE> tags in the <HEAD>...</HEAD> section of the generated HTML pages. Note, this relies on the program correctly detecting headings, and in particular the first heading. If the first heading is also the first line, you may want to instead just consider using the [[goto use first line as heading]] and/or [[goto use first heading as title]] policies. If no heading is encountered the [[goto document title]] is used instead Use first line as title ....................... _Menu location: Conversion options -> Output policies -> Title description etc._ When this option is selected, the first line in the document will be treated as the document title, i.e. as the text that goes into the <TITLE>...</TITLE> tags in the <HEAD>...</HEAD> section of the generated HTML pages. This can be a useful option to select when the first line of your document is a document title line. If you also want the first line to appear in the output as a heading, select the [[goto use first line as heading]] option This will only take effect if the first heading is not to be used, or no heading has been found. Document Title .............. $_$_HELP_TOPIC_ID ID_TITLE _Menu location: Conversion options -> Output policies -> Title description etc._ This specifies the text to be used by default in the <TITLE>...</TITLE> tags in the <HEAD>...</HEAD> section of the generated HTML pages. The default value is Converted from [[OT]]filename[[CT]] where *[[OT]]filename[[CT]]* gets replaced by the original filename (see [[goto Pre-processor command: filename]]). This value will only be used if the first heading is not to be used (or is not found), and if the first line is not to be used. If you want this to be the title, make sure the “Use first heading” and “use first line” options are disabled. See also: - [[goto Splitting large files into a linked set of smaller files,Split Into Files]] - [[goto use first heading as title]] - [[goto use first line as title]] Document Description .................... $_$_HELP_TOPIC_ID ID_DESCRIPTION _Menu location: Conversion options -> Output policies -> Title description etc._ This specifies text that will be inserted into a <META> tag in the <HEAD> portion of your HTML page. Search engines use this description when indexing your page, and may be shown as the summary of your page when people search for it. This text is not normally visible in a browser. Document Keywords ................. $_$_HELP_TOPIC_ID ID_KEYWORDS _Menu location: Conversion options -> Output policies -> Title description etc._ This specifies text that will be inserted into a <META> tag in the <HEAD> portion of your HTML page. Search engines will use these keywords when indexing your page. You should add here any keywords that summarise the contents of your page, and in particular include words not actually in the document, or alternative spellings (e.g. American versus UK English). This text is not normally visible in a browser. Author URL .......... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Title description etc._ Identifies the URL of the author of this document. A META tag will be added to the HTML so that those browsers that can display this information can use it. Bookmark URL ............ _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Title description etc._ Identifies the URL to be used as the bookmark for this document. A META tag will be added to the HTML so that those browsers that understand this information can use it. Copyright URL ............. _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Title description etc._ Identifies a URL describing the copyright notice for this document. A META tag will be added to the HTML so that those browsers that can display this information can use it. Shortcut Icon URL ................. _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Title description etc._ Identifies the URL of any icon to be used as a shortcut for this page. A META tag will be added to the HTML so that those browsers that support shortcut icons can use it. Background Image ................ $_$_HELP_TOPIC_ID ID_BGIMAGE _Menu location: Conversion options -> Output policies -> Title description etc._ This specifies the image file to be drawn as background on your HTML page. This is the text inserted into the <BODY BGIMAGE=value> tag in the generated HTML. The value entered should be the absolute or relative URL of the file to be used. Usually this is simply the name of a .GIF or .JPG file that will be placed in the same directory as the created .HTML files. $_$_HELP_CHAPTER 3,"Advanced HTML policies" Advanced HTML policies ---------------------- $_$_HELP_TOPIC_ID HIDD_ADVANCED_HTML _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ These policies allow you to control more advanced features that influence HTML generation. *HTML Options* - [[popup Omit <HEAD> and <BODY> from output]] - [[popup Comment generation code,"Allow ""generated by AscToHTM"" comments"]] - [[popup Document Base URL,Base HREF URL]] *Character Set* - [[popup Character Encoding]] *Include files* These policies allow you insert files into your output HTML at particular locations. This can be useful to give your pages a common “look and feel”. - [[popup HTML Header file]] - [[popup HTML Footer file]] - [[popup HTML Script file,Script file (copied to the <HEAD> section)]] Omit <HEAD> and <BODY> from output .................................. $_$_HELP_TOPIC_ID ID_OMIT_TAGS _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ This policy specifies that the <HTML>, <HEAD> and <BODY> tags should be omitted from the HTML generated. This will end up producing HTML that is not, technically, a correct standalone document, although many browsers will display it correctly. You should only select this option if your intention is to use the generated HTML as part of a larger document, in which case these tags shouldn’t be duplicated. This policy is enabled automatically whenever [[goto Outputting HTML to the clipboard, output to Windows clipboard]] is selected. Comment generation code ....................... $_$_HELP_TOPIC_ID ID_ALLOW_COMMENT _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ Used to control the placing of comment in the code advertising the fact that AscToHTM was used to generate the file. By default the program will add a META tag marking ASCTOHTM as the generator and comments at the top and bottom of the file identifying the program. The value should be set as follows $_$_BEGIN_TABLE 0 META tag and comments added 1 META tag added 2 neither added $_$_END_TABLE _This on-screen as 'Allow “generated by AscToHTM” comments'. When enabled this sets a value of 0. When disabled the value is 2._ NOTE: This feature is only enabled in the registered version of the software. You cannot use it in the shareware version. Document Base URL ................. $_$_HELP_TOPIC_ID ID_BASE_HREF _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ This specifies the URL to be placed in any <BASE> tag. This URL is used as a baseline for resolving any relative links. In HTML you might want this if the page is going to refer to images, style sheets or cgi scripts using URLs that are correct relative to location 1, but incorrect when the page is moved to location 2, e.g. to be used as a mirror on a second site. Of course, if you were to also move the images, style sheets and cgi-scripts to the second site so that all relative links remained correct, you wouldn’t need this policy. Character encoding .................. $_$_HELP_TOPIC_ID ID_CHARSET _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ The software has the ability to detect if the source file uses a character set other than ASCII. This can then be used to set the character set of the HTML generated so that it will display correctly in a browser. The character set should be detected automatically, but if it isn’t, or if it is detected wrongly, you can use this to change it. If left blank, the default will be “ascii”. Character set Language Auto-detected? ---------------------------------------------- ascii English/Western Yes big5 Chinese Yes csGB2312 Chinese - csShiftJIS Japanese - csbig5 Chinese - euc-kr Korean - gb2312 Chinese Yes iso-2022-kr Korean Yes iso-8859-1 Western Europe - iso-8859-10 Scandinavia - iso-8859-2 Eastern Europe - iso-8859-3 Turkish - iso-8859-4 Baltic states - iso-8859-5 Cyrillic - iso-8859-6 Arabic - iso-8859-7 Greek - iso-8859-8 Hebrew Yes iso-8859-9 Latin + Turkish - koi8-r Cyrillic Yes ms_Kanji Japanese - shift_jis Japanese - tis-620 Thai Yes UTF-8 Unicode - windows-1251 Cyrillic Yes windows-1253 Greek Yes windows-1254 Turkish Yes windows-1256 Arabic Yes x-euc-jp Japanese - x-euc-tw Chinese - x-sjis Japanese Yes HTML Header file ................ $_$_HELP_TOPIC_ID ID_HEADER _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ This specifies the name of a text file whose contents will be copied into the generated HTML page(s). The contents of this file will be inserted just after the <BODY> tag, and *before* any of the converted files contents are copied across to the HTML file. This file should be accessible at conversion time, and will normally contain some standard text or HTML that you want including at the top of the visible page. Note: Although still supported, in later versions it is recommended that you instead define a HTML_HEADER [[goto Using HTML Fragments,HTML fragment]] in an external definition file. HTML footer file ................ $_$_HELP_TOPIC_ID ID_FOOTER _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ This specifies the name of a text file whose contents will be copied into the generated HTML page(s). The contents of this file will be inserted just before the closing </BODY> tag, and *after* all of the converted files contents have been copied across to the HTML file. This file should be accessible at conversion time, and will normally contain some standard text or HTML that you want including at the top of the visible page. Note: Although still supported, in later versions it is recommended that you instead define a HTML_FOOTER [[goto Using HTML Fragments,HTML fragment]] in an external definition file. HTML Script file ................ $_$_HELP_TOPIC_ID ID_SCRIPT _Menu location: Conversion options -> Output policies -> Title description etc._ _(and then press the "Advanced options >>>" button_ This specifies the name of a text file whose contents will be copied into the generated HTML page(s). The contents of this file will be inserted into the <HEAD>...</HEAD> section of the generated HTML file. This file should be accessible at conversion time, and will normally contain some HTML that you want including at the HTML <HEAD>...<HEAD> section. Note, tags inserted at this point are not normally visible, and as such this file should only contain relevant HTML such as <META> tags or JavaScript... hence the name. Note: Although still supported, in later versions it is recommended that you instead define a HTML_SCRIPT [[goto Using HTML Fragments,HTML fragment]] in an external definition file. $_$_HELP_CHAPTER 3,"Colour policies" Colour policies --------------- $_$_HELP_TOPIC_ID HIDD_COLOURS _Menu location: Conversion Options -> Output Policies -> Document Colours_ These policies allow you to choose the colour of various components of your HTML pages. HTML allows you to control the colours of several components by specifying attributes in the <BODY> tag. These include :- - [[popup Text colour]] (TEXT attribute) - [[popup Background colour]] (BGCOLOR) - [[popup Unvisited Link Colour,Hyperlink colour]] (LINK) - [[popup Visited Link Colour,Visited hyperlinks]] (VLINK) - [[popup Active Link Colour,Active hyperlinks]] (ALINK) These policies should be given a valid [[goto HTML colours,HTML colour code]] value You can also choose - [[popup Suppress all colour markup]] Suppress all colour markup .......................... _(New in version 5.0)_ _Menu location: Conversion Options -> Output Policies -> Document Colours_ This option may be of interest to those generating pages to be viewed by the visually impaired who can use their browser to set the colours that suit them best. HTML Colours ............ $_$_HELP_TOPIC_ID ID_COLOURS Some policies specify colours of various HTML components, described in the <BODY> tag and others in the generated file. You can use the browse buttons to choose from a colour palette. Colours in HTML are specified as 6-character RRGGBB values, with each component taking a hexadecimal value in the range 00-FF. Thus 000000 is black, FFFFFF is white and 550000 is a dark red. A few colours (some of the combinations of “00”, “80” and “FF” values) may be specified by name. The list of colours recognised in the HTML standard is $_$_BEGIN_TABLE $_$_TABLE_HEADER_COLS 0 $_$_TABLE_BORDER 1 $_$_TABLE_ALIGN C Colour HTML Hex value -------------------------- Black #000000 Silver #C0C0C0 Gray #808080 White #FFFFFF Maroon #800000 Red #FF0000 Purple #800080 Fuchia #FF00FF Green #008000 Lime #00FF00 Olive #808000 Yellow #FFFF00 Navy #000080 Blue #0000FF Teal #008080 Aqua #00FFFF $_$_END_TABLE Only these values will be converted by the software to the equivalent names. Other names exist outside the standard which may not be universally supported. Active Link Colour .................. _Menu location: Conversion Options -> Output Policies -> Document Colours_ Identifies the colour of "active" hyperlinks, that is the colour of the hyperlink just as it is being selected. This value is a HTML colour that is used to set the ALINK attribute of the <BODY> tag. See also :- [[GOTO "Unvisited Link Colour"]] [[GOTO "Visited Link Colour"]] Background Colour ................. _Menu location: Conversion Options -> Output Policies -> Document Colours_ Identifies the background colour of the HTML page(s) created. This value is a HTML colour that is used to set the BGCOLOR attribute of the <BODY> tag. If omitted, AscToHTM defaults to a white background (I find Gray too dull) Text Colour ........... _Menu location: Conversion Options -> Output Policies -> Document Colours_ Identifies the text colour of the HTML page(s) created. This value is a HTML colour that is used to set the TEXT attribute of the <BODY> tag. Unvisited Link Colour ..................... _Menu location: Conversion Options -> Output Policies -> Document Colours_ Identifies the colour of "unvisited" hyperlinks, that is the colour of the hyperlink before it is selected for the first time. This value is a HTML colour that is used to set the LINK attribute of the <BODY> tag. See also :- [[GOTO "Active Link Colour"]] [[GOTO "Visited Link Colour"]] Visited Link Colour ................... _Menu location: Conversion Options -> Output Policies -> Document Colours_ Identifies the colour of "visited" hyperlinks, that is the colour of the hyperlink after is has been selected at least once. This value is a HTML colour that is used to set the VLINK attribute of the <BODY> tag. See also :- [[GOTO "Active Link Colour"]] [[GOTO "Unvisited Link Colour"]] $_$_HELP_CHAPTER 3,"CSS policies" CSS policies ------------ $_$_HELP_TOPIC_ID HIDD_CSS _Menu location: Conversion options -> Output policies -> Cascading style sheets (CSS)_ Cascading Style Sheets (CSS) allow styles to be added to HTML pages. They are supported in the Version 4 browsers, although the support can be variable. - [[popup Document Style Sheet]] Document Style Sheet .................... _Menu location: Conversion options -> Output policies -> Cascading style sheets (CSS)_ Style sheets are a feature recently added to HTML. They are supported by Internet Explorer and Netscape 4.0 and above. They may not be supported by earlier browsers. Style sheets allow you to specify the colours and fonts that you want added to your paragraphs, headers etc in your HTML. Normally you store all this detail in a cascading style sheet (.css) file and use a line of HTML in your <HEAD> section. In this way a uniform style can be added to all pages on your site and easily changed. This policy allows you to specify the URL of any style sheet you want to use. AscToHTM will then add the requisite HTML to the <HEAD> portion of your document. $_$_HELP_CHAPTER 3,"Directory page policies" Directory page policies ----------------------- $_$_HELP_TOPIC_ID HIDD_DIRECTORY _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ When converting many files at once, AscToHTM can generate a Directory Page, which lists all the files converted, complete with hyperlinks to the files and their contents. - [[popup Make Directory,Generate a directory page]] - [[popup Indent headings in Directory,Indent contents lines]] - [[popup Show file titles in directory]] - [[popup Directory filename]] - [[popup Split directory into pages]] - [[popup Maximum number of files per index page]] *Details* These details will go into the <HEAD>...</HEAD> of the directory page. - [[popup Directory title]] - [[popup Directory description]] - [[popup Directory keywords]] - [[popup Directory return hyperlink text,Text on hyperlink back to directory page]] *Include files* These policies allow you insert files containing HTML into your output directory page at particular locations. - [[popup Directory header file,Header HTML file]] - [[popup Directory footer file,Footer HTML file]] - [[popup Directory script file,Script file (copied to the <HEAD> section)]] Split directory into pages .......................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ When enabled the directory "page" will be split into several smaller, linked pages. This can be useful when building an index for a large number of files all being converted at once. This option will only take effect if the [[popup Maximum number of files per index page]] is set to be greater than 0. There is no policy line for this option as such, instead the value of [[popup Maximum number of files per index page]] is simply set to 0 if this option is disabled. Maximum number of files per index page ...................................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies how many files should have their contents added to a directory page before a new page is started. A value of 0 indicates that no splitting of the directory page is wanted. So for example if you elected to build a directory whilst converting 100 files in a single pass, a value of 20 would mean that you'd end up with 5 index pages all linked together, each detailing the contents list of 20 files. Make Directory .............. $_$_HELP_TOPIC_ID ID_MAKE_DIRPAGE _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This policy specifies whether or not you want a directory page created when converting multiple files. _This appears on-screen as "Generate a directory page"_ Indent headings in Directory ............................ $_$_HELP_TOPIC_ID ID_DIRCONTENTS _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This policy specifies whether or not AscToHTM should indent the hyperlinks to the sections contained in the documents being converted. If this is disabled, then all the contents hyperlinks will be indented one level relative to file titles. _This appears on-screen as "Indent contents lines"_ Directory filename .................. $_$_HELP_TOPIC_ID ID_DIRFILENAME _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This policy specifies the name of the index file. If a file of this name already exists it will be overwritten. Show file titles in directory ............................. $_$_HELP_TOPIC_ID ID_DIRSHOWTITLES _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This policy specifies whether or not the directory page should include a title line for each file being converted. This will either be the title of each file, or the filename. Directory title ............... $_$_HELP_TOPIC_ID ID_DIRTITLE _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies the text to be used by default in the <TITLE>...</TITLE> tags in the <HEAD>...</HEAD> section of the generated HTML pages. Directory description ..................... $_$_HELP_TOPIC_ID ID_DIRDESCRIPTION _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies text that will be inserted into a <META> tag in the <HEAD> portion of your directory page. This description is used by search engines when indexing your page, and may be shown as the summary of your page when people search for it. This text is not normally visible in a browser. Directory keywords .................. $_$_HELP_TOPIC_ID ID_DIRKEYWORDS _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies text that will be inserted into a <META> tag in the <HEAD> portion of your directory page. These keywords will be used by search engines when indexing your page. You should add here any keywords that summarise the contents of your page, and in particular include words not actually in the document, or alternative spellings (e.g. American versus UK English). This text is not normally visible in a browser. Directory return hyperlink text ............................... $_$_HELP_TOPIC_ID ID_DIRBACKTEXT _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This is the text shown on the hyperlink back to the directory page. This link is inserted into each HTML document generated to allow navigation back to the directory index. _This appears on-screen as "Text on hyperlink back to directory page"_ The default value is “Directory”. Directory header file ..................... $_$_HELP_TOPIC_ID ID_DIRHEADER _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies the name of a text file whose contents will be copied into the directory page. The contents of this file will be inserted just after the <BODY> tag, and *before* any generated contents of the directory page. This file should be accessible at conversion time, and will normally contain some standard text or HTML that you want including at the top of the visible page. If omitted the same header file as used for the individual HTML files will be used. Directory footer file ..................... $_$_HELP_TOPIC_ID ID_DIRFOOTER _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies the name of a text file whose contents will be copied into the directory page. The contents of this file will be inserted just before the closing </BODY> tag, and *after* all of the generated contents of the directory page. This file should be accessible at conversion time, and will normally contain some standard text or HTML that you want including at the top of the visible page. If omitted the same footer file as used for the individual HTML files will be used. Directory script file ..................... $_$_HELP_TOPIC_ID ID_DIRSCRIPT _Menu location: Conversion options -> Output policies -> File Generation -> Directory Page_ This specifies the name of a text file whose contents will be copied into the directory page. The contents of this file will be inserted into the <HEAD>...</HEAD> section of the directory page. This file should be accessible at conversion time, and will normally contain some HTML that you want including at the HTML <HEAD>...<HEAD> section. Note, tags inserted at this point are not normally visible, and as such this file should only contain relevant HTML such as <META> tags or JavaScript... hence the name. $_$_HELP_CHAPTER 3,"File generation policies" File generation policies ------------------------ $_$_HELP_TOPIC_ID HIDD_FILEGEN _Menu location: Conversion options -> Output policies -> File generation -> General_ These policies determine some general options for the HTML file generation. *DOS Compatibility* - [[popup Use DOS filenames,Generate DOS-compatible filenames]] - [[popup DOS filename root]] *File extensions* - [[popup Use .HTM extension,File extensions]] - [[popup Output file extension,Alternative file extension]] *Diagnostics Files* - [[popup Generate diagnostics files,Generate log files]] - [[popup Output policy file,Generate sample policy file]] - [[popup Output policy filename]] *Line and file structures* - [[popup Preserve file structure using <PRE>]] - [[popup Preserve line structure]] - [[popup Treat each line as a paragraph]] - [[popup Break up long HTML lines]] Preserve file structure using <PRE> ................................... $_$_HELP_TOPIC_ID ID_PRESERVEFILE _Menu location: Conversion options -> Output policies -> File generation -> General_ This policy can be used to place the whole file inside <PRE>...</PRE> markup. This will use a mono-spaced font that preserves the line structure and the relative spacing of characters. When this is enabled almost all of the program’s other conversion options will be disabled. You should only really use this if your document has a lot of formatting that the program is failing to understand. This policy needs to be set manually where wanted. Preserve Line structure ....................... $_$_HELP_TOPIC_ID ID_PRESERVELINES _Menu location: Conversion options -> Output policies -> File generation -> General_ This policy specifies that the line structure of the original document should be preserved, rather than just the paragraph structure. If enabled the lines in the output document will match those of the original document, and the text will not automatically be adjusted if you widen your window. On large monitors this will give the text an “A4” look and feel. This policy needs to be set manually where wanted. Treat each line as a paragraph .............................. $_$_HELP_TOPIC_ID ID_TREATLINESASPARAS _Menu location: Conversion options -> Output policies -> File generation -> General_ Some files do not break large paragraphs into smaller lines, but instead place the whole paragraph on a single line. This is especially true if the source file was created by a text editor that relied on word wrap (such as Notepad or Word). These files often have no blank lines between paragraphs, which makes detecting where paragraphs begin and end more difficult. In such files this policy can be enabled so that each “line of text” in the source file will be treated as a separate paragraph. This policy cannot be automatically detected, and so needs to be set manually where wanted. Break up long HTML lines ........................ _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> File generation -> General_ Specifies that long HTML lines should be broken into smaller ones. This attempts to make the HTML more readable, should you need to edit it afterwards. However, there is the possibility that the insertion of newline characters into the output could affect how the HTML is displayed. This is because most of the browsers have bugs in their parsing of newlines. These problems are most pronounced when using non-standard (12pt) font sizes. If you experience such problems, try disabling this policy. Generate diagnostics files .......................... $_$_HELP_TOPIC_ID ID_GENLOGS _Menu location: Conversion options -> Output policies -> File generation -> General_ This policy allows you to specify the generation of some diagnostics files. AscToHTM will generate 3 files with the following extensions: $_$_BEGIN_TABLE .lis1 A line-by-line summary of how AscToHTM analysed the source file during the analysis pass .lis A line-by-line summary of how AscToHTM analysed the source file during the output pass .stats A statistics file $_$_END_TABLE The .lis file will give the best description of how the source file has been converted. The differences between the .lis1 and .lis files can be slight, and are down to fact that on the output pass more rigorous attention is applied to the policies. Any error messages generated during the conversion are inserted into the .lis file at the offending line. This will help you determine how relevant they are. _This appears on-screen as "Generate log files"_ Output policy file .................. $_$_HELP_TOPIC_ID ID_GENSAMPLE _Menu location: Conversion options -> Output policies -> File generation -> General_ This policy allows you to generate a policy file containing all the policies used during the output pass. This will help you understand how AscToHTM has interpreted your document, and may help in determining where the analysis may have gone wrong and need correcting. Note, this file will contain all the policies used, and as such is probably not suited for use as an input policy. _This appears on-screen as "Generate sample policy file"_ See the discussion in [[goto Generating a policy file for your document]] Output policy filename ...................... _Menu location: Conversion options -> Output policies -> File generation -> General_ When [[popup output policy file]] is selected, this allows you to specify the name of the policy file you want created. Use .HTM extension .................. $_$_HELP_TOPIC_ID ID_FILEEXTN _Menu location: Conversion options -> Output policies -> File generation -> General_ This specifies the type of file extension to be used for the generated files. Note, if DOS-compatible filenames are chosen “.HTM” will be used, otherwise the options are “.html”, “.htm” or other On-screen this appears as a radio button for selecting file extensions. If .HTM is selected this policy is set to true, otherwise it is false. If "Other" is selected, then the Other value is set via the [[popup Output file extension]] policy is used (which appears on-screen as "Alternative file extension"). Output file extension ..................... $_$_HELP_TOPIC_ID ID_ALTEXTN _Menu location: Conversion options -> Output policies -> File generation -> General_ This specifies that an alternative file extension (e.g. “.shtml”) should be used for the generated files. _This appears on-screen as "Alternative file extension"_ Use DOS filenames ................. $_$_HELP_TOPIC_ID ID_DOSCOMP _Menu location: Conversion options -> Output policies -> File generation -> General_ By default AscToHTM uses the input filename to generate the output filename. Often this name is not DOS-compatible. If you set this flag AscToHTM will ensure all filenames are DOS compatible as follows: A five-letter filename root will be calculated. This will either be the first 5 letters of the input filename, or the DOS file root specified in policy. If generating many files, the section numbers N, N.N, N.N.N are appended in the form _N, _N_N etc. If the resulting filename exceeds 8 characters a unique name is generated consisting of 3 letters and 5 numbers. The 3 letters are the first three letters of the DOS root. The extension .htm is added. _This appears on-screen as "Generate DOS-compatible filenames"_ DOS filename root ................. $_$_HELP_TOPIC_ID ID_DOSROOT _Menu location: Conversion options -> Output policies -> File generation -> General_ If DOS compatibility is selected, this is the up-to-5 letter DOS file root used in generating filenames. If omitted the first 5 characters of the input filename is used instead. $_$_HELP_CHAPTER 3,"File splitting policies" File splitting policies ----------------------- $_$_HELP_TOPIC_ID HIDD_FILESPLIT _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ These policies determine how - if at all - the source document is to be converted into one or more output HTML files. AscToHTM can split the output at heading boundaries, and ensure that hyperlinks work across the suite of output HTML files. In addition, a navigation bar can be added to each page, taking you to the next and previous HTML document, and back to the contents list. [[popup split level,Split into several HTML files]][[br]] *HTML file creation* - [[popup split level,Split at which heading level]] - [[popup Min HTML file size,Minimum output file size]] - [[popup Minimise HTML file size]] - [[popup Add navigation bar]] - [[popup Split at page markers]] *File naming* - [[popup Number of words to include in filename]] - [[popup Use numbered sequence in file names]] Split level ........... $_$_HELP_TOPIC_ID ID_SPLITLEVEL _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ If the output file is being split into several HTML files, this policy determines at which heading level the file is split. Splits will occur at each heading at the specified level or above. For example, a value of 2 will create a new page starting on section 1 and section 1.1, but section 1.1.1 will not create a new page, and will thus be copied into the page containing section 1.1. The HTML pages created will have the section number appended to the file root, thus in this case a file source.txt would create files source_1.html, source_1_1.html etc. _This appears on-screen as the two options "Split into several HTML pages" and "split at what heading level". If the first is unchecked, the value is set to 0, meaning no splitting will occur._ This should be set manually, or loaded from a policy file. See the discussion in [[goto Splitting large files into a linked set of smaller files]] Min HTML file size .................. $_$_HELP_TOPIC_ID ID_MINOUTSIZE _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ If the output file is being split into several HTML files, this policy determines the minimum number of lines to be added to each HTML file. This is sometimes useful when a sub-section follows immediately after a heading. By setting this value large enough you can avoid having an HTML created with only the major section heading in it. This should be set manually, or loaded from a policy file. _This appears on-screen as "Minimum output file size"_ See the discussion in [[goto Splitting large files into a linked set of smaller files]] Add navigation bar .................. $_$_HELP_TOPIC_ID ID_ADDNAVBAR _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ If the output file is being split into several HTML files, this policy determines whether or not a navigation bar should be added at the foot of each HTML page generated. This navigation bar will include - a link to the previous HTML page (if any) - a link to the next HTML page (if any) - a link to the contents list (if any) at the start of the next section This should be set manually, or loaded from a policy file. See the discussion in [[goto Splitting large files into a linked set of smaller files]] Minimise HTML file size ....................... $_$_HELP_TOPIC_ID ID_MAKE_SMALL_FILE _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ This policy indicates that the created HTML files should be optimised for size. This is done by eliminating unnecessary white space in the output. AscToHTM adds white space to make the HTML more readable. The choice here is to sacrifice the readability and edibility of the HTML to produce a file that will download faster. Typically the files are around 10% smaller, but in a file that consists of many tables the savings can be more like 30%. Split at page markers ..................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ Specifies that the document should be split into smaller HTML pages at the page markers. The first file created normally has a name that matches the source file. Subsequent files append the page number (_1, _2...) Number of words to include in filename ...................................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ When splitting a large document into files a new file will be created each time a suitable heading is reached. If the heading is underlined or capitalised (as opposed to numbered), the first few words of the heading will be included in the filename. This policy determines how many words from the title should be used. Use numbered sequence in file names ................................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> File generation -> Splitting large files_ When splitting a large document into files this option allows you to name your output files using a numbering sequence. Previously the file names would attempt to come from the first heading and it was possible to get duplicates. Enabling this option means that when converting filename.txt, it will be split into filename_1.html, filename_2.html etc, etc, giving more consistent and orderly filenames. $_$_HELP_CHAPTER 3,"Font policies" Font policies ------------- $_$_HELP_TOPIC_ID HIDD_FONTS _Menu location: Conversion options -> Output policies -> Fonts_ *Fonts* Normal text [[popup Default font]] Headings [[popup Heading Font]] Text in tables [[popup Table font]] Table of contents [[popup Table of contents Font, TOC Font]] Fixed-pitch text [[popup Fixed font]] *Implementation* [[popup Use CSS to implement fonts,Font Implementation]] Default font ............ $_$_HELP_TOPIC_ID ID_DEFAULTFONT _Menu location: Conversion options -> Output policies -> Fonts_ This specifies the default font to be used. It may be edited via a normal Windows Font selection dialog. Heading font ............ $_$_HELP_TOPIC_ID ID_HEADINGFONT _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Fonts_ This specifies the default font to be used for headings. The actual headings will be based on this font family, but will be made larger and or italic according to the level of heading applied to a given heading. It may be edited via [[popup the Font selection dialog]]. Table font .......... $_$_HELP_TOPIC_ID ID_TABLEFONT _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Fonts_ This specifies the default font to be used inside tables. This will default to the [[popup Default Font]], but you may want to set it smaller in order to fit wide tables on the page. It may be edited via [[popup the Font selection dialog]]. Table of contents Font ...................... $_$_HELP_TOPIC_ID ID_TOCFONT _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Fonts_ This specifies the default font used in any generated Table of Contents. The font family specified will be used, but the different levels of heading in the list will be given different sizes and italics, just as in a default Word document. It may be edited via [[popup the Font selection dialog]]. _This policy appears on-screen as "TOC font"_ Fixed font .......... $_$_HELP_TOPIC_ID ID_FIXEDFONT _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Fonts_ This specifies the default font to be used for ASCII art and diagrams and other portions of text where the spacing is to be preserved. For this a mono-spaced font such as Courier is usually used. The Font size is also usually set a bit smaller at 8pt. This is to ensure that an 80-character "line" in the original document will fit on a page in the output document. It may be edited via [[popup the Font selection dialog]]. The Font Selection Dialog ......................... Each of the font values may be chosen using the font selection dialog. The selected font is shown as a comma-separated list containing :- - The font name - The font characteristics ("Regular", "bold", "italic" or "bold italic") - The font size (in pts) Depending on the font concerned some of these attributes may be ignored. For example when selecting the font for headings the sizes of different headings are different, based on the selected value. Use CSS to implement fonts .......................... $_$_HELP_TOPIC_ID ID_FONTIMPLEMENTATION _Menu location: Conversion options -> Output policies -> Fonts_ This specifies whether or not CSS should be used to implement any selected fonts for the document. This is enabled by default. _This appears on-screen as a choice of "implementation" as follows_ - Using Cascading Style sheets (CSS). In this case the desired font is implemented by adding a <STYLE>..</STYLE> section to the head of each HTML page generated. - Using <FONT>...</FONT> markup. In HTML 4.0 onwards the use of CSS is encouraged (indeed in Strict HTML 4.0 the <FONT> tag is no longer permitted). There are many advantages of CSS chief amongst which are reduced file sizes and the clean separation of style from content, allowing users to substitute their own styles (e.g. larger fonts, clearer colours etc). CSS is supported to various degrees by all of the version 4 and above browsers. The CSS generated by AscToHTM lies well within the capabilities of all these browsers. By contrast using <FONT> tags leads to larger files, less user control and is actually not permitted in strict HTML 4.0 and above. That said it is supported by earlier browsers. We advise you use CSS (the default behaviour), and only consider switching to using <FONT> tags if you experience problems, or have a significant proportion of your target audience using older (V3 and earlier) browsers. Base font size (in pts) ....................... $_$_HELP_TOPIC_ID ID_BASEFONT *Deprecated in version 5.0* This specifies the default font size to be used for the document. The size is specified in points, with 12pt corresponding to HTML size 3. Delta font size (in pts) ........................ $_$_HELP_TOPIC_ID ID_DELTAFONT *Deprecated in version 5.0* This specifies an increment in font sizes to be applied to the document. Each <FONT> tag generated will have its size adjusted by this amount. This can be used to make text universally larger or smaller. $_$_HELP_CHAPTER 3,"Frames policies" Frames policies --------------- $_$_HELP_TOPIC_ID HIDD_FRAMES _Menu location: Conversion options -> Output policies -> Frames_ From version 4 onwards AscToHTM supports placing the generated HTML in FRAMES. These policies can be used to fine-tune the process. *Policies that apply to frames generation in general* - [[popup Place document in frames]] - [[popup Output frame name,File frame name]] - [[popup Open frame links in new window]] - [[popup New frame link window name,New window name]] - [[popup Add frame border]] - [[popup Add NOFRAMES links]] - [[popup NOFRAMES link URL]] *Frame colours* - A button will take you to the [[goto Frame colours dialog]]. *“Header” frame policies* - [[popup header frame depth,Frame depth]] - [[popup Use main header in header frame,Use any header defined for main pages]] *”Contents” frame policies* - [[popup Add contents frame if possible]] - [[popup Number of levels in contents frame,Number of contents levels]] - [[popup contents frame width,Frame width]] *”Main” frame policies* - [[popup Split level, Split into several HTML files]] - [[popup Split level, Split at what level]] - [[popup First frame page number,First page to show in main frame]] *”Footer frame policies* - [[popup footer frame depth,Frame depth]] - [[popup Use main footer in footer frame,Use any footer defined for main pages]] - [[popup Only allow pages to be viewed in frames]] For a fuller discussion see [[goto Generating a set of Frames]]. Place document in frames ........................ $_$_HELP_TOPIC_ID ID_FRAMES_FRAMES _Menu location: Conversion options -> Output policies -> Frames_ This policy allows you to specify that you want your document output in HTML frames. The program will create a HTML page with the necessary <FRAMESET> tags. Output frame name ................. $_$_HELP_TOPIC_ID ID_FRAMES_NAME _Menu location: Conversion options -> Output policies -> Frames_ This specifies the name of the HTML file which will contain the FRAMESET tags that define the layout and contents of the FRAMES. If omitted the default behaviour is to append "_frame" to the filename. For example myfile.txt would generate myfile_frame.html FRAMESET file myfile_contents_frame.html (optional) contents frame myfile_header_frame.html (optional) header frame myfile_footer_frame.html (optional) footer frame and then myfile.html first main frame page myfile_1.html (optional) second main frame page ... ... Open frame links in new window ................................ $_$_HELP_TOPIC_ID ID_FRAMES_NEWWINDOW _Menu location: Conversion options -> Output policies -> Frames_ This specifies that whenever you click on an "External" hyperlink inside a set of generated FRAMES, a new window should be opened, rather than displaying the selected page inside the current FRAMESET. Note, the program distinguishes between "internal" links to other parts of the same converted document (be they in a different HTML page or whatever) and "external" links to URLs nothing to do with the current conversion. Thus a link to www.jafsoft.com will create a new window, but a link to section 3.2 will not. See also [[popup New frame link window name]] New frame link window name .......................... $_$_HELP_TOPIC_ID ID_FRAMES_NEWWINDOWNAME _Menu location: Conversion options -> Output policies -> Frames_ When an "external" hyperlink is clicked on from inside a generated FRAMESET and the policy [[popup Open frame links in new window]] is enabled, this is the name of the browser window to be used as the target for the link. You can specify any name you like, but the default is the reserved browser window name "_top" which will cause the current window to be used, thereby replacing all the FRAMESET currently on display (this will re-appear if you press the BACK button) Add frame border .................... $_$_HELP_TOPIC_ID ID_FRAMES_BORDER _Menu location: Conversion options -> Output policies -> Frames_ This specifies whether or not you want visible borders on your frames. If the borders are visible then users will be able to select and move them to resize the frames to a size that suits them. Add NOFRAMES links .................. $_$_HELP_TOPIC_ID ID_FRAMES_NOFRAMES _Menu location: Conversion options -> Output policies -> Frames_ Specifies that a NOFRAMES link should be added to the Contents frame. You can choose the target of this link using the [[popup NOFRAMES link URL]] policy. The NOFRAMES link will target the "_top" browser window, thereby replacing the current FRAMESET by the single page selected without creating new browser windows. NOFRAMES links are useful courtesy to users who dislike FRAMES, and they are also search-engine friendly. Note, this link is a *visible* NOFRAMES link. In addition to this the software will in any case create a non-visible <NOFRAMES> tag that will allow users whose browsers do not support FRAMES to access your content. NOFRAMES link URL ................. $_$_HELP_TOPIC_ID ID_FRAMES_NOFRAMESURL _Menu location: Conversion options -> Output policies -> Frames_ When the [[popup Add NOFRAMES links]] policy is enabled, this is the URL that is used in the visible NOFRAMES hyperlink added to the contents frame. If left blank (the default) this link will point to the first HTML page that would normally be displayed in the main frame. You should only really need to use this if you have created an independent set on non-FRAMES pages that you'd like to link to instead. Header frame depth .................. $_$_HELP_TOPIC_ID ID_FRAMES_HEADERDEPTH _Menu location: Conversion options -> Output policies -> Frames_ If a header frame is generated, this specifies its depth. The default is 100 pixels. To specify a percentage, add the % sign on the end, e.g. "20%" Use main header in header frame ............................... $_$_HELP_TOPIC_ID ID_FRAMES_USEHEADER _Menu location: Conversion options -> Output policies -> Frames_ When this policy is set the software will attempt to move any HTML header defined for each page into a header frame. This allows the same policy file to be used for both FRAMES and non-FRAMES generation. In non-FRAMES generation the supplied header will be included at the top of each page generated. If this policy is enabled, then in FRAMES generation the supplied header will be placed in a header frame, and omitted from each page generated. This means the header will always be visible in the header frame, as the generated pages are displayed and scrolled in the main frame. Further modification of this behaviour is possible by using the [[goto Using HTML fragments,HTML fragments]] feature to define specific HTML fragments to be used in particular frames. Add contents frame if possible .............................. $_$_HELP_TOPIC_ID ID_FRAMES_ADDCONTENTS _Menu location: Conversion options -> Output policies -> Frames_ This specifies that, if possible, a contents frame should be placed on the left of the screen to hold a generated contents list. Alternatively a CONTENTS_FRAME HTML [[goto Using HTML fragments,HTML fragments]] can be defined Generated contents lists are only possible when the program recognises headings inside your text file, so you may need to get that working first. If no content for the contents frame is possible, a WARNING message is generated. Number of levels in contents frame .................................. $_$_HELP_TOPIC_ID ID_FRAMES_CONTENTSLEVELS _Menu location: Conversion options -> Output policies -> Frames_ When a generated contents list is placed in a contents frame, this policy specifies how many levels of heading you want shown there. In large, complex documents there can be up to 4 levels of heading. Whilst in a normal contents list you'd want to see most of these, in a FRAMES document space (width) is tight and you don't really want to have to scroll the left frame. In such cases you may want to limit the amount of detail in the contents frame. The default value "0" is interpreted as "all", i.e. a full contents list will be generated. Contents frame width .................... $_$_HELP_TOPIC_ID ID_FRAMES_CONTENTSWIDTH _Menu location: Conversion options -> Output policies -> Frames_ If a contents frame is generated, this specifies its width. The default is 200 pixels. To specify a percentage, add the % sign on the end, e.g. "30%" First frame page number ....................... $_$_HELP_TOPIC_ID ID_FRAMES_FIRSTPAGE _Menu location: Conversion options -> Output policies -> Frames_ This specified the "page number" of the main document that you initially want shown in the main frame of the FRAMESET. When converting large documents you can choose to split them into many smaller pages. Often such documents have a contents list as the sole content of the first page, and inside a FRAMES document his has the unfortunate side-effect of displaying a contents list in the main frame next to a contents list in the contents frame. In such cases you might choose to start by initially displaying the *second* page in the main frame. That's what this policy is for. _This appears on-screen as "First page to show in 'main' frame"_ Footer frame depth .................. $_$_HELP_TOPIC_ID ID_FRAMES_FOOTERDEPTH _Menu location: Conversion options -> Output policies -> Frames_ If a footer frame is generated, this specifies its depth. The default is 100 pixels. To specify a percentage, add the % sign on the end, e.g. "20%" Use main footer in footer frame ............................... $_$_HELP_TOPIC_ID ID_FRAMES_USEFOOTER _Menu location: Conversion options -> Output policies -> Frames_ When this policy is set the software will attempt to move any HTML footer defined for each page into a footer frame. This allows the same policy file to be used for both FRAMES and non-FRAMES generation. In non-FRAMES generation the supplied footer will be included at the top of each page generated. If this policy is enabled, then in FRAMES generation the supplied footer will be placed in a footer frame, and omitted from each page generated. This means the footer will always be visible in the footer frame, as the generated pages are displayed and scrolled in the main frame. Further modification of this behaviour is possible by using the [[goto Using HTML fragments,HTML fragments]] feature to define specific HTML fragments to be used in particular frames. Only allow pages to be viewed in frames ....................................... $_$_HELP_TOPIC_ID ID_FRAMES_ONLY _Menu location: Conversion options -> Output policies -> Frames_ This specifies that you only want your frame pages to be viewed inside frames. If this is selected some JavaScript is added to the page to force a refresh in frames if a browser should come direct to one of the pages. You might want this if a search engine indexes your individual pages. If that happens visitors may come to a single page and not see the surrounding frames. $_$_HELP_CHAPTER 3,"Frame colours dialog" Frame colours dialog -------------------- $_$_HELP_TOPIC_ID HIDD_FRAME_COLOUR _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ This dialog allows you to choose the colours used in each frame. By default all the frames will default to the colours of the main frame, which in turn will use the colours usually set for non-frames production. - [[popup Contents frame background colour]] - [[popup Contents frame text colour]] - [[popup Footer frame background colour]] - [[popup Footer frame text colour]] - [[popup Header frame background colour]] - [[popup Header frame text colour]] Contents frame background colour ................................ _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ _Only applies to FRAMES production when HTML is being generated_ See discussion in [[GOTO Header frame background colour]]. Contents frame text colour .......................... _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ _Only applies to FRAMES production when HTML is being generated_ See discussion in [[GOTO Header frame background colour]]. Footer frame background colour .............................. _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ _Only applies to FRAMES production when HTML is being generated_ See discussion in [[GOTO Header frame background colour]]. Footer frame text colour ........................ _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ _Only applies to FRAMES production when HTML is being generated_ See discussion in [[GOTO Header frame background colour]]. Header frame background colour .............................. _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ _Only applies to FRAMES production when HTML is being generated_ The program allows you to independently set the background and colour of each frame in a FRAMESET. The default behaviour is that each frame will match the colours set for the main document using the policies [[GOTO Background Colour]] [[GOTO Text Colour]] You can override this behaviour using the frame colouring policies [[GOTO Header frame background colour]][[br]] [[GOTO Header frame text colour]][[br]] [[GOTO Contents frame background colour]][[br]] [[GOTO Contents frame text colour]][[br]] [[GOTO Footer frame background colour]][[br]] [[GOTO Footer frame text colour]] Header frame text colour ........................ _Menu location: Conversion options -> Output policies -> Frames_ [[br]] _(then press the "Edit frame colours >>>" button)_ _Only applies to FRAMES production when HTML is being generated_ See discussion in [[GOTO Header frame background colour]]. $_$_HELP_CHAPTER 3,"Hyperlink policies" Hyperlink policies ------------------ $_$_HELP_TOPIC_ID HIDD_HYPERLINKS _Menu location: Conversion options -> Output policies -> Hyperlinks_ _Add hyperlinks_ - [[popup Create hyperlinks,http:// and www references]] - [[popup Create mailto links, Convert Email references]] - [[popup Allow email beginning with numbers, Allow email addresses that begin with a number]] - [[popup Check domain name syntax]] - [[popup Create Gopher links, Convert Gopher references]] - [[popup Create Telnet links, Convert Telnet references]] - [[popup Create FTP links, Convert FTP references]] - [[popup Only allow explicit FTP links, Convert "weak" FTP references]] - [[popup Create NEWS links, Convert USENET newsgroup references]] - [[popup Only use known groups, Convert only recognised USENET newsgroups]] - [[popup Recognised USENET groups, Additional hierarchies to recognize]] - [[popup Add <BR> to lines with URLs]] - [[popup Max length of heading links]] whole first paragraph would be treated as a title/heading. _Hyperlinks to other section numbers_ - [[popup Cross-refs at level,Convert cross-references to other sections]] _Browser behaviour when hyperlink selected_ - [[popup Open links in new browser window]] - [[popup New browser window name]] See also the comments in the [[goto adding hyperlinks]] section. Create hyperlinks ................. $_$_HELP_TOPIC_ID ID_CONVERTHTTP _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that all valid "http" and www references that are found should be turned into active hyperlinks. Such hyperlinks may sometimes get confused by surrounding punctuation characters. _This appears on-screen as "http:// and www references"_ Create mailto links ................... $_$_HELP_TOPIC_ID ID_CONVERTEMAIL _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that all valid email addresses that are found should be turned into active "mailto" hyperlinks. AscToHTM has no way of checking email addresses, so "made up" addresses will also get converted, although the domain name will be validated. An extra option allows email addresses beginning with a number to be accepted. Often USENET message IDs have an email format, but start with a number, so by Default these are not converted to email hyperlinks. _This appears on-screen as "Convert email references"_ Allow email beginning with numbers .................................. $_$_HELP_TOPIC_ID ID_EMAILNUMBERS _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies whether or not email addresses that begin with numbers are allowed or now. The program has no way of validating email addresses. Often documents - especially Usenet posts and the like - contain message Ids that look like email addresses but aren't. These usually become with a number, and so by default the program will ignore "addresses" in this form. On the other hand some ISPs (e.g. older CompuServe accounts) allow email addresses that start with numbers. You should toggle this policy according to which is more appropriate for your documents. _This appears on-screen as "Allow email addresses that begin with a number"_ Create FTP links ................ $_$_HELP_TOPIC_ID ID_CONVERTFTP _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that all FTP addresses that are found should be turned into active hyperlinks. These will usually start with "ftp://" or be a domain name starting "ftp.". However quite often FTP sites have domain names that don't start with "ftp." But do end in a recognised domain type such as ".com". An extra option allows the program to convert such "weak" or implicit FTP references into FTP links. See [[popup Only allow explicit FTP links]] _This appears on-screen as "Convert FTP references"_ Only allow explicit FTP links ............................. $_$_HELP_TOPIC_ID ID_FTPWEAK _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that all "internet" addresses which don't start with "www." or "ftp." Should be regarded as FTP sites. Often FTP sites have domain names that don't start with "ftp." But do end in a recognised domain type such as ".com". For example rtfm.mit.edu is a well known archive. _This appears on-screen as "Convert "weak" FTP references"_ Create Gopher links ................... $_$_HELP_TOPIC_ID ID_CONVERTGOPHER _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that all gopher addresses that are found should be turned into active hyperlinks. These will usually start with "gopher://". _This appears on-screen as "Convert Gopher references"_ Create Telnet links ................... $_$_HELP_TOPIC_ID ID_CONVERTTELNET _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that all telnet addresses that are found should be turned into active hyperlinks. These will usually start with "telnet://". _This appears on-screen as "Convert Telnet references"_ Check domain name syntax ........................ $_$_HELP_TOPIC_ID ID_CHECKSYNTAX _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies whether or not potential URLs should have their "domain name" checked against the known domain name structures, (i.e. ends in .com, .org, .co.uk etc). Having this switched on reduces the likelyhood of invalid URLs being turned into clickable links that don't go anywhere. Note, the software doesn't check the domain *exists*, only that the domain name obeys the known rules. You might want to switch this off if your document contains URLs that don't use standard domain names (e.g. they are inside an Intranet). Create NEWS links ................. $_$_HELP_TOPIC_ID ID_CONVERTNEWS _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that AscToHTM should attempt to identify Usenet newsgroup names and turn them into active "news" hyperlinks. AscToHTM has no way of checking newsgroup names, so by default it will only convert names in recognised hierarchies such as alt.,comp.,rec. etc. _This appears on-screen as "Convert USENET newsgroup references"_ Only use known groups ..................... $_$_HELP_TOPIC_ID ID_KNOWNONLY _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that when detecting Usenet newsgroup names, AscToHTM should only convert names in recognised hierarchies such as alt.,comp.,rec. etc.. You can get the program to recognize additional hierarchies. _This appears on-screen as "Convert only recognised USENET newsgroups"_ Recognised USENET groups ........................ $_$_HELP_TOPIC_ID ID_OTHERGROUPS _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that when detecting Usenet newsgroup names, AscToHTM should additionally allow "newsgroups" in these hierarchies in addition to the standard hierarchies such as alt.,comp.,rec. etc. _This appears on-screen as "Additional hierarchies to recognize"_ Cross-refs at level ................... $_$_HELP_TOPIC_ID ID_CONVERTXREF _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies whether the level of heading at which AscToHTM should turn references to section numbers in the main text to hyperlinks to those sections. This is only possible for numbered sections. If selected, you should specify the level at which such cross-references should start. A value of "1" will attempt to convert all numbers N, N.N... to hyperlinks. A value of two will attempt to convert N.N, N.N.N... etc. This policy is quite prone to error (e.g. Windows 3.1 often becomes a hyperlink to section 3.1). Consequently lower values are more error prone. A value of "2" is set by default. Later versions may address this problem. _This appears on-screen as "Convert cross-references to other sections"_ Add <BR> to lines with URLs ........................... $_$_HELP_TOPIC_ID ID_ADDBR _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that when a line is found to have a URL on it, a <BR> will be added to the output line. This will preserve the line structure of the original document. This can be useful where you have a list of URLs, one-per-line. It’s less useful for a document where URLs are embedded in normal text. Max length of heading links ........................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Hyperlinks_ This option sets a limit on the length of headings used as titles for the generated HTML pages, or as hyperlinks in generated contents lists or directory pages. When set to a non-zero value the heading text will be truncated back to the last end sentence period, or failing that space. When links are truncated, this is attempted to be at a word boundary, and the ellipsis "..." is added to indicate a truncated link. This option can be useful when headings are very long, or when options such has [[popup Use first heading as title]] or [[popup use first line as heading]] or [[popup Use first line as Title]] are used on a file that places each paragraph on a single line (i.e. no line breaks). In such cases the Open links in new browser window ................................ $_$_HELP_TOPIC_ID ID_NEW_BROWSER _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies that where hyperlinks are added to the HTML, the target window for these links should be a new window. This means that when you click on these links a new window is opened, and the original window continues to display the original document. If you don't select this policy, the new document replaces the old document in the current browser window. See also :- [[goto "New browser window name"]] New browser window name ....................... $_$_HELP_TOPIC_ID ID_NEW_BROWSER_NAME _Menu location: Conversion options -> Output policies -> Hyperlinks_ This specifies whether or not AscToHTM should turn references to section numbers in the main text to hyperlinks to those sections. $_$_HELP_CHAPTER 3,"Pre-processor policies" Pre-processor policies --------------------- $_$_HELP_TOPIC_ID HIDD_PREPROCESSOR _Menu location: Conversion options -> Output policies -> Pre-processor_ A few policies can be used to control the use of the pre-processor. For details of how the pre-processor works and the tags available see the [Tag Manual] that comes as part of the [[goto Documentation available,HTML documentation]] - [[goto Use Preprocessor]] - [[goto Include document section(s)]] - [[goto Allow definitions inside PRE,Allow definitions inside a user <PRE> section]] Use Preprocessor ................ _Menu location: Conversion options -> Output policies -> Pre-processor_ When enabled the pre-processor is activated. You would only ever want to de-activate it to see what difference not processing an pre-processor commands would make. Include document section(s) ........................... _Menu location: Conversion options -> Output policies -> Pre-processor_ This is a comma-separated list of which SECTION's you want included in your document. This only applies if you've made use of the [[goto Pre-processor command: SECTION, SECTION]] command to mark up parts of your document to be conditionally output during the conversion. Allow definitions inside PRE ............................ $_$_HELP_TOPIC_ID ID_ALLOWDEFNS _Menu location: Conversion options -> Output policies -> Pre-processor_ This options specifies that where user specified pre-formatted text are used, should AscToHTM search for definitions lines. This is only relevant should you wish definitions to be highlighted in such cases. $_$_HELP_CHAPTER 3,"Style policies" Style policies -------------- $_$_HELP_TOPIC_ID HIDD_STYLE _Menu location: Conversion options -> Output policies -> HTML styling_ *Miscellaneous* - [[popup Allow automatic centring]] - [[popup Automatic centring tolerance,Centring Tolerance (in characters)]] - [[popup Ignore multiple blank lines]] *Definitions* - [[popup Highlight definition text,Highlight definition terms]] - [[popup Use <DL> markup for defn. paras]] *Headings* - [[popup Largest allowed <Hn> tag,Hn markup to be used]] - [[popup Headings colour]] - [[popup Preserve underlining of headings]] *Emphasis* - [[popup Add emphasis and bold markup,Markup emphasised text]] - [[popup Use <EM> and <STRONG> markup]] *Paragraphs* - [[popup Use <P> markup for paragraphs]] - [[popup Preserve new paragraph offset, Preserve any first line indentation]] See the discussions on detecting [[goto paragraph detection, paragraphs]], [[goto definition detection, definitions]], [[goto Headings and section titles, headings]], and [[goto emphasis detection, emphasis characters]]. Style sheet URL ............... $_$_HELP_TOPIC_ID ID_STYLESHEET _Menu location: Conversion options -> Output policies -> HTML styling_ Style sheets are a feature recently added to HTML. They are supported by Internet Explorer and Netscape 4.0 and above. They may not be supported by earlier browsers. Style sheets allow you to specify the colours and fonts that you want added to your paragraphs, headers etc in your HTML. Normally you store all this detail in a cascading style sheet (.css) file and use a line of HTML in your <HEAD> section. In this way a uniform style can be added to all pages on your site and easily changed. This policy allows you to specify the URL of any style sheet you want to use. AscToHTM will then add the requisite HTML to the <HEAD> portion of your document. Highlight definition text ......................... $_$_HELP_TOPIC_ID ID_HIGHLIGHTDEFNS _Menu location: Conversion options -> Output policies -> HTML styling_ This policy specifies whether or not the definition term in a definition should be highlighted in bold. See [[goto definition detection, definitions]] for more details Use <DL> markup for defn. paras ............................... $_$_HELP_TOPIC_ID ID_USEDL _Menu location: Conversion options -> Output policies -> HTML styling_ This policy specifies whether or not definition paragraphs should be marked up using <DL>...</DL> markup. <DL> markup puts the definition term on one line, and the definition text as an indented paragraph immediately below. See [[goto definition detection, definitions]] for more details Largest allowed <Hn> tag ........................ $_$_HELP_TOPIC_ID ID_HNMARKUP _Menu location: Conversion options -> Output policies -> HTML styling_ This policy (together with [[popup Smallest allowed <Hn> tag]]) specify the range of values that may be used in <Hn> markup on headings. In HTML, <H1> gives the largest heading, <H2>... give smaller headings, thus the “largest” <Hn> value will actually be smaller than the “smallest” value. These policies only apply to numbered headings that are detected. See also [[popup Smallest allowed <Hn> tag]]. Smallest allowed <Hn> tag ......................... _Menu location: Conversion options -> Output policies -> HTML styling_ See discussion in [[popup Largest allowed <Hn> tag]] Headings colour ............... $_$_HELP_TOPIC_ID ID_HEADINGSCOLOUR _Menu location: Conversion options -> Output policies -> HTML styling_ This policy identifies the [[popup HTML colours,HTML COLOUR]] to be used for all headings in the document. Preserve underlining of headings ................................ $_$_HELP_TOPIC_ID ID_HEADINGS_PRESERVE _Menu location: Conversion options -> Output policies -> HTML styling_ This policy specifies that where headings are underlined in the source text then the heading should be underlined in the generated HTML. Sometimes headings are underlined for emphasis in plain text, but once recognised as a heading you don't want the underlining itself preserved. Allow automatic centring ........................ _Menu location: Conversion options -> Output policies -> HTML styling_ When enabled the software will attempt [[goto centred text detection]]. _This appears on-screen as "Enable automatic centring"_ Automatic centring tolerance ............................ _Menu location: Conversion options -> Output policies -> HTML styling_ When [[goto centred text detection]] is enabled, this specifies how much off-centre text can be and still be considered as centred text. Text is compared to the [[goto page width]], taking into account any left hand indentation. If you make this value larger, more text will be considered to be centred and will be centred in the output, although only blocks of text that are wholly centred (all lines fall within the specified tolerance) will be regarded as centred text in the output. Ignore multiple blank lines ........................... _Menu location: Conversion options -> Output policies -> HTML styling_ When enabled multiple blank lines in the input will not be converted to multiple blank lines in the output. This can be desirable when converting a document that has been "paged" and so had extra blank lines added to space out the sections, and this spacing makes no sense and is unwanted in the HTML. If not selected, AscToHTM will add extra <BR> markup for each additional blank line. Add emphasis and bold markup ............................ $_$_HELP_TOPIC_ID ID_EMPHASIS_POL _Menu location: Conversion options -> Output policies -> HTML styling_ This policy determines whether or not AscToHTM should attempt to convert any potential emphasis characters encountered. _This appears on-screen as "Markup emphasis characters"_ See the [[goto emphasis detection, emphasis section]] for more details. Use <EM> and <STRONG> markup ............................ _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> HTML styling_ Specifies whether <EM> and <STRONG> markup should be used in preference to <I> and <B> when placing text in italic or bold markup. Strictly speaking <EM> and <STRONG> should be used as these are "logical" as opposed to "physical" markup. The preference has become a near religious decision which I avoid, by giving you this policy so you can choose (if you really care) Use <P> markup for paragraphs ............................. $_$_HELP_TOPIC_ID ID_USE_P_MARKUP _Menu location: Conversion options -> Output policies -> HTML styling_ This policy determines whether <P> or <BR> markup should be used for paragraphs. <P> markup is the default, and is normally interpreted in browsers as occupying more white space. If you don’t want so much white space used, disable this policy. Preserve new paragraph offset ............................. _Menu location: Conversion options -> Output policies -> HTML styling_ When enabled, any first-line indentation detected for paragraphs will be preserved. Often paragraphs indent the first line by a few spaces. Where the software detects this you have the choice as to whether an indentation should be preserved in the output. _This appears on-screen as "Preserve any first line indentation"_ $_$_HELP_CHAPTER 3,"Table generation policies" Table generation policies ------------------------- $_$_HELP_TOPIC_ID HIDD_TABLE _Menu location: Conversion options -> Output policies -> Tables_ AscToHTM can attempt to generate HTML tables automatically wherever a section of pre-formatted text is encountered. This feature can be disabled in those cases where the “tables” generated are unappealing. In such cases the pre-formatted text will be marked up using <PRE>...</PRE> tags instead. See also the discussion about [[goto pre-formatted text]] This page allows you to change the following:- *Default <TABLE> tag attributes* If HTML TABLE generation is attempted, these attributes are used as defaults for the tables that are created. These defaults can be overridden on a table-by-table basis by using the various pre-processor TABLE command in the source document. - [[popup Default TABLE header rows,Number of header rows]] - [[popup Default TABLE border size,Table border size]] - [[popup Default TABLE width,Table width]] - [[popup Default TABLE cell padding,CELLPADDING]] - [[popup Default TABLE cell spacing,CELLSPACING]] *Colours* - [[popup Default TABLE colour,Table colour]] - [[popup Default TABLE border colour,Border colour]] - [[popup Colour data rows,Colour odd and even rows differently]] - [[popup Default TABLE odd row colour,Odd row colour]] - [[popup Default TABLE even row colour,Even row colour]] *Alignment* - [[popup Default TABLE alignment,Table alignment]] - [[popup Default TABLE cell alignment]] *Other Conversion options* - [[popup Convert TABLE X-refs to links,Convert cross-references inside tables to hyperlinks]] - [[popup Keep original table lines in output,Keep row separator lines in the output]] - [[popup Default table html attributes]] - [[popup Default table html cell attributes]] Default TABLE header rows ......................... $_$_HELP_TOPIC_ID ID_TAB_HEADER _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies how many lines should be regarded as the header of a table. AscToHTM can attempt to detect this, and it may not be the case that all tables in the same file have the same header size. In such cases leave this value as 0. _This appears on-screen as "Number of header rows"_ Default TABLE border size ......................... $_$_HELP_TOPIC_ID ID_TAB_BORDER _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies the value to be given to the BORDER attribute of the <TABLE> tag. This attribute determines the size of the table borders. If set to 0, no border will be added to the table. Default TABLE border colour ........................... _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies the value to be used in the BORDERCOLOR attribute of any created <TABLE> tags. Not all browsers support these attributes. The colours should be specified as valid HTML colours, or selected from the colour palette using the browse buttons. See the discussion about [[goto HTML colours]] Default TABLE colour .................... _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies the value to be used in the BGCOLOR attribute of any created <TABLE> tags. Not all browsers support these attributes. The colours should be specified as valid HTML colours, or selected from the colour palette using the browse buttons. See the discussion about [[goto HTML colours]] Colour data rows ................ $_$_HELP_TOPIC_ID ID_TAB_COLOUR_ROWS _Menu location: Conversion options -> Output policies -> Tables_ These policies allow you to specify whether or not you want odd and even data rows of the table coloured differently. The table header will be coloured either according to the document's colour, or - if you've specified it - the table colour. See the discussion about [[goto HTML colours]] Default TABLE even row colour ............................. _Menu location: Conversion options -> Output policies -> Tables_ When [[popup Colour data rows]] is enabled, this specifies the colour to be used as background on even numbered data rows in the table. See also [[popup Default TABLE odd row colour]] Default TABLE odd row colour ............................ _Menu location: Conversion options -> Output policies -> Tables_ When [[popup Colour data rows]] is enabled, this specifies the colour to be used as background on odd numbered data rows in the table. See also [[popup Default TABLE even row colour]] Default TABLE width ................... $_$_HELP_TOPIC_ID ID_TABLE_WIDTH _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies the value to be used for the WIDTH attribute of each generated <TABLE> tab. Table widths are specified in pixels, or as a percentage of the total screen width, thus “350” and “75%” would both be valid values. Note, this value will be used for *all* tables generated in the document, so it is only suitable for use when you have a number of similar width tables. Default TABLE cell padding .......................... $_$_HELP_TOPIC_ID ID_TAB_CELL _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies the value to be used in the CELLPADDING attribute of any created <TABLE> tags. The CELLPADDING attribute specifies the amount of white space to be added to each table cell as padding round the cell’s contents. Default TABLE cell spacing .......................... $_$_HELP_TOPIC_ID ID_TAB_CELL _Menu location: Conversion options -> Output policies -> Tables_ This policy specifies the value to be used in the CELLSPACING attribute of any created <TABLE> tags. The CELLSPACING attribute specifies the amount of white space to be added between cells. Default TABLE alignment ....................... _Menu location: Conversion options -> Output policies -> Tables_ By default the software will attempt to automatically calculate the alignment of a table within a document, and in most cases will simply left align the table, possibly with a margin where one is detected. This policy can be used to overrule that process and set the alignment for all tables in the document (e.g. to centre all tables). To exert more control over particular columns in particular tables you should consider using a [[goto Using Table Definition Files (TDF),Table definition file]] Default TABLE cell alignment ............................ _Menu location: Conversion options -> Output policies -> Tables_ By default the software will attempt to automatically calculate the alignment of data inside each cell of a table. This will look at the placement of the data, and the type of data (e.g. numerical data is right justified). This policy can be used to overrule that process and force a particular alignment. When set it will apply to *all* cells in all detected tables. To exert more control over particular columns in particular tables you should consider using a [[goto Using Table Definition Files (TDF),Table definition file]] Convert TABLE X-refs to links ............................. $_$_HELP_TOPIC_ID ID_CONVERXREFS _Menu location: Conversion options -> Output policies -> Tables_ This policy determines whether or not numbers in a table should be regarded as references to numbered sections in the document. If they are, then the number will be converted to a hyperlink to the numbered section. If they are not, the number will be left unconverted. _This appears on-screen as "Convert cross-references inside a table"_ See also [[popup Cross-refs at level,Convert cross-references to other sections]] Keep original table lines in output ................................... _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Tables_ The converter can look for horizontal lines in the input text of a table as signs of row separators. Normally when these are detected, the program will use them to decide how to allocate the input text into rows, but will then discard the lines themselves from the output. Sometimes, however such lines are useful, and on occasion these lines may be being misinterpreted. either way, this policy allows you to specify that any horizontal lines found in the input should be replicated in the output, and not discarded. This appears on-screen as "Keep row separator lines in the output" Default table html attributes ............................. _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Tables_ This option specifies any HTML attributes that should be added to each <TABLE> tag that is created. This can be used to customize the table's behaviour and appearance. For example you can add the necessary JavaScript attributes to add the ability to sort the table. See also [[popup Default table html cell attributes]] Default table html cell attributes .................................. _(New in version 5.0)_ _Menu location: Conversion options -> Output policies -> Tables_ This option specifies any HTML attributes that should be added to each cell in the tables that are create, that is, to the <TH> and <TD> tags that are created. This can be used to customize the table's behaviour and appearance. For example you can add the necessary JavaScript attributes to add the ability to sort the table. See also [[popup Default table html attributes]] $_$_HELP_CHAPTER 3,"Configuration file policies" Configuration file policies --------------------------- _Menu Location: Conversion options -> Configuration files_ These policies identify the locations of external configuration files used by AscToHTM. - [[popup Fragments file, HTML fragments file]] - [[popup Link Dictionary file]] - [[popup Definitions file,Table Definitions file]] - [[popup Text command file]] Fragments file .............. $_$_HELP_TOPIC_ID ID_FRAGMENTS_FILE _Menu location: Conversion options -> Configuration files -> HTML fragments file_ The [[goto Using HTML fragments,HTML fragments]] feature allows you to customise the HTML generated by the software by defining pieces of HTML that the software can copy at various points into the output HTML. These “fragments” can be placed in-line within the source file, but are usually best placed in a separate file, in which case this policy is used to identify the location of this “HTML fragments file”. Link Dictionary File .................... $_$_HELP_TOPIC_ID HIDD_LINK_DICTIONARY _Menu location: Conversion options -> Configuration files -> Link Dictionary_ The [[goto Using link dictionary files, Link Dictionary feature]] allows you to define text that should be converted into hyperlinks during the conversion. This policy specifies the name of a dictionary file to be used. Once a files has been selected, the "Edit" button on this dialog will take you to the [[goto Link Dictionary Edit Dialog]]. Definitions file ................ _Menu location: Conversion options -> Configuration files -> Table Definitions File_ The [[goto Using Table Definition Files (TDF),Table Definition File (TDF) feature]] allows you to define certain types of table and how they should be processed during the conversion. This policy identifies the external configuration file that holds all your Table definition details and TDF commands. Text command file ................. _Menu location: Conversion options -> Configuration files -> Text Commands File_ The [[goto Using Text Command Files, Text Commands feature]] allows you to define simple text manipulations that can be performed on the text on input into the conversion. This policy identifies the external configuration file that holds all your Text Command definitions. $_$_HELP_CHAPTER 2,"Other policies" $_$_HELP_SUBJECT "Introduction" Other policies ============== In addition to the policies set via the "Conversion Options" menu, there are policies that can set which correspond to options elsewhere in the user interface, and a few that can't be accessed via the user interface, but which can be edited manually into any policy file that is used. - [[goto Settings Policies, Policies set via the Settings Menu]] - [[goto Policies set elsewhere in the user interface]][[br]] - [[goto Policies that need to be added manually]] $_$_HELP_CHAPTER 3,"Settings policies" Settings policies ----------------- _Menu location: Settings -> Diagnostics_ These policies are equivalent to options accessible view the [[goto Settings menu]] - [[popup Error reporting level]] - [[popup Suppress INFO messages]] - [[popup Suppress program ERROR messages]] - [[popup Suppress TAG ERROR messages]] - [[popup Suppress URL messages]] - [[popup Suppress WARNING messages]] Display Messages ................ _Menu location: Settings -> Diagnostics_ Specifies that all display and informational messages should be suppressed. If selected, you will get no messages displayed at all, although these can still be directed to a .log file (e.g. by using the [[popup command line qualifiers: /LOG,/LOG]] command qualifier) This policy can't be set via the user interface, but can be edited into a policy file should you wish. This policy is equivalent to the [[popup command line qualifiers: /SILENT,/SILENT]] command qualifier. Error reporting level ..................... _Menu location: Settings -> Diagnostics_ Specifies the level of error reporting you want during the conversion. The program can generate a variety of messages of varying severity to inform you of the decisions it's made. These messages can be useful in explaining why a conversion has gone wrong, but are less interesting at other times. Whilst all of these messages are copied into any diagnostic .lis files created (see [[GOTO "Generate diagnostics files"]]) regardless of severity, you can use this policy to choose the level of reporting you want to see on your screen. The value is nominally in the range 1-10 with a value of 1 showing few messages and a value of 10 showing almost all messages. The default value is 5. Suppress INFO messages ...................... _Menu location: Settings -> Diagnostics_ Suppresses all "INFO" messages from the display. These are messages deemed to be "informational" The severity (reporting level) will match how important/useful the seriousness of the warning. Together with the [[GOTO "Error Reporting Level"]] policy, similar suppression policies and the [[popup command line qualifiers: /SILENT,/SILENT]] command qualifier, you have a fair degree of control of the level of reporting made visible during conversion. Suppress TAG ERROR messages ........................... _Menu location: Settings -> Diagnostics_ Suppresses all "TAG ERROR" messages from the display. These are messages reporting failure to implement inline tags and directives (if any) placed in your source text. However, you should really fix up all your tag errors if possible. Together with the [[GOTO "Error Reporting Level"]] policy, similar suppression policies and the [[popup command line qualifiers: /SILENT,/SILENT]] command qualifier, you have a fair degree of control of the level of reporting made visible during conversion. Suppress URL messages ..................... _Menu location: Settings -> Diagnostics_ Suppresses all "URL" messages from the display. These are messages that report the detection of URLs in the document being converted. Together with the [[GOTO "Error Reporting Level"]] policy, similar suppression policies and the [[popup command line qualifiers: /SILENT,/SILENT]] command qualifier, you have a fair degree of control of the level of reporting made visible during conversion. Suppress WARNING messages ......................... _Menu location: Settings -> Diagnostics_ Suppresses all "WARNING" messages from the display. These are messages usually reporting that the program has possibly done something you may not have wanted it to, or not done something you might have wanted it to. For example if lines that could contain emphasis or headings are rejected, a warning will be issued. The severity (reporting level) will match the seriousness of the warning. Together with the [[GOTO "Error Reporting Level"]] policy, similar suppression policies and the [[popup command line qualifiers: /SILENT,/SILENT]] command qualifier, you have a fair degree of control of the level of reporting made visible during conversion. Suppress PROGRAM ERROR messages ............................... _Menu location: Settings -> Diagnostics_ Suppresses all "PROGRAM ERROR" messages from the display. These are messages indicating that the program itself thinks it's done something wrong. There's not much you can do about such errors, other than ignore them, or report them to the author so he can fix the software. Together with the [[GOTO "Error Reporting Level"]] policy, similar suppression policies and the [[popup command line qualifiers: /SILENT,/SILENT]] command qualifier, you have a fair degree of control of the level of reporting made visible during conversion. $_$_HELP_CHAPTER 3,"Policies set elsewhere in the user interface" Policies set elsewhere in the user interface -------------------------------------------- Some policies are saved into the policy fie, but are not accessed via the "Conversion Options" menu These include:- - [[popup Default TABLE delimiter character]] Default TABLE delimiter character ................................. _(New in version 5.0)_ This policy is used to save the value of the [[goto delimiter character]] selected on the main screen whenever the [[goto input file type]] has been set to "other-delimited table", indicating that the input file is to be treated as a single, character-delimited, data table. $_$_HELP_CHAPTER 3,"Policies that need to be added manually" Policies that need to be added manually --------------------------------------- Some policies cannot currently be set via the User Interface, instead these policies can only be added by opening a policy file in a text editor and adding the options by hand. See [[goto Changing policies by editing a Policy file]] Such policies include: *Tables* - [[popup Default TABLE caption]] - [[popup Default TABLE header cols]] *Code samples* - [[popup Use <CODE>..</CODE> markup]] *Contents lists* - [[popup Contents style code]] *Headings* - [[popup Expect Second Word Headings]] - [[popup First Section Number]] Default TABLE caption ..................... Specifies the caption to be applied to generated tables. However, since this will be applied to all generated tables, this is less useful that placing individual [[popup Pre-processor command: TABLE_CAPTION, TABLE_CAPTION]] directives in your source text. Default TABLE header cols ......................... This tells AscToHTM how many columns in each table should be highlighted as "header" columns using <B> ... </B> markup inside the table cells. Normally this is 0. Use <CODE>..</CODE> markup .......................... This policy specifies that where a code fragment has been detected or marked up, what sort of HTML markup should be used. HTML provides a special <CODE> .. </CODE> markup that is suited to variables being quoted in text, but is not well suited for marking up several lines. In particular, you have to add non-breaking spaces and <BR> markup if you wish to correctly lay out several lines. This makes the resultant HTML harder to read and much larger. For this reason, AscToHTM defaults to <PRE> .. </PRE> markup for code fragments. The only reason for reversing this might be if you needed the <CODE> tag for a particular style sheet to take effect. Contents style code ................... Specifies a "style" to be applied to the contents list. There aren't too many options at present. Possible values are $_$_BEGIN_TABLE 0 AscToHTM "Classic". Contents line is bolded 1 As above, but not bolded. $_$_END_TABLE Expect Second Word Headings ........................... This is a reserved policy that may be removed at some time in the future. when enabled, this policy indicates that the heading may be a numbered heading, but that the number is in the second (or perhaps third) word in the heading. For example in the case of the following heading $_$_BEGIN_PRE Section 2.3.4 - This is the next section $_$_END_PRE the section number "2.3.4" isn't at the start of the line, but instead follows the word "Section". This can still be counted as a numbered heading, with result that it can be checked to see that it is in sequence etc, etc. First Section Number .................... Indicates the chapter number of the first numbered section in a file containing numbered sections (see [[GOTO "Expect numbered headings"]]). Normally this starts at 0 or 1, but if it starts higher, then the program will reject headers as being out of sequence, and fail to detect to presence or absence of contents lists correctly. Only for the advanced/foolhardy user. $_$_BEGIN_IGNORE ! ! deprecated /deleted policy descriptions ! ! Scope COLOUR tags globally ! .......................... ! Specifies whether the [[HYPERLINK TAGGING, COLOUR]] tags should scope globally or locally. ! "Global" scope means the colour won't change until another [[HYPERLINK TAGGING, COLOUR]] tag ! is encountered. "Local" means the colour will only scope as far as the next ! font change. ! $_$_END_IGNORE $_$_HELP_CHAPTER 1,"Using the pre-processor" $_$_HELP_SUBJECT "Introduction to the pre-processor" Using the pre-processor *********************** $_$_HELP_TOPIC_ID ID_PREPROCESSOR The pre-processor allows authors to add special lines to the source document to customise the conversion. This is usually used where someone intends regularly generating HTML from a master text document. The Pre-processor is described more fully in the separate document the [Tag Manual]. The pre-processor works by giving the software hints and instructions on how to process the text. During the analysis process the software reads the source files line-by-line. The pre-processor recognises special keywords in two ways - [[goto pre-processor directives,Directives]] are placed on a line by themselves. They usually instruct the software to do something, but don't usually appear directly in the output themselves. Often directives occur in pairs, marking up a section of text between them as having a special significance (e.g. to say it's a comma-delimited table) - [[goto pre-processor in-line tags,In-line tags]] can be placed anywhere in a line of input text. Usually they are substituted by some special text. For example a [[goto Pre-processor command: GOTO, GOTO]] tag becomes a hyperlink to a section elsewhere, while a [[goto Pre-processor command: BR, BR]] tag forces a line break at that point. In both cases the tag or directive cannot be split over multiple lines, that is directives must be on a line by themselves, and in-line tags must be wholly contained on a single line. $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION MAKINGRTF Pre-processor commands come in several types:- $_$_BEGIN_DELIMITED_TABLE [[goto Document commands]] Commands that change the document title and keywords etc [[goto Section delimiters]] Commands that delimit sections in the source text [[goto Tagged table commands]] Commands that allow you to specify a table structure cell-by-cell [[goto Table modifier commands]] Commands that delimit and control table generation [[goto Other commands]] Other miscellaneous commands $_$_END_TABLE $_$_SECTION ALL Pre-processor Directives ------------------------ "Directives" consist of a single line in the source file beginning with the string "$_$_" followed by a recognised keyword and any additional "attributes" that the directive supports. NOTE: The "$_$_" must be at the start of the line, otherwise it will be ignored. Often directives come in pairs, for example $_$_BEGIN_PRE $_$_BEGIN_COMMA_DELIMITED_TABLE Date, column 2, column 3, value in column 4, column 5 ----,-------,--------,-------,------ Monday, 2, 3,4,5.5 Tuesday, 2, 3.3, 4.4, 5.5 ... $_$_END_COMMA_DELIMITED_TABLE $_$_END_PRE allows the comma-separated data to be transformed into the following table $_$_BEGIN_COMMA_DELIMITED_TABLE Date, column 2, column 3, value in column 4, column 5 ----,-------,--------,-------,------ Monday, 2, 3,4,5.5 Tuesday, 2, 3.3, 4.4, 5.5 $_$_END_COMMA_DELIMITED_TABLE Pre-processor In-line tags -------------------------- In-line tags, as the name implies, can occur anywhere in the source lines. They are enclosed between the special strings "[[OT]]" and "[[CT]]". Between these strings the tag consists of a keyword and then any attributes that tag supports. Useful in-line tags include - [[goto Pre-processor command: GOTO, GOTO]] - [[goto Pre-processor command: BR, BR]] - [[goto Pre-processor command: FRACTION, FRACTION]] - [[goto Pre-processor command: SUPER and SUB, SUPER and SUB]] $_$_HELP_CHAPTER 2,"Document commands" Document commands ================= $_$_HELP_TOPIC_ID ID_PRE_DOCUMENT These commands are used to control tags placed in the <HEAD..</HEAD> section of the created HTML page(s). Not yet implemented in this release. $_$_BEGIN_DELIMITED_TABLE [[popup Pre-processor command: DESCRIPTION, DESCRIPTION]] Add a description in the document <HEAD> [[popup Pre-processor command: KEYWORDS, KEYWORDS]] Add keywords to the document <HEAD> [[popup Pre-processor command: TITLE, TITLE]] Add a Title to the HTML pages [[popup Pre-processor command: STYLE_SHEET, STYLE_SHEET]] Add a style sheet to the HTML pages $_$_END_DELIMITED_TABLE Pre-processor command: DESCRIPTION ---------------------------------- $_$_HELP_TOPIC_ID ID_PRE_DESCRIPTION You can specify a description of your page to be added as a <META> tag to the <HEAD> portion of your page by adding a line of the form $_$_BEGIN_PRE $_$_DESCRIPTION <rest of line is used as a description> $_$_END_PRE This takes precedence over any description added via a policy file, or on the Added HTML options page. See the discussion in the [[goto Document Description]] section Pre-processor command: KEYWORDS ------------------------------- $_$_HELP_TOPIC_ID ID_PRE_KEYWORDS You can specify keywords that describe the contents of your page to be added as a <META> tag to the <HEAD> portion of your page by adding a line of the form $_$_BEGIN_PRE $_$_KEYWORDS <rest of line is used as a list of keywords> $_$_END_PRE This takes precedence over any keywords added via a policy file, or on the Added HTML options page. See the discussion in the [[goto Document Keywords]] section Pre-processor command: TITLE ---------------------------- $_$_HELP_TOPIC_ID ID_PRE_TITLE You can specify the TITLE to be added to your HTML page (in the <HEAD> section, by adding a line of the form $_$_BEGIN_PRE $_$_TITLE <rest of line is used as a title> $_$_END_PRE This title takes precedence over any title added via a policy file, or on the Added HTML options page Pre-processor command: STYLE_SHEET ---------------------------------- $_$_HELP_TOPIC_ID ID_PRE_STYLESHEET You can specify a style sheet file to be added as a <LINK> tag to the <HEAD> portion of your page by adding a line of the form $_$_BEGIN_PRE $_$_STYLE_SHEET <URL of your .css file> $_$_END_PRE This takes precedence over any style sheet added via a policy file, or on the [[goto CSS policies]] page. $_$_HELP_CHAPTER 2,"Section delimiters" Section delimiters ================== $_$_HELP_TOPIC_ID ID_PRE_SECTION These commands mark the start and end of various sections in your document $_$_BEGIN_DELIMITED_TABLE [[popup Pre-processor command: ALLOW and DISALLOW, ALLOW and DISALLOW]] Enable and disable certain types of detection. [[popup Pre-processor command: ASCII, ASCII]] Mark a section of text for utility A2HDETAG. [[popup Pre-processor command: CONTENTS, CONTENTS]] Mark a section as the contents list. [[popup Pre-processor command: CODE, CODE]] Mark a section as C-like code sample [[popup Pre-processor command: DIAGRAM, DIAGRAM]] Mark a section as a diagram or ASCII Art [[popup Pre-processor command: HTML, HTML]] Mark a section of HTML to be copied into the output [[popup Pre-processor command: HTML_LINE,HTML_LINE]] Mark a line of HTML to be copied into the output [[popup Pre-processor command: IGNORE, IGNORE]] Ignore a section of the document [[popup Pre-processor command: PRE, PRE]] Mark a section as pre-formatted text. [[popup Pre-processor command: TABLE, TABLE]] Mark a section as a table. [[popup Pre-processor command: COMMA_DELIMITED_TABLE,COMMA_DELIMITED_TABLE]] Mark a section as comma-delimited data table. [[popup Pre-processor command: DELIMITED_TABLE,DELIMITED_TABLE]] Mark a section as a tab-delimited data table. [[popup Pre-processor command: SECTION, SECTION]] Mark the start of a user-specified section. $_$_END_TABLE Pre-processor command: ALLOW and DISALLOW ----------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_ALLOW_AND_DISALLOW _(New in version 5.0)_ AscToHTM will automatically try to detect various typographical features. You can turn this behaviour on and off in different sections by using the ALLOW and DISALLOW. This can be used, for example, to prevent a numbered list being wrongly detected as a numbered heading and vice versa. The syntax for both commands is the same, namely $_$_BEGIN_PRE ALLOW/DISALLOW <comma-separated list of keywords> $_$_END_PRE Where the recognised keywords are as follows $_$_BEGIN_TABLE Headings This enables/disable the search for lines that could be treated as headings. Lists This enables/disables the search for lines that could be regarded as list items (either unordered bullets, or alphabetic or numeric list points) All Set (enable) all of the above Reset Reset (disable) all of the above $_$_END_TABLE In each case the tag will simply add or subtract from the current list of allowable features. To aid control, two special keywords "all" and "reset" are available for inclusion in the list. "Reset" will disable all options, thus $_$_BEGIN_PRE $_$_ALLOW reset, Headings $_$_END_PRE will have the effect of disabling everything (the "reset") and then adding "Headings" to the allowed list. In this respect "ALLOW all" and "DISALLOW reset" are identical commands. Below is an example in which the DISALLOW tag is used to prevent numbered lines being regarded as lists or headings. The ALLOW tag at the end switched back to default behaviour,, so if there are any lists of numbered headings elsewhere in the document they will still be detected. $_$_BEGIN_PRE $_$_DISALLOW headings ... 1. Whatever this line is, it isn't a heading ... $_$_DISALLOW headings, lists ... 2. Whatever this line is, it isn't a heading *or* a list item ... $_$_ALLOW reset $_$_END_PRE Pre-processor command: ASCII ---------------------------- _(New in version 5.0)_ The separate utility [[goto new utility a2hdetag,A2HDETAG]] is available to create a plain ASCII file, by removing all pre-processor tags from your source file. In this was a source file designed for conversion to HTML by AscToHTM can be "cleaned up" and posted as plain text elsewhere. To support this, the BEGIN_ASCII and END_ASCII tags can be used to delimit a section of text that will only appear in the version created by A2HDETAG. This allows you to add comments to the "plain text" version, that won't appear in the HTML conversion. Use these commands as follows $_$_BEGIN_PRE $_$_BEGIN_ASCII You are reading this text in a "cleaned up" version of the source file. This text won't get copied across when this file is converted to either RTF or HTML $_$_END_ASCII $_$_END_PRE Pre-processor command: CONTENTS ------------------------------- $_$_HELP_TOPIC_ID ID_PRE_CONTENTS You can mark up a section of your document as a contents list. To do this use matching BEGIN_CONTENTS and END_CONTENTS command as follows: $_$_BEGIN_PRE $_$_BEGIN_CONTENTS ... $_$_END_CONTENTS $_$_END_PRE AscToHTM will then attempt to treat the enclosed text as a contents list. See comments on [[goto contents list policies]] Pre-processor command: CODE --------------------------- $_$_HELP_TOPIC_ID ID_PRE_CODE You can mark up a section of your document as being a piece of sample C-like code. To do this use matching BEGIN_CODE and END_CODE command as follows: $_$_BEGIN_PRE $_$_BEGIN_CODE ... $_$_END_CODE $_$_END_PRE AscToHTM will then mark up the enclosed text in fixed width fonts. See comments on [[goto pre-formatted text]] Pre-processor command: COMMA_DELIMITED_TABLE -------------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_COMMA_TABLE _(New in version 5.0)_ These commands delimit a table of comma-delimited data Syntax: $_$_BEGIN_PRE $_$_BEGIN_COMMA_DELIMITED_TABLE ... (lines of comma-delimited data) ... $_$_END_COMMA_DELIMITED_TABLE $_$_END_PRE The BEGIN_COMMA_DELIMITED_TABLE ... END_COMMA_DELIMITED_TABLE directives can be used to delimit a series of comma-delimited data values that should be interpreted as a table (e.g. data originally exported from a spreadsheet such as Excel) See comments in [[goto Pre-processor command: TABLE]] Pre-processor command: DEFINE_HTML_FRAGMENT ------------------------------------------- The DEFINE_HTML_FRAGMENT...END_BLOCK delimits a [[goto Using HTML Fragments,HTML fragment]], that is a fragment of HTML that can be inserted into the output at certain key points. It is normally recommended that all fragments defined in this manner are placed in an external HTML Fragments file, and that the [[goto Fragments file]] policy is used to locate this file, so that it is loaded at runtime, but you can, if you wish, embed fragment definitions in your source. Syntax: $_$_BEGIN_PRE $_$_BEGIN_HTML_FRAGMENT <fragment_name>,<scope> ... Fragment of HTML which may include "fragment" tags ... $_$_END_BLOCK $_$_END_PRE and $_$_RESET_HTML_FRAGMENT <fragment_name> $_$_BEGIN_IGNORE ! $_$_RESET_HTML_FRAGMENT <fragment_name>,<scope> $_$_END_IGNORE where $_$_BEGIN_TABLE <fragment_name> The name used to refer to this fragment. fragment names may be reused, in which case the fragments will be "scoped" so that required fragment can be resolved. $_$_END_TABLE $_$_BEGIN_IGNORE ! <scope> The "scope" of this fragment. Same meaning as that ! explained in [[POPUP Pre-processor command: DEFINE_BLOCK, DEFINE_BLOCK]]. $_$_END_IGNORE The [[goto Pre-processor command: RESET_HTML_FRAGMENT,RESET_HTML_FRAGMENT]] tag may be used to effectively cancel a previously defined fragment. If a reserved fragment name is reset this will have the effect of suppressing the generation of that HTML. See also [[GOTO "Using HTML fragments"]] Pre-processor command: DELIMITED_TABLE -------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_DELIMITED_TABLE These directives delimit a table of delimited data Syntax: $_$_BEGIN_PRE $_$_BEGIN_DELIMITED_TABLE [<delimiter>] ... (lines of delimited data) ... $_$_END_DELIMITED_TABLE $_$_END_PRE where <delimiter> The delimiter character to use. If omitted the default is tab-delimited. The delimiter can be any character except a comma. For comma-delimited tables use the [[goto Pre-processor command: COMMA_DELIMITED_TABLE,COMMA_DELIMITED_TABLE]] Command instead The BEGIN_DELIMITED_TABLE ... END_DELIMITED_TABLE directives can be used to delimit a series of delimited data values that should be interpreted as a table (e.g. data originally exported from a spreadsheet such as Excel) See comments in [[goto Pre-processor command: TABLE]] Pre-processor command: DIAGRAM ------------------------------ $_$_HELP_TOPIC_ID ID_PRE_DIAGRAM You can mark up a section of your document as being a diagram or a piece of ASCII art. To do this use matching BEGIN_DIAGRAM and END_DIAGRAM commands as follows: $_$_BEGIN_PRE $_$_BEGIN_DIAGRAM ... $_$_END_DIAGRAM $_$_END_PRE AscToHTM will then mark up the enclosed text in fixed width fonts. See comments on [[goto pre-formatted text]] Pre-processor command: HTML --------------------------- $_$_HELP_TOPIC_ID ID_PRE_HTML You can mark up a section of your document as being pure HTML. To do this use matching BEGIN_HTML and END_HTML commands as follows: $_$_BEGIN_PRE $_$_BEGIN_HTML ... HTML commands ... $_$_END_HTML $_$_END_PRE AscToHTM will then treat the enclosed text as pure HTML. This allows you to add images, Javascript and tables to your documents. See also [[goto Pre-processor command: HTML_LINE]] Pre-processor command: HTML_LINE -------------------------------- $_$_HELP_TOPIC_ID ID_PRE_HTML_LINE This command marks a single line in your document as being pure HTML which doesn’t need converting. This achieves the same effect as the HTML section commands, but in a more compact form. You can use this to insert images, or to manually centre some text as follows:- $_$_BEGIN_PRE $_$_HTML_LINE <centre> . . section of document that needs converting, and that . want centred. . $_$_HTML </centre> $_$_END_PRE See also the [[goto Pre-processor command: HTML]] commands Pre-processor command: IGNORE ----------------------------- $_$_HELP_TOPIC_ID ID_PRE_IGNORE You can mark up a section in your document that you want ignored in the output. This can be used to store change history information or whatever you want. Syntax: $_$_BEGIN_PRE $_$_BEGIN_IGNORE ... (text to be ignored) ... $_$_END_IGNORE $_$_END_PRE This markup can be used to delimit a section to be wholly ignored. Any markup and tags in the ignored section will have no effect. Pre-processor command: PRE -------------------------- $_$_HELP_TOPIC_ID ID_PRE_PRE You can mark up a section of your document as being pre-formatted text. To do this use matching BEGIN_PRE and END_PRE commands as follows: $_$_BEGIN_PRE $_$_BEGIN_PRE ... $_$_END_PRE $_$_END_PRE AscToHTM will then mark up the enclosed text in fixed width fonts. See comments on [[goto pre-formatted text]] Pre-processor command: TABLE ---------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_TABLE You can mark up a section of your document as being a text table. To do this use matching BEGIN_TABLE and END_TABLE Commands as follows: $_$_BEGIN_PRE $_$_BEGIN_TABLE ... $_$_END_TABLE $_$_END_PRE AscToHTM will then analyse the enclosed text to determine the table layout and will generate a proper HTML table. *General comments on marking up tables* AscToHTM has some ability to auto-detect tables (see comments on [[goto pre-formatted text]]), but this can be error prone. Marking up tables removes a lot of the ambiguity and so can give better results* For tables of delimited data (as opposed to plain text tables) you should use the [[goto Pre-processor command: DELIMITED_TABLE,DELIMITED_TABLE]] and [[goto Pre-processor command: COMMA_DELIMITED_TABLE, COMMA_DELIMITED_TABLE]] commands. Note in each case the presence of these directives overrides any value set in the [[goto Attempt table generation]] policy, as that only refers to the auto-detection of tables. Placing markup in the source *forces* the text to be treated as tables. Within each marked-up table other pre-processor commands may be used to customise the table as follows: - [[popup Pre-processor command: TABLE_HEADER_ROWS,TABLE_HEADER_ROWS]] - [[popup Pre-processor command: TABLE_MAY_BE_SPARSE,TABLE_MAY_BE_SPARSE]] - [[popup Pre-processor command: TABLE_MIN_COLUMN_SEPARATION,TABLE_MIN_COLUMN_SEPARATION]] For a full list see [[goto Table modifier commands]] Pre-processor command: RESET_HTML_FRAGMENT ------------------------------------------- This command is used to cancel the scope of a defined HTML Fragment. See the discussion in [[goto Pre-processor command: DEFINE_HTML_FRAGMENT,DEFINE_HTML_FRAGMENT]] See also [[GOTO "Using HTML fragments"]] Pre-processor command: SECTION ------------------------------ $_$_HELP_TOPIC_ID ID_PRE_NAMED_SECTION You can mark up sections of your document as being named sections. By default text belongs to a section called "all". To do so insert SECTION command at the start of each section as follows: $_$_BEGIN_PRE $_$_SECTION <name> ... $_$_END_PRE All following text will be marked as belonging to the named section until another SECTION command is encountered. AscToHTM will only copy across those sections named in the allowable sections policy, and any text in "all" sections. In this way you can generate variants of your document for different audiences (e.g. Internet and Intranet). If you want the rest of your document to be included in all conversions, insert an "all" SECTION command as follows: $_$_BEGIN_PRE $_$_SECTION all ... $_$_END_PRE $_$_HELP_CHAPTER 2,"Text definition block commands" Text definition block commands ============================== $_$_HELP_TOPIC_ID ID_PRE_SECTION These commands help with the definition and instantiation of [[goto Using text definition blocks, definition blocks]] $_$_BEGIN_DELIMITED_TABLE [[goto Pre-processor command: DEFINE_BLOCK, DEFINE_BLOCK]] Mark out a definition block [[goto Pre-processor command: DEFINE_VARIABLE, DEFINE_VARIABLE]] Define a variable value [[goto Pre-processor command: EMBED_BLOCK, EMBED_BLOCK]] Instantiate a block with regard to context [[goto Pre-processor command: INSERT_BLOCK, INSERT_BLOCK]] Instantiate a block without regard to context [[goto Pre-processor command: RESET_BLOCK, RESET_BLOCK]] Cancel a definition block [[goto Pre-processor command: SAVE/RESTORE_CONTEXT, SAVE/RESTORE_CONTEXT]] Saves/restores an output context [[goto Pre-processor command: VARIABLE, VARIABLE]] Instantiate a variable value $_$_END_TABLE Pre-processor command: DEFINE_BLOCK ----------------------------------- The DEFINE_BLOCK...END_BLOCK delimits a [[goto Using text definition blocks, Definition Block]], that is a standard block of text that can be inserted into the output at certain key points - e.g. at the end of chapters. Such blocks may be instantiated by issuing [[POPUP Pre-processor command: INSERT_BLOCK]] or [[popup Pre-processor command: EMBED_BLOCK]] commands anywhere in the document. It is normally recommended that text blocks defined in this manner are placed in an external HTML Fragments file, and that the [[goto Fragments file]] policy is used to locate this file, so that it is loaded at runtime, but you can, if you wish, embed such block definitions in your source (usually at the top of the document). Syntax: $_$_BEGIN_PRE $_$_DEFINE_BLOCK <block_name>,<scope> ... Block of lines ... $_$_END_BLOCK $_$_END_PRE where $_$_BEGIN_TABLE <block_name> The name used to refer to this block. Block names may be reused, in which case the blocks will be "scoped" so that required block can be resolved. <scope> The "scope" of this block. By default blocks are scoped to be document wide. If the same name block is defined multiple times then this will determine the range of document to which this variant of the block will apply. The Scope will be a list of keywords with one keyword taken from each of the following sets. If no keyword is found, the set's default will be used. If multiple keywords from the same set are found, and error will be reported. Range: GLOBAL (default) Application to pages: ALL_PAGES (default) ODD_PAGES_ONLY EVEN_PAGES_ONLY $_$_END_TABLE If you define two blocks of the same name with the GLOBAL scope, the first will definition will apply up until the location of the second definition. The [[goto Pre-processor command: RESET_BLOCK,RESET_BLOCK]] tag may be used to effectively cancel a previously defined text block. Pre-processor command: DEFINE_VARIABLE -------------------------------------- Defines a variable value. This value may be substituted into the document text wherever a matching [[POPUP Pre-processor command: VARIABLE, VARIABLE]] tag is used. This is particularly useful when using definition blocks, as it is a way of varying the content of the block each time it is instantiated. Syntax: $_$_BEGIN_PRE $_$_DEFINE_VARIABLE <name>,<value>,<scope> $_$_END_PRE where $_$_BEGIN_TABLE <name> The name by which the variable is to be known. <value> The (text) value for the variable <scope> The scope for the variable. $_$_END_TABLE See [[goto Using text definition blocks]] Pre-processor command: EMBED_BLOCK ---------------------------------- An EMBED_BLOCK command will cause the named DEFINE_BLOCK to be output, but without regard to the current context information, and without causing the prevailing context information (indentation, fonts) to be changed. Syntax: $_$_BEGIN_PRE $_$_EMBED_BLOCK <name> $_$_END_PRE where $_$_BEGIN_TABLE <name> Name of the block to be embedded. This will be a named DEFINE_BLOCK, resolved subject to the scoping rules. $_$_END_TABLE See also [[POPUP Pre-processor command: INSERT_BLOCK, INSERT_BLOCK]] and [[goto Using text definition blocks]] Pre-processor command: INSERT_BLOCK ----------------------------------- An INSERT_BLOCK command will cause the named [[goto Pre-processor command: DEFINE_BLOCK, DEFINE_BLOCK]] to be inserted into the document source as seen as by the program. As such the inserted block will be subject to, and able to change, the prevailing context information (indentation, fonts etc.). Syntax: $_$_BEGIN_PRE $_$_INSERT_BLOCK <name> $_$_END_PRE where $_$_BEGIN_TABLE <name> Name of the block to be inserted. This will be a named DEFINE_BLOCK, resolved subject to the scoping rules. $_$_END_TABLE See also [[POPUP Pre-processor command: EMBED_BLOCK, EMBED_BLOCK]] and [[goto Using text definition blocks]] Pre-processor command: SAVE/RESTORE_CONTEXT ------------------------------------------- The SAVE_CONTEXT and RESTORE_CONTEXT are intended for use with definition blocks. The SAVE_CONTEXT saves all the current context information (indentation, font etc) so that the slate may be wiped clean ready for the output of a new block. The RESTORE_CONTEXT command recovers the previous SAVE_CONTEXT, allowing a document to continue as it was before the defined block was inserted. It's unlikely that these tags should been to be used explicitly, but they will be used implicitly inside the implementation of the [[POPUP Pre-processor command: HTML]] section delimiters. Syntax: $_$_BEGIN_PRE $_$_SAVE_CONTEXT $_$_RESTORE_CONTEXT $_$_END_PRE Pre-processor command: RESET_BLOCK ---------------------------------- This command is used to cancel the scope of a defined text BLOCK. See the discussion in [[goto Pre-processor command: DEFINE_BLOCK,DEFINE_BLOCK]] See also [[goto Using text definition blocks, Definition blocks]] Pre-processor command: VARIABLE ------------------------------- The tab will be replaced by the value of the nearest matching [[POPUP Pre-processor command: DEFINE_VARIABLE, DEFINE_VARIABLE]] statement. Over time it is expected that some variables (section heading, page number etc.) will be automatically "defined" by the software. Syntax: $_$_BEGIN_PRE [[OT]]VARIABLE <name>[[CT]] $_$_END_PRE See [[goto Using text definition blocks]]. $_$_HELP_CHAPTER 2,"Tagged Table commands" Tagged Table commands ===================== _(New in version 5.0)_ In addition to converting plain text files, and sets of delimited data into tables, the software also supports a method of explicitly tagging the input as to how it should be placed in a table. This may seem extreme, as the point of the converters is to generate the desired markup as save work, but there are a couple of situations in which this approach can be useful. - If you are converting the source to both RTF and HTML, the same input file can be used to generate the desired output format - If the file you are converting is being generated by some software it may be easy to add the required tags, and by so doing get the required output with minimal changes and maximum accuracy. Here's a sample of a user-tagged table (with blank lines added for clarity) :- $_$_BEGIN_PRE $_$_BEGIN_USER_TABLE C,1 in $_$_COLUMN_DETAILS 1,,,L, 2 in $_$_COLUMN_DETAILS 2,,,C, 1 ins $_$_TABLE_BORDER 1 $_$_NEW_ROW HEAD $_$_NEW_CELL Substance (units) $_$_NEW_CELL Year Sampled $_$_NEW_ROW DATA $_$_NEW_CELL Alpha emitters (pCi/L) $_$_NEW_CELL 1999 $_$_NEW_ROW DATA $_$_NEW_CELL Asbestos (MFL) $_$_NEW_CELL 1993 $_$_END_TABLE $_$_END_PRE Here's how this table appears when converted into the current format $_$_BEGIN_USER_TABLE C,1 in $_$_COLUMN_DETAILS 1,,,L, 2 in $_$_COLUMN_DETAILS 2,,,C, 1 ins $_$_TABLE_BORDER 1 $_$_NEW_ROW HEAD $_$_NEW_CELL Substance (units) $_$_NEW_CELL Year Sampled $_$_NEW_ROW DATA $_$_NEW_CELL Alpha emitters (pCi/L) $_$_NEW_CELL 1999 $_$_NEW_ROW DATA $_$_NEW_CELL Asbestos (MFL) $_$_NEW_CELL 1993 $_$_END_TABLE See also - [[goto Tagged table command: BEGIN_USER_TABLE, BEGIN_USER_TABLE]] - [[goto Tagged table command: COLUMN_DETAILS, COLUMN_DETAILS]] - [[goto Tagged table command: NEW_ROW, NEW_ROW]] - [[goto Tagged table command: NEW_CELL, NEW_CELL]] - [[goto Tagged table: cell contents, Table cell contents]] Tagged table command: BEGIN_USER_TABLE -------------------------------------- To identify a section of a source file as a user table, it must be enclosed in the BEGIN_USER_TABLE ... END_TABLE commands as follows $_$_BEGIN_PRE $_$_BEGIN_USER_TABLE <arguments> ... <other commands to layout the table> ... $_$_END_TABLE $_$_END_PRE The command line can take arguments as follows $_$_BEGIN_PRE $_$_BEGIN_USER_TABLE <alignment>,<margin> $_$_END_PRE where $_$_BEGIN_TABLE <align> The alignment of the table. This can be L(eft), R(ight) or C(enter) <margin> The margin to be applied to the table. This consists of a number and a unit. Recognised units include points ("pts" or "pt"), inches ("ins" or "in") and centimetres ("cm"). In HTML generation these margins will be approximate only $_$_END_TABLE Tagged table command: COLUMN_DETAILS ------------------------------------ After the BEGIN_USER_TABLE line will appear a number of COLUMN_DETAILS lines. These are optional, but if present they give details of the characteristics of each column in the table as follows :- $_$_BEGIN_PRE $_$_COLUMN_DETAILS <col_no>,<align>,<width> $_$_END_PRE where $_$_BEGIN_TABLE <col_no> This is the column number, starting at 1 <align> This is the alignment of data in this column. If omitted this will be auto-detected, but you can choose to set it to L(eft), R(ight) or C(enter) <width> The width of the column. If omitted the width will be calculated. As with the <margin> on the table the width can be specified in points, inches or centimetres. If a width is set too narrow, it may be ignored. $_$_END_TABLE Tagged table command: NEW_ROW ----------------------------- Each new row is identifies by the present of a NEW_ROW command on a line by itself. The format is $_$_BEGIN_PRE $_$_NEW_ROW <row_type> $_$_END_PRE where $_$_BEGIN_TABLE $_$_TABLE_MIN_COLUMN_SEPARATION 2 <row_type> This is the row type. Options include HEAD This is a header row DATA This is a data row LINE This is a line in the table The type may be omitted, in which case the default is "DATA" $_$_END_TABLE except when the NEW_ROW is a "LINE", this command should be followed by a series of NEW_CELL commands and their matching cell data - normally one per column. Tagged table command: NEW_CELL ------------------------------ Except for "LINE" rows, each new cell in a row identifies by the present of a NEW_CELL command on a line by itself. The contents of the cell follow on subsequent lines until either another NEW_CELL, NEW_ROW or END_TABLE command is encountered. The format of the NEW_CELL command is $_$_BEGIN_PRE $_$_NEW_CELL $_$_END_PRE At present the NEW_CELL command doesn't take any arguments. Tagged table: Cell contents --------------------------- Anything following a NEW_CELL command up until the next NEW_CELL, NEW_ROW or END_TABLE commands will be added into the current cell. The line structure will be preserved, so that if you have three lines of text following a NEW_CELL command, this will appear as a cell in the table with three lines of data in it. The alignment of the cell will normally be that of the column the cell is in. This will either have been calculated automatically for the column as a whole, or will be value passed in via the matching [[goto Tagged table command: COLUMN_DETAILS, COLUMN_DETAILS]] line, earlier in the table definition. $_$_HELP_CHAPTER 2,"Table modifier commands" Table modifier commands ======================= $_$_HELP_TOPIC_ID ID_PRE_TABLE These commands can be used to tailor the appearance of a table. They're usually placed between the BEGIN_TABLE ... END_TABLE for the table they will affect, but they can also be placed at the top of the document to define defaults for all tables. Any subsequent commands will apply for all tables detected from that point onwards. So, for example, you can change the width of each table just by issuing new TABLE_WIDTH commands. $_$_BEGIN_DELIMITED_TABLE $_$_TABLE_BORDER 0 $_$_TABLE_ALIGN CENTER $_$_TABLE_CELLSPACING 2 Directive Value Effect -------------------------------------------------------------------------------- [[goto Pre-processor command: TABLE_ALIGN, TABLE_ALIGN]] Align Specifies the alignment of the whole table. [[goto Pre-processor command: TABLE_BGCOLOR, TABLE_BGCOLOR]] Colour Colour of background [[goto Pre-processor command: TABLE_BORDER, TABLE_BORDER]] Number Size of border. 0 = None [[goto Pre-processor command: TABLE_BORDERCOLOR, TABLE_BORDERCOLOR]] Colour Colour of border [[goto Pre-processor command: TABLE_CAPTION, TABLE_CAPTION]] Text Table caption. Added centred at the top [[goto Pre-processor command: TABLE_CELL_ALIGN, TABLE_CELL_ALIGN]] Align Specifies the default alignment of cells. Left, right or center [[goto Pre-processor command: TABLE_CELLPADDING, TABLE_CELLPADDING]] Number Padding inside each cell [[goto Pre-processor command: TABLE_CELLSPACING, TABLE_CELLSPACING]] Number Spacing between cells. [[goto Pre-processor command: TABLE_COLO(U)R_ROWS, TABLE_COLO(U)R_ROWS]] (none) If present this specifies that the odd and even rows of the table should be coloured differently. See also the [[popup Colour data rows]] policy. [[goto Pre-processor command: TABLE_CONVERT_XREFS, TABLE_CONVERT_XREFS]] (none) If present, indicates that any section cross-references in the table may be converted to hyperlinks (see also the policy line [[popup Convert TABLE X-refs to links]]) [[goto Pre-processor command: TABLE_EVEN_ROW_COLO(U)R, TABLE_EVEN_ROW_COLO(U)R]] Colour When data rows are to be coloured this specifies the colour of the even numbered rows. [[goto Pre-processor command: TABLE_HEADER_ROWS, TABLE_HEADER_ROWS]] Number Number of header rows. These will be placed in <TH> .. </TH> markup [[goto Pre-processor command: TABLE_HEADER_COLS, TABLE_HEADER_COLS]] Number Number of header columns. These will be marked up in bold [[goto Pre-processor command: TABLE_IGNORE_HEADER, TABLE_IGNORE_HEADER]] (none) If present, indicates that the first few line (i.e. the header) should be ignored when calculating the column structure of the table. See also policy [[popup Ignore table header during analysis]] [[goto Pre-processor command: TABLE_LAYOUT, TABLE_LAYOUT]] Layout Explicit structure of table in terms of number of columns and their widths. See also policy [[popup Default TABLE layout]] [[goto Pre-processor command: TABLE_MAY_BE_SPARSE, TABLE_MAY_BE_SPARSE]] (none) If present, indicates that the TABLE may be sparse (see also the policy [[popup Expect sparse tables]]) [[goto Pre-processor command: TABLE_MIN_COLUMN_SEPARATION, TABLE_MIN_COLUMN_SEPARATION]] Number Number of spaces to be taken as a column separator when analysing the table (see also the policy [[popup Minimum TABLE column separation]]). [[goto Pre-processor command: TABLE_ODD_ROW_COLO(U)R, TABLE_ODD_ROW_COLO(U)R]] Colour When data rows are to be coloured this specifies the colour of the odd numbered rows. [[goto Pre-processor command: TABLE_WIDTH, TABLE_WIDTH]] Text The width of the table (see also the policy [[popup Default TABLE width]]) $_$_END_DELIMITED_TABLE Colours should be [[GOTO HTML Colours]] which will placed in the various attributes of the <BODY> tag and other. The program simply transcribes your value into the output file. Pre-processor command: TABLE_ALIGN ---------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_ALIGN This policy specifies the value to be given to the ALIGN attribute of the <TABLE> tag. Possible values are :- Left Right Center Pre-processor command: TABLE_BORDER ----------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_BORDER This policy specifies the value to be given to the BORDER attribute of the <TABLE> tag. This attribute determines the size of the table borders. If set to 0, no border will be added to the table. Pre-processor command: TABLE_BGCOLOR ------------------------------------ $_$_HELP_TOPIC_ID ID_PRE_TAB_BGCOLOR This species the value to be used in the BGCOLOR attributes of the <TABLE> tag. Not all browsers support these attributes. See the discussion about [[goto HTML colours]] Pre-processor command: TABLE_BORDERCOLOR ---------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_BORDERCOLOR This specifies the value to be used in the BORDERCOLOR attributes of the <TABLE> tag. Not all browsers support these attributes. See the discussion about [[goto HTML colours]] Pre-processor command: TABLE_CAPTION ------------------------------------ This specifies the table caption for the table(s) concerned Syntax: $_$_BEGIN_PRE $_$_TABLE_CAPTION <rest of line is the caption text> $_$_END_PRE The caption should normally only be applied to individual tables, as applying the same caption to all tables is unlikely to may much sense. Pre-processor command: TABLE_CELL_ALIGN --------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_CELLALIGN This specifies the value to be used in the ALIGN attribute of each cell within the table. By default the program will try to calculate a suitable alignment on a cell-by-cell basis. This command can override that behaviour. Pre-processor command: TABLE_CELLPADDING ---------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_CELLPADDING This specifies the value to be used in the CELLPADDING attribute of the <TABLE> tag. CELLPADDING specifies the amount of white space to be added to each table cell as padding round the cell’s contents. Pre-processor command: TABLE_CELLSPACING ---------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_CELLSPACING This specifies the value to be used in the CELLSPACING attribute of the <TABLE> tag. CELLSPACING specifies the amount of white space to be added between cells. Pre-processor command: TABLE_CONVERT_XREFS ------------------------------------------ Specifies that section numbers should be made into hyperlinks Syntax: $_$_BEGIN_PRE $_$_TABLE_CONVERT_XREFS $_$_END_PRE If present, indicates that any section cross-references in the table may be converted to hyperlinks See also [[popup Convert TABLE X-refs to links]] Pre-processor command: TABLE_HEADER_COLS ---------------------------------------- This specifies the number of header columns in a table Syntax: $_$_BEGIN_PRE $_$_TABLE_HEADER_COLS <integer number of columns> $_$_END_PRE Number of "header" columns (usually just 1). These will be marked up in bold Pre-processor command: TABLE_HEADER_ROWS ---------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_HEADER This specifies how many rows in the table should be regarded as the table header. Pre-processor command: TABLE_IGNORE_HEADER ------------------------------------------ $_$_HELP_TOPIC_ID ID_PRE_TAB_IGNORE_HEADER This directive specifies that a table header should be ignored during the column analysis Syntax: $_$_BEGIN_PRE $_$_TABLE_IGNORE_HEADER $_$_END_PRE This tag has no attributes. If present, indicates that the first few lines of the table - assumed to be the header - should be ignored when calculating the table's column structure. This should be enabled if the table has a particularly complex header that may confuse the program. This command has the same effect as the policy [[goto Ignore table header during analysis,Ignore table header when analysing columns]], but can be applied on a table-by-table basis when enclosed between [[goto Pre-processor command: TABLE, TABLE]] command markers. Pre-processor command: TABLE_LAYOUT ----------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_LAYOUT This directive allows you to specify the column structure of a table Syntax: $_$_BEGIN_PRE $_$_TABLE_LAYOUT <number of columns>,"<col 1 spec>","<col 2>",..... $_$_END_PRE where, $_$_BEGIN_TABLE <Number_of_cols> Integer number of columns <col_n_spec> Specification of the nth column. The specification must be contained in quote. Currently the specification consists of just the end position of the column. More may be added in later versions $_$_END_TABLE An example would be $_$_BEGIN_PRE $_$_TABLE_LAYOUT 3,"6","21","32" $_$_END_PRE which describes a 3-column table with column boundaries at the 6th, 21st and 32nd character positions. Normally this directive should be placed between the BEGIN_TABLE...END_TABLE directives for the table it applies to, thereby overriding the "intelligent" analysis the program would otherwise attempt for a plain text table. Pre-processor command: TABLE_MAY_BE_SPARSE ------------------------------------------ $_$_HELP_TOPIC_ID ID_PRE_TAB_SPARSE This specifies that the table may be sparse, i.e. largely empty in places. There is no data value required on this command. See also [[popup expect sparse tables]] policy Pre-processor command: TABLE_MIN_COLUMN_SEPARATION -------------------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_MINCOLSEP This specifies the minimum number of spaces to be regarded as a column separator. The default value is 1, but occasionally this gives too many columns, especially in short tables. Increasing this value will reduce the number of columns calculated. Pre-processor command: TABLE_WIDTH ---------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_WIDTH This specifies the value to be used for the WIDTH attribute of the <TABLE> tab. Table widths are specified in pixels, or as a percentage of the total screen width, thus “350” and “75%” would both be valid values. Pre-processor command: TABLE_COLO(U)R_ROWS ------------------------------------------ $_$_HELP_TOPIC_ID ID_PRE_TAB_COLOUR_ROWS This specifies the whether or not you want alternate data rows in the table coloured differently. Both American and British spellings of "colour" are supported. Pre-processor command: TABLE_ODD_ROW_COLO(U)R --------------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_ODD This specifies colour for odd data rows. Only applies when row colouring is selected. Both American and British spellings of "colour" are supported. Pre-processor command: TABLE_EVEN_ROW_COLO(U)R ---------------------------------------------- $_$_HELP_TOPIC_ID ID_PRE_TAB_EVEN This specifies colour for even data rows. Only applies when row colouring is selected Both American and British spellings of "colour" are supported. $_$_HELP_CHAPTER 2,"Other commands" Other commands ============== $_$_BEGIN_DELIMITED_TABLE [[popup Pre-processor command: BR, BR]] Insert a line break [[popup Pre-processor command: CHANGE_POLICY,CHANGE_POLICY]] Dynamically vary policies through the input file [[popup Pre-processor command: CONTENTS_LIST, CONTENTS_LIST]] Insert a hyperlinked contents list [[popup Pre-processor command: FILENAME, FILENAME]] Output the original filename [[popup Pre-processor command: FRACTION, FRACTION]] Output a fraction [[popup Pre-processor command: GOTO, GOTO]] Add a hyperlink to a section title [[popup Pre-processor command: HYPERLINK, HYPERLINK]] Insert a hyperlink into the document [[popup Pre-processor command: IGNORE_THIS,IGNORE_THIS]] Ignore some text in the source [[popup Pre-processor command: INCLUDE, INCLUDE]] Include an external file into the source [[popup Pre-processor command: LINERULE, LINERULE]] Insert a separator line into the output [[popup Pre-processor command: LINKPOINT, LINKPOINT]] Insert a hyperlink target location [[popup Pre-processor command: NAVIGATION_BAR,NAVIGATION_BAR]] Insert a navigation bar when splitting into files [[popup Pre-processor command: PAGE, PAGE]] Create a page boundary at this location [[popup Pre-processor command: POPUP, POPUP]] Add a hyperlink to a section title [[popup Pre-processor command: SUPER and SUB, SUPER and SUB]] Add superscripts and subscripts [[popup Pre-processor command: TOC]] Define a hyperlink target for the Table of Contents [[popup Pre-processor command: VERSION, VERSION]] Output the program version used in this conversion $_$_END_DELIMITED_TABLE Pre-processor command: BR ------------------------- This command tells the software to output a line break at this point. Usually the default is to let all lines flow together to form a paragraph. This commands can be used (e.g. in address lines to make sure lines are correctly placed on new lines). Pre-processor command: CHANGE_POLICY ------------------------------------ $_$_HELP_TOPIC_ID ID_PRE_CHANGEPOLICY This option allows you to embed policy lines in the source document. This can be used to avoid the need for separate policy files, or to change the policy at different locations within the document (although the effects can sometimes be unpredictable). The syntax is $_$_BEGIN_PRE $_$_CHANGE_POLICY <policy line as in policy file> $_$_END_PRE For example placing $_$_BEGIN_PRE $_$_CHANGE_POLICY Background colour : Red $_$_END_PRE would make all subsequent HTML files have a red background. This could be used to colour each section of a document differently when splitting a file into a number of HTML files. For details of policy lines that can be used, see [[goto Alphabetical list of policies available in AscToHTM]] or the [Policy Manual] in the [[goto Documentation available,HTML documentation]] Pre-processor command: CONTENTS_LIST ------------------------------------ Defines the location to place the contents list (if any). By default the contents list is placed at the top of the document before any other end-user text, but by using this command you can specify a location of your choice. Syntax: $_$_BEGIN_PRE $_$_CONTENTS_LIST <number_levels>,<Style>,<Range>, _More to be defined_ $_$_END_PRE where, $_$_BEGIN_TABLE <number_levels> number of levels of heading to be shown in the list 1,2,3... A value of "0" means all. The default value will be 0. <Style> Style of contents list 1 - traditional list (default) 2 - navigation bar The default value will be 1. <Range> Range of headings to include in the list 0 - All (default) 1 - All bar first 2 - Only those in current chapter 3 - Only those in current section $_$_END_TABLE Pre-processor command: FILENAME ------------------------------- This in-line tag substitutes the name of the files being converted Syntax: $_$_BEGIN_PRE [[OT]]FILENAME[[CT]] $_$_END_PRE The tag will be replaced by the name of the file being converted. This facilitates the construction of sentences like "This file was converted from *[[OT]]FILENAME[[CT]]* at *[[OT]]TIMESTAMP[[CT]]*" which becomes "This file was converted from *[[FILENAME]]* at *[[TIMESTAMP]]*" $_$_BEGIN_IGNORE ! Pre-processor command: FO ! ------------------------- ! _(New in version 5.0)_ ! ! NOTE: The FO tag is only currently supported in RTF generation. ! ! This in-line tag allows the font used in a document to be changed, either ! locally within some text, or from this point onwards. ! ! The FO tag should be used in conjunction with a [[goto Using Style Definition Files (SDF),Style Definition File (SDF)]], which can be ! used to define the "font id"s that are used ! ! Syntax: ! ! FO [<font_id>],[<font_size>],[<font_weight>] ! ! where ! ! $_$_BEGIN_TABLE ! $_$_TABLE_LAYOUT 2,24,132 ! <font_id> Identifies the font to be used. This must match the ! name of a font in the SDF file. If no name is given then ! the prevailing font will be used. ! ! <font_size> The font size in pts. Only needed if the default ! value in the font table is to be overridden. ! ! The size can be supplied as an absolute value or - if a plus or ! minus sign is present - as a relative size. So for example ! "4" means 4pt, whereas "+4" means 4pt larger than the ! surrounding text. ! ! A value of "-" will be taken as a reset to the prevailing ! default font size. ! ! <font_weight> The font weight. Only needed if the default value ! in the font table is to be overridden. Possible values ! are ! ! it (Italic) ! bo (Bold) ! bi (Bold Italic) ! no (Normal) ! - (Reset) ! ! The "reset" will cause the weight to be reset to the ! prevailing default, i.e. no longer override the ! prevailing font. ! $_$_END_TABLE ! ! Example: ! ! $_$_BEGIN_PRE ! "This text is [[ot]]fo ,+6,bo[[ct]]big and bold,[[ot]]fo ,-,-[[ct]] but this text is ! normal again" ! $_$_END_PRE ! ! becomes ! ! "This text is [[fo ,+6,bo]]big and bold,[[fo ,-,-]] but this text is ! normal again" ! ! (this may only work in the RTF version of this document) ! ! See also [[goto Scope for font tags]] ! $_$_END_IGNORE Pre-processor command: FRACTION ------------------------------- This in-line tag implements a fraction Syntax: $_$_BEGIN_PRE [[OT]]FRACTION <expression>[[CT]] $_$_END_PRE where $_$_BEGIN_TABLE <expression> This is the fraction expression which should contain a slash ("/") separating the numerator and denominator Both values must be present. $_$_END_TABLE So for example The fractions [[OT]]FRACTION 5/16[[CT]] and 1[[OT]]FRACTION 1/2[[CT]]. becomes The fractions [[FRACTION 5/16]] and 1[[FRACTION 1/2]]. Pre-processor command: GOTO --------------------------- _(New in version 5.0)_ This in-line tag adds a hyperlink to the named section heading. Syntax: $_$_BEGIN_PRE [[OT]]GOTO <Heading_name>[[CT]] $_$_END_PRE where $_$_BEGIN_TABLE <Heading_name> Name of a heading else where in the file. The text used must match exactly for this tag to work (case insensitive though) $_$_END_TABLE It creates a hyperlink to the named section heading. The heading must match the text exactly, and be in the same file. It must also have been recognised by AscToHTM as a heading. See also the [[POPUP Pre-processor command: HYPERLINK, HYPERLINK]] and [[POPUP Pre-processor command: POPUP, POPUP]] commands. Pre-processor command: HYPERLINK -------------------------------- This command defines a hyperlink to a LINKPOINT, Table of Contents (TOC) entry or external URL Syntax: $_$_BEGIN_PRE [[OT]]HYPERLINK <type>,"<link_name>","<display_text>"[[CT]] $_$_END_PRE where, $_$_BEGIN_TABLE <type> Type of link. Choices are:- TOC - link to a TOC entry LINK - link to a LINKPOINT entry URL - link to a named URL <link_name> Name of link. For TOC and LINK this must be the name used in the matching TOC or LINK tag. For a URL this will be the URL to link to. TOC and LINK hyperlinks will be checked against the list of known link points. If no match is found an error is generated, and the tag is simply replaced by the display text. <display_text> The on-screen text to be used for the hyperlink. If omitted it will default to the <link_name> $_$_END_TABLE See also [[goto Pre-processor command: GOTO, GOTO]] and [[goto Pre-processor command: POPUP, POPUP]] Pre-processor command: IGNORE_THIS ---------------------------------- This is an in-line tag whose contents are ignored. Could be used for comments Syntax: $_$_BEGIN_PRE [[OT]]IGNORE_THIS <anything_you_like>[[CT]] $_$_END_PRE This tag is ignored. It is replaced by a single space in the output stream. It could be used to add a brief comment to your source that would not appear in the output. See also the [[goto Pre-processor command: IGNORE, IGNORE]] command Pre-processor command: INCLUDE ------------------------------ $_$_HELP_TOPIC_ID ID_PRE_INCLUDE You can include one source file in another by using the include command as follows:- $_$_BEGIN_PRE $_$_INCLUDE filename $_$_END_PRE Make sure the file is accessible from wherever AscToHTM is run, or in the same directory as the original source file. AscToHTM will read the file on each pass, treating its contents as part of the main file for both analysis and conversion purposes. Note, the include file should be plain text, which will be converted as normal for the document. It may include other pre-processor commands including further INCLUDE commands up to a limit of 9 levels. Be careful not to set up include loops (i.e. a includes b include c includes a etc). Include files like this can be a useful way of embedding standard disclaimers etc, and compliment the use of header and footers. Pre-processor command: LINERULE ------------------------------- This command allows you to insert a separator line into your HTML output. Syntax: $_$_BEGIN_PRE $_$_LINERULE <length>,<thickness>,<leading>,<alignment>,<colour> or [[OT]]LINERULE <length>,<thickness>,<leading>,<alignment>,<colour>[[CT]] $_$_END_PRE where $_$_BEGIN_TABLE <length> length of line in pixels/pts/percent. To specify a percentage add the percent sign (%) after the value <thickness> thickness of line in pixels/pts <leading> leading of line in pixels (not yet implemented) <alignment> Code indicating the alignment. Possible values are L - Left aligned R - Right aligned C - Centre aligned J - justified <colour> Colour value. Either an HTML colour like "AABBCC" or "red" or a (R,G,B) value like "0.12,0.57,1.0". A RGB value must be included in quotes. If omitted the linerule will adopt the prevailing text colour. $_$_END_TABLE Pre-processor command: LINKPOINT -------------------------------- This command marks the location of an HTML anchor point. This can then be used as the target of a hyperlink, particularly in a [[goto Pre-processor command: HYPERLINK, HYPERLINK]] command. Syntax: $_$_BEGIN_PRE [[OT]]LINKPOINT "<link name>"[[CT]] $_$_END_PRE where, $_$_BEGIN_TABLE <link_Name> This is the name by which the link will be known. It is also the text that will be placed in the NAME anchor point, so only valid characters should be used. $_$_END_TABLE Pre-processor command: NAVIGATION_BAR ------------------------------------- The NAVIGATION_BAR command inserts a navigation bar that takes you to the next/previous and contents files. This will only be generated when you have selected to split your file by setting the [[popup Split level]] policy. Syntax: $_$_BEGIN_PRE $_$_NAVIGATION_BAR $_$_END_PRE Pre-processor command: PAGE --------------------------- _(New in version 5.0)_ The syntax is $_$_BEGIN_PRE $_$_PAGE $_$_END_PRE This signals a page boundary. This command is primarily intended for use in RTF creation by [AscToRTF]. In HTML the concept of page boundaries isn't really supported, so a horizontal rule <HR> is put out instead. Pre-processor command: POPUP ---------------------------- _(New in version 5.0)_ This in-line tag adds a hyperlink to the named section heading. Syntax: $_$_BEGIN_PRE [[OT]]POPUP <Heading_name>[[CT]] $_$_END_PRE This behaves in an identical manner to the [[goto Pre-processor command: GOTO, GOTO]] unless you are using [AscToRTF] creating an RTF file for use as a Windows Help file, in which case the hyperlink link becomes a pop-up link, instead of a full "go to" link. See also the [[POPUP Pre-processor command: HYPERLINK, HYPERLINK]] command. Pre-processor command: SUPER and SUB ------------------------------------ These in-line tags implement superscripts and subscripts Syntax: $_$_BEGIN_PRE [[OT]]SUPER <expression>[[CT]] [[OT]]SUB <expression>[[CT]] $_$_END_PRE So for example $_$_BEGIN_PRE This[[OT]]SUPER superscript[[CT]] and that[[OT]]SUB subscript[[CT]] $_$_END_PRE becomes This[[SUPER superscript]] and that[[SUB subscript]] Pre-processor command: TOC -------------------------- Marks a Table of Contents entry, and the location of the associated hyperlink. The TOC directive marks a point in the file that will receive an anchor point, and then be linked to from any generated contents lists. This can be useful to index non-headings like key diagrams and tables. Syntax: $_$_BEGIN_PRE $_$_TOC <level>, <link name>, <display text> $_$_END_PRE where, $_$_BEGIN_TABLE <level> the level in the TOC, starting with 1 being the most significant, equivalent to "chapter" <link name> The (usually short) name by which this linkpoint may be known. This is the value used to create an ANCHOR point, and which may be referenced in any HYPERLINK tag. <display text> The text to be shown in the TOC. This will also be used to generate an ANCHOR name, and may be used in a TOC type HYPERLINK Tag, although this is marginally less portable than referencing the link name If omitted, defaults to the link name, and only one ANCHOR is created. $_$_END_TABLE See also the [[popup Pre-processor command: HYPERLINK, HYPERLINK]] command. Pre-processor command: VERSION ------------------------------ This in-line tag adds a description of the program name/version used to convert the files (e.g. "AscToHTM 5.0") Syntax: $_$_BEGIN_PRE [[OT]]VERSION[[CT]] $_$_END_PRE Outputs the version name of the conversion into the output file. For example "[[VERSION]]". $_$_HELP_CHAPTER 1,"Using HTML Fragments to customise your HTML" $_$_HELP_SUBJECT "Overview HTML Fragments" Using HTML fragments ******************** The "HTML fragments" feature allows you to define a block of HTML that you can then embed in your document at key locations. These fragments are pure HTML that gets transcribed into the output files, but they may contain [[GOTO "fragment tags"]] that will be replaced by suitable values each time the fragment is used. Most fragments use reserved names, that is they have a particular meaning to the program. If you define fragments with these names they will be used instead of the HTML that is generated by default. Currently only fragments with reserved names are used by the software. The ability to define and use your own fragments names may be added in later versions of the software. You can choose to define empty fragments. This can be done either by literally defining a fragment with no HTML in it, or by issuing a RESET_HTML_FRAGMENT command - see [[POPUP Pre-processor command: DEFINE_HTML_FRAGMENT,DEFINE_HTML_FRAGMENT]] and [[popup Pre-processor command: RESET_HTML_FRAGMENT,RESET_HTML_FRAGMENT]] If an empty HTML fragment is defined then no HTML will be generated. If the fragment name is a reserved name then the result is to suppress that particular feature. For example the command $_$_BEGIN_PRE $_$_RESET_HTML_FRAGMENT NAVBAR_TOP $_$_END_PRE would cause the navigation bar at the top of each page to be suppressed when splitting large documents into several small pages. HTML fragments may be defined either in the source text, or in a separate "HTML fragments file". This file may then be selected via the policy [[popup Fragments file]]. Only the fragments themselves will be read from this file, everything else will be ignored, leaving you free to add your own comments to this file between the fragment definitions. If you don't want to set the policy you can get the same effect by using the [[POPUP Pre-processor command: INCLUDE, INCLUDE]] command as follows $_$_BEGIN_PRE $_$_INCLUDE <fragments file> $_$_END_PRE to your source file near the top. This will copy the fragments file into your source text, so in this case you should include no other text in this file as it will appear in the output. You may, if you wish, re-define the HTML fragment later in the file. This will take effect from that point onwards. For example if you redefine the HORIZONTAL_RULE fragment to be an image, you could arrange for this image to change for different sections of your document. How to define a HTML fragment ============================= Simply use pre-processor commands as follows $_$_BEGIN_PRE $_$_DEFINE_HTML_FRAGMENT <name> ... ...<your HTML with embedded "fragment tags"> ... $_$_END_BLOCK $_$_END_PRE For example, $_$_BEGIN_PRE $_$_DEFINE_HTML_FRAGMENT NAVBAR_BOTTOM <A HREF="[[OT]]PREV_PAGE[[CT]]"><IMG SRC="prev.gif"></A> <A HREF="[[OT]]NEXT_PAGE[[CT]]"><IMG SRC="next.gif"></A> $_$_END_BLOCK $_$_END_PRE could define a navigation bar for the bottom of each page which adds a hyperlink to the previous and next page which is added to some .gif. The [[GOTO fragment tags]] [[OT]]PREV_PAGE[[CT]] and [[OT]]NEXT_PAGE[[CT]] will be replaced by the correct URLs. $_$_BEGIN_PRE $_$_RESET_HTML_FRAGMENT NAVBAR_TOP $_$_END_PRE or $_$_BEGIN_PRE $_$_DEFINE_HTML_FRAGMENT NAVBAR_TOP $_$_END_BLOCK $_$_END_PRE both define an "empty" top navigation bar, thereby suppressing the generation of a navigation bar at the top of each page. Fragment tags ============= Within HTML fragments special "fragment tags" are supported. These tags have the same overall format as the more general pre-processor tags, but are only supported inside HTML fragments. The following tags are supported - [[goto Tags for frame fragments]] - [[goto Tags for heading fragments]] - [[goto Tags for horizontal rule fragments]] - [[goto Tags for navigation bar fragments]] - [[goto Tags for Table of Contents fragments]] Tags for navigation bar fragments --------------------------------- $_$_BEGIN_TABLE Tag Description ========================================================================= PREV_PAGE URL of previous page. If no pervious page then URL of *this* page CURRENT_PAGE URL of the current page. Can be useful if you want to construct a NOFRAMES link to the current page. NEXT_PAGE URL of next page. If no next page then the URL of *this* page. CONTENTS_TOP URL of page containing contents list CONTENTS_NEXT_SECTION As above - but linked to an anchor for the next section in the contents list. $_$_END_TABLE Tags for horizontal rule fragments ---------------------------------- $_$_BEGIN_TABLE Tag Description ========================================================================= RULEWIDTHPC The calculated ruler width expressed as a percentage. Often the program will detect a line, and will set it as a <HR> tag of the appropriate percentage width. This is that value. RULEWIDTH The calculated ruler width. This will be the percentage width expressed for a default 800 pixel wide screen. RULEHEIGHT The ruler height. Not usually varied unless supplied as part of a [[POPUP Pre-processor command: LINERULE, LINERULE]] tag. RULEALIGN The ruler alignment. This may sometimes be set to LEFT if a less that 100% rule is being generated, or it may be set to some other value by a user-supplied [[POPUP Pre-processor command: LINERULE, LINERULE]] tag. $_$_END_TABLE The above values are all supplied ready to be used as attribute values. As such they should normally be enclosed in quotes in your HTML fragment. If you're using an <IMG> tag and want to capture the width, use the RULEWIDTH value. If you're generating an <HR> tag we recommend the RULEWIDTHPC percentage value instead. Tags for frame fragments ------------------------ Currently there is only one fragment tag used inside frames fragments :- $_$_BEGIN_TABLE NOFRAMES_URL This is the URL used by default for any NOFRAMES link. Typically you'd use this inside a NOFRAMES_LINK fragment to link to the same URL as the default NOFRAMES link would, while adding your own text and decoration for the link. $_$_END_TABLE Tags for Heading fragments -------------------------- The following tags may be used inside the various Heading tag fragments $_$_BEGIN_TABLE HEADER_TEXT The text part of the heading HEADER_LEVEL The heading level (1,2,3...). Note, this is the *logical* heading level. The default markup might use a different <Hn> tag because these values are limited in range to ensure text is a sensible size (<H1> is too big, <H4> is too small etc). $_$_END_TABLE Tags for Table of Contents fragments ------------------------------------ The following tags may be used inside the various TOC line tag fragments $_$_BEGIN_TABLE TOC_TEXT The text part of the TOC line TOC_LEVEL The TOC level (1,2,3...) TOC_URL The URL for this TOC line $_$_END_TABLE Reserved HTML fragment names ============================ Here are the reserved HTML fragment names recognised by the software, and their effect on the HTML generated. Navigation bar fragments ------------------------ $_$_BEGIN_TABLE NAVBAR_TOP_FIRST The navigation bars output at the top of the NAVBAR_TOP first, general or last pages. Usually the first and NAVBAR_TOP_LAST last navigation bars may wish to omit the previous or next links (since no such page exists). If the "_FIRST" and "_LAST" fragments are not defined, the "NAVBAR_TOP" fragment will be used instead. NAVBAR_MIDDLE Any navigation bar output in the middle of a page as a result of a [[POPUP Pre-processor command: NAVIGATION_BAR,NAVIGATION_BAR]] tag. NAVBAR_BOTTOM_FIRST As for the "NAVBAR_TOP" fragments, but this time NAVBAR_BOTTOM at the bottom of generated pages. NAVBAR_BOTTOM_LAST $_$_END_TABLE Table fragments --------------- $_$_BEGIN_TABLE TABLE_HEADER Any HTML fragment to be output *before* a table. This won't actually replace the table header itself, but could be used to insert a title. TABLE_FOOTER Any HTML fragment to be output *before* a table. $_$_END_TABLE The horizontal rule fragment ---------------------------- $_$_BEGIN_TABLE HORIZONTAL_RULE The horizontal ruler. Normally this is just <HR>, but you can change that by defining a HTML fragment of this name, e.g. to use an <IMG> tag (see [[GOTO A sample HTML Fragments file]]). $_$_END_TABLE Table of contents fragments --------------------------- These fragments can be used to tailor the appearance of a generated contents list. $_$_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> TOC_LINE_<n> A fragment to be output for TOC contents lines at heading level <n> (<n> = 1,2,3...) TOC_LINE The default fragment to be used for TOC content lines if the specific fragment TOC_LINE_<n> is not defined $_$_END_TABLE When create TOC_LINE fragments, you will almost certainly want to use the TOC_TEXT and TOC_URL fragment tags (see [[POPUP Tags for Table of Contents fragments]]). HTML headers, footers and JavaScript fragments ---------------------------------------------- The program previously supported the insertion of HTML at the start and end of each HTML page generated through the policies - [[popup HTML header file]] - [[popup HTML footer file]] - [[popup HTML script file]] The new fragments HTML_HEADER, HTML_FOOTER and HEAD_SCRIPT provide exactly the same functionality. The use of fragments is encouraged over that of the previous policies, so where both are defined, the fragment will be used (e.g. a HTML_HEADER fragment will override a "HTML header file" policy value). HTML header and footers (inside FRAMES) fragments ------------------------------------------------- A number of fragments can be used to control the creation of header and footer FRAMES, and the creation of headers and footers inside the main frame. The use of these fragments depends on the values of the policies - [[popup Use main header in header frame]] - [[popup Use main footer in footer frame]] which can be used to promote a HTML header/footer from the top of each HTML page into a frame by itself. This allows the same policy file to be used to generate a non-FRAMES set of pages with headers and footers on each page, and also a FRAMES set of pages with the same headers and footers now permanently on display in their own frames at the top and bottom of the screen. The following fragments can be used to define the contents of particular frames :- $_$_BEGIN_TABLE HEADER_FRAME If defined, this fragment will be used as the contents of a header frame at the top of the screen FOOTER_FRAME If defined, this fragment will be used as the contents of a footer frame at the bottom of the screen NOFRAMES_LINK If defined, this fragment will be used in place of any NOFRAMES link that is created by default. You would most likely use this with the NOFRAMES_URL fragment tag to define alternative text on the link. CONTENTS_FRAME If defined, this fragment will be 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 will be used as the HTML footer of each page that appears in the main frame. If defined this will override any HTML_FOOTER fragment, or value defined via policy file. MAIN_FRAME_HEADER If defined, this fragment will be used as the HTML header of each page that appears in the main frame. If defined this will override any HTML_HEADER fragment, or value defined via policy file. $_$_END_TABLE Heading fragments ----------------- Where headings are detected in the program, you can use the following HTML fragments HTML_HEADER_LINE_<n> The fragment to be used for headings of level <n> (<n> = 1, 2 3...) HTML_HEADER_LINE The default fragment to be used for headings if there isn't a specific HTML_HEADR_LINE_<n> for the value of <n> involved. The default markup would be to place the heading text in <Hn> tags. Using the [[POPUP Tags for Heading fragments]] you could reproduce this in your own fragments as follows <H[[OT]]HEADER_LEVEL[[CT]]>[[OT]]HEADER_TEXT[[CT]]</H[[OT]]HEADER_LEVEL[[CT]]> e.g. if the heading was "Introduction" and this was a level 1 heading, this would become <H1>Introduction</H1> A sample HTML fragments file ============================ The following sample fragments file does the following - Defines a HORIZONTAL_RULE fragment to use an image in place of the <HR> tag. The image uses the HTML fragment tags RULEALIGN and RULEWIDTH to take on the necessary alignment and size. - Defines a HEADER_FRAME that contains a title and link to the home page, both centred on the page. This fragment will only be used when generating a set of FRAMES. - Does a reset on the NAVBAR_BOTTOM fragment. This effectively defines an empty fragment whose effect is to suppress the navigation bar usually put at the bottom of each page when splitting a large file into sections. $_$_LINERULE $_$_BEGIN_PRE !----- sample HTML fragments file Comments in this file (like these) are ignored if the file is selected via the "HTML fragments file" policy. !----- Horizontal rules ! Here's a redefinition of the horizontal rules <HR> that the program generates. ! I'm replacing them by an image, but I'm capturing the (pixel) width and fixing ! the height (otherwise the image would scale). ! ! Within this fragment I'm using the [[OT]]RULEALIGN[[CT]] and [[OT]]RULEWIDTH[[CT]] HTML ! fragment tags to pick up the alignment and width appropriate for the rule ! when the fragment is used. ! ! NOTE, not all <HR> tags created by the program are currently overridden in ! this way. $_$_DEFINE_HTML_FRAGMENT HORIZONTAL_RULE <DIV ALIGN="[[OT]]RULEALIGN[[CT]]"> <IMG SRC="HR.GIF" HEIGHT=4 WIDTH="[[OT]]RULEWIDTH[[CT]]"><BR> </DIV> $_$_END_BLOCK !----- Frame headers $_$_DEFINE_HTML_FRAGMENT HEADER_FRAME <DIV ALIGN="CENTER"> <H2>header frame</H2> <A HREF="http://www.jafsoft.com/">Visit the Jaf soft home page!</A> </DIV> <HR NOSHADE> $_$_END_BLOCK !----- bottom navigation bars ! I don't want any bottom navigation bars so issue a reset command. ! I could just as easily have defined an "empty" fragment $_$_RESET_HTML_FRAGMENT NAVBAR_BOTTOM $_$_END_PRE The HTML fragments file used on this document is html_fragments.inc $_$_HELP_CHAPTER 1,"Using Table definitions Files to improve table handling" $_$_HELP_SUBJECT "Overview of Table Definition Files (TDF)" Using Table Definition Files (TDF) ********************************** $_$_HELP_TOPIC_ID HIDD_TDF_FILE _(New in version 5.0)_ AscToHTM has the ability to detect and analyse tables. However, if you want to convert a file containing multiple tables, or to convert multiple files containing a variety of tables, it may be useful to create a "Table Definition File" (TDF). In this file you can define multiple table types, and each type can be associated with a particular [[goto Defining a Table Structure, structure]] and a particular [[goto Defining a Table format, format]]. By associating a [[goto Defining a Table Type, table type]] with a structure, you are telling the software how the table is laid out, thereby simplifying it's task, and reducing the likelihood of analysis errors. By associating a [[goto Defining a Table Type, table type]] with a format, you can control various aspects of how the final table looks. Using TDF files you can - Customise the <TABLE> tag, and each cell in specified columns to have the CSS ID and HTML attributes of your choice added. This facilitates the fine tuning of appearance and the use of JavaScript on an almost cell-by-cell basis. - Define "alarm" conditions for cells in a specified column, and have cells that are in alarm change colour, or to be placed in a different CSS class, so that they can be marked out through your stylesheet definitions. See [[goto Defining table alarms]] - Define a "barchart" for cells in a given column, so that each cell's value is displayed as a bar sized to represent the value of the cell. See [[goto Defining table graphs and barcharts]] - Selectively extract data form the table for use elsewhere in the HTML. See [[goto Locating data in a table]] You can see [[goto An example TDF file]] $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION MAKINGRTF See - [[goto Loading the Table Definition File]] and - [[goto Defining a table type]] - [[goto Defining a table structure]] - [[goto Defining a table format]] $_$_SECTION ALL Loading the Table Definition File ================================= All the table definition information should be placed in a "Table Definitions File" (TDF). By convention this file should have a ".inc" extension, but this isn't a requirement. To have the file loaded, you will need to set a policy line in your policy file of the form $_$_BEGIN_PRE [config files] Definitions file : table_definitions.inc $_$_END_PRE This will normally appear in the "[config files]" section of your policy file, but again this isn't strictly necessary. Once this option appears in your policy file, the table definitions file will be loaded before the conversion process starts. During the conversion each table that is found will be tested against the known table types, and if a match is made, any associated structure and formatting will be applied. You can select the Style Definition File that you want from the _Config File locations_ menu option. $_$_HELP_CHAPTER 2,"Identifying table types" $_$_HELP_SUBJECT "Defining a Table Type section" Defining a Table Type ===================== Whenever the software identifies a candidate table, it will check against the Table Definitions File (TDF) to see if this is a table of a known type. If it is, it will apply any defined structure or formatting for that type to the candidate table. Table types are defined by having a series of table type sections something like the following in your definition file $_$_BEGIN_PRE table type : Rank must contain : Rank ROC5 ROC10 ROC21 use format : format_rank use structure : structure_rank $_$_END_PRE Each table type section starts with the [[goto TDF line: table type, table type]] line, and is followed by a number of additional definition lines that apply to this table type. NOTE: The [[goto TDF line: use format, use format]] and [[goto TDF line: use structure, use structure]] lines are optional, although you would want at least one to be present for the table type to have any real use. Each table type section must contain at least one "identifier" line. Identifier lines are those that specify conditions by which tables of this type can be identified. NOTE: At present the only identifier line supported is the [[goto TDF line: must contain, must contain]] line The identifier line(s) specify conditions that are used to test each table to see if it could be of this type. Commonly the test is a search for text that is present in the header of all tables of this type. If multiple table type sections are defined, then the first table type whose identifiers match the table is used, so the ordering of table type sections within the definition file can be important. For example :- $_$_BEGIN_PRE table type : type_1 must contain : Rank ... table type : type_2 must contain : date Rank ... $_$_END_PRE In the above example any table that contains a line of text containing "date rank" would match both table types. Since type_1 is listed first, all such tables would be treated as type_1. In this case it would be better to define type_2 first as below $_$_BEGIN_PRE table type : type_2 must contain : date Rank ... table type : type_1 must contain : Rank ... $_$_END_PRE With the above definitions, a table containing "date rank" would be assigned to type_1, one which simply contained "rank" would be type_2 TDF line: Table type -------------------- The presence of a "table type" line in the definition file marks the start of a new table type definition. The line has the format $_$_BEGIN_PRE table type : <type_name> $_$_END_PRE where <type_name> is the a unique name for this type of table, and shouldn't contain any spaces. TDF line: Must contain ---------------------- The "must contain" line is an identifier line. That is it is a condition applied against a candidate table to see if it matches this table type. The line has the format : $_$_BEGIN_PRE must contain : <text_to_be_matched> $_$_END_PRE The candidate table is tested line-by-line, so the text to be matched must be wholly contained within one line of the source text. When testing the match expression the case of the text being tested is ignored, and all multiple white space is treated as a single space. So the match text "Date rank" will match the word "date" followed by any number of spaces and tabs, followed by "rank". A good use of this line would be to match the know headers in a table, e.g. $_$_BEGIN_PRE must contain : Date Temperature Max Min $_$_END_PRE would match a table with headers "Date", "temperature", "MAX" and "MIN" if they were in that order, regardless of the spacing. NOTE: At present only one "must contain" line per table type is supported TDF line: Use Structure ----------------------- The "use structure" line specifies that if a table matches the identifying conditions for this table type, then it's structure should be interpreted according to the rules specified in the named table structure section. This line has the form $_$_BEGIN_PRE use structure : <structure_name> $_$_END_PRE where <structure_name> is the name of a table structure section defined elsewhere in the definition file. The <structure_name> should contain no spaces. The same structure may be shared by multiple table types, that is several table type sections could all end up having the same "use structure" line. If the <structure_name> given doesn't match a structure defined elsewhere in the definition file, then the software will report this error each time it matches a table of this type and then fails to locate the named structure. That is it gives a runtime error, rather than reporting the error when the definition file is loaded. NOTE: This may change in later versions See [[goto Defining a table structure]] TDF line: Use Format -------------------- The "use format" line specifies that if a table matches the identifying conditions for this table type, then it should be formatted according to the rules specified in the named table format section. This line has the form $_$_BEGIN_PRE use format : <format_name> $_$_END_PRE where <format_name> is the name of a table format section defined elsewhere in the definition file. The <format_name> should contain no spaces. The same format may be shared by multiple table types, that is several table type sections could all end up having the same "use format" line. If the <format_name> given doesn't match a format defined elsewhere in the definition file, then the software will report this error each time it matches a table of this type and then fails to locate the named format. That is it gives a runtime error, rather than reporting the error when the definition file is loaded. NOTE: This may change in later versions See [[goto Defining a table format]] $_$_HELP_CHAPTER 2,"Defining table layouts" $_$_HELP_SUBJECT "Defining a Table Structure section" Defining a Table Structure ========================== Table structures are defined by having a table structure section something like the following in your definition file $_$_BEGIN_PRE table structure : Percent_funds Layout : 6,31,41,51,61,71,81 $_$_END_PRE Each table structure section starts with the [[goto TDF line: table structure, table structure]] line, and is followed by [[goto TDF line: layout, layout]] line. TDF line: Table structure ------------------------- The presence of a "table structure" line in the definition file marks the start of a new table structure definition. The line has the format $_$_BEGIN_PRE table structure : <structure_name> $_$_END_PRE where <structure_name> is the a unique name for this structure, and shouldn't contain any spaces. The <structure_name> is the name used in any "[[goto TDF line: use structure,Use structure]]" statement in a table type section. TDF line: Layout ---------------- The Layout line in a table structure section describes how the matched table should be interpreted into columns. The format of the Layout line is the same as that used by the [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] pre-processor command. $_$_BEGIN_PRE Layout : 6,7,39,51,61,71,80 $_$_END_PRE For example the above line specifies the data comes in 6 columns which end at the column positions 7, 39, 51.. etc $_$_HELP_CHAPTER 2,"Defining table formats" $_$_HELP_SUBJECT "Defining a Table Format section" Defining a Table Format ======================= Table formats are defined by having a table format section something like the following in your definition file $_$_BEGIN_PRE table format : Rank column names : ,,,ROC5,ROC10,ROC21 caption : Rankings table colour : #E1D1C1 border colour : #E2E2E2 Colour data rows : Yes border size : 2 HTML attributes : onmouseover='click' HTML cell attributes : nowrap show columns : no,no,no,,,,,,,, $_$_END_PRE TDF line: Table format ---------------------- The presence of a "table format" line in the definition file marks the start of a new table format definition. The line has the format $_$_BEGIN_PRE table format : <format_name> $_$_END_PRE where <format_name> is the a unique name for this format, and shouldn't contain any spaces. The <format_name> is the name used in any "[[goto TDF line: use format,Use format]]" statement in a table type section. TDF line: Column names ---------------------- The "Column Names" line allows you to give each column a name. This name should be unique, and can be referenced in more advanced configuration lines. TDF line: Column format ----------------------- The "Column Format" line specifies how cells in a particular column should be formatted. The format of this line is as follows $_$_BEGIN_PRE column format : name=<name> css_id=<id> barchart=<chartname> alarms=<alarm_list> $_$_END_PRE where $_$_BEGIN_TABLE name (mandatory). The unique name given to this column format. This is used to match the name listed for the column in the [[popup TDF line: Column names, column names]] line. css_id (optional). The CSS class ID to be added to cells in this column of the table barchart (optional). Identifies the name of any [[popup TDF line: Column names, barchart]] to be used to display data in this column. alarms (optional). Identifies the name of any [[popup TDF line: alarm, alarms]] to be applied against data in this column. $_$_END_TABLE TDF line: Caption ----------------- The "Caption" line allows you to add a caption to any table that matched the table type conditions. TDF line: Column alignments --------------------------- The "Column alignments" line allows you to define the alignment of each column. The format is $_$_BEGIN_PRE column alignments : "<alignment_1>","<alignment_2>",... $_$_END_PRE where alignment is LEFT,RIGHT,CENTER. If a value is omitted, the software will automatically calculate the best alignment for the column. TDF line: Column headers ------------------------ The "Column headers" line allows you to define the headers to put at the top of the each column. The format is $_$_BEGIN_PRE column headers : "<heading_1>","<heading_2>",... $_$_END_PRE If you want a heading to break over several lines, insert the text "\n" wherever you want a line break. TDF line: Column widths ----------------------- The "Column widths" line allows you to define the width of each column in pixels or as a percentage. The format is $_$_BEGIN_PRE column widths : "<width_1>","<width_2>",... $_$_END_PRE If a value is omitted, the software will normally leave the width unspecified allowing the browser to fit the data in the bets way it can. TDF line: CSS ID ---------------- This specifies the CSS_ID to be added to the <TABLE> tag of the matching table. If omitted, each table will be given a unique name in the form "table_1", "table_2" etc. Format $_$_BEGIN_PRE CSS ID : <ID_value> $_$_END_PRE TDF line: Table colour ---------------------- The "Table Colour" line allows you to specify a background colour for the table. TDF line: Border colour ----------------------- The "Border Colour" line allows you to specify a border colour for the table. TDF line: Colour data rows -------------------------- The "Colour data rows" line allows you to specify that odd and even rows of the table should be coloured differently to allow the table to be more easily understood. Format $_$_BEGIN_PRE colour data rows : <yes/no> $_$_END_PRE TDF line: Border size --------------------- The "Border size" line allows you to specify a border colour for the table. TDF line: HTML attributes ------------------------- The "HTML attributes" line only applies to HTML generation by [AscToHTM] This line has the same effect as that described for the policy line [[goto Default TABLE html attributes]] policy, namely it will define attributes to be added to the <TABLE> tag. Note that this will apply only to the tables which match this definition, whereas that policy will apply to all tables. Where both are defined, the matching TDF line will override any default value. TDF line: HTML cell attributes ------------------------------ The "HTML cell attributes" line only applies to HTML generation by [AscToHTM] This line has the same effect as that described for the policy line [[goto Default TABLE html cell attributes]] policy, namely it will defined attributes to be added to the cell tags <TH> and <TD> in any matching table. Note that this will apply only to the tables which match this definition, whereas that policy will apply to all tables. Where both are defined, the matching TDF line will override any default value. TDF line: Show columns ---------------------- Format is $_$_BEGIN_PRE show columns : <yes_no>,<yes_no>,... $_$_END_PRE where <yes_no> is either "yes" or "no" or blank. If blank it's taken to be "yes" for all columns This line specifies whether or not each column should be included in the output. If your table has been exported in CSV format from a spreadsheet it may contain "work" columns that you don't want shown. This option allows you to specify that. TDF line: HTML fragments ------------------------ Format is $_$_BEGIN_PRE HTML fragments : <header_fragment_name>,<footer_fragment_name> $_$_END_PRE This line identifies [[goto Using HTML fragments, HTML fragments]] to be used as alternatives for the TABLE_HEADER and TABLE_FOOTER HTML fragments. This allows you to define custom HTML fragments to be output either before or after the matching table type. If you don't want to supply both header and footer, then leave the unwanted fragment name blank. NOTE: Despite it's name the TABLE_HEADER fragment doesn't replace the table header, but instead defined HTML to be output before the table. See [[goto Table fragments]] $_$_HELP_CHAPTER 2,"Defining table alarms" $_$_HELP_SUBJECT "Defining a Table Alarm" Defining table alarms ===================== It's possible to define "alarm" conditions on cells in a given column of the table. These alarm conditions test the value in the cell against a "comparison value". Various "types" of comparison are possible. The "comparison value" can either be a fixed value (i.e. the same for all cells in the column), or a value taken from a cell in a different column in the same row. For example you could define an alarm for any value in the column greater than 100, or for any cell whose value exceeded the value in column 2 of the same row. Any cell that matches the alarm criteria is said to be "in alarm". Cells that are in alarm have their output modified in a number of ways, including having a different CSS ID applied to the cell and having extra attributes added to the cell's tag. In this way you are able to customize the appearance and behaviour of any cell that meets your "alarm" conditions. Alarms are defined by [[goto TDF line: alarm, alarm]] lines in the TDF file. To identify that an alarm should be applied to a cell, add the desired alarm names to the *alarms* attribute of the [[goto TDF line: column format]] definition for the relevant column. TDF line: alarm --------------- The "alarm" line specifies how cells in a particular column should be tested for being "in alarm". Cells that are in alarm can have a number of formatting options applied to them, to make them stand out in the HTML. The format is as follows (shown here over two lines for convenience) $_$_BEGIN_PRE alarm : name=<name> type=<type> column_value=<colum_no> value=<value> alarm_color=<html_color> cellatts="<cell_attributes>" CSS_ID=<id> $_$_END_PRE where $_$_BEGIN_TABLE name (mandatory). The unique name given to this column format. This is used to match the name listed for the column in the [[popup TDF line: Column names, column names]] line. type (mandatory). The type of comparison being made between the cell value and comparison value. Options are lt numerically less than le numerically less than or equal to eq numerically equal to ne numerically not equal to ge numerically greater than or equal to gt numerically greater than eqs text strings are the same nes text strings are not the same column_value (optional). Column number to get comparison value from. When specified the value in this column in the current row will be used for the comparison. value (optional). Fixed comparison value. alarm_color (optional). If the cell is configured to display a barchart, then this is the colour the barchart should be when the cell is "in alarm" cellatts (optional). When the cell is in alarm, this identifies any HTML attributes you want added to the alarm cell's tag. CSS_ID (optional). When the cell is in alarm, this identifies any CSS ID to be added to the cell's tag. This will replace any CSS ID that the cell would have acquired from the column definition. This would allow you to define in your style sheet how alarm cells should be formatted. $_$_END_TABLE Note, the "comparison value" will be determined by the values of *column_value* or *value*, only one of which should be supplied. The "in alarm" status is determined by comparing the cell's value with the comparison value according to *type*. The "in alarm" response is configured by the *alarm_color*, *cellatts* and *CSS_ID* attributes. You should specify at least one of these, but are free to specify more than one should you want. $_$_HELP_CHAPTER 2,"Defining table graphs and barcharts" $_$_HELP_SUBJECT "Defining table graphs and barcharts" Defining table graphs and barcharts =================================== Using a [[goto TDF line: Barchart, barchart]] definition, it's possible to get the numbers in a column displayed as a series of bargraphs where each bargraph is proportional to the size of the value in the cell. For example the TDF lines $_$_BEGIN_PRE column format: name=mom barchart=mom_bar alarms=negative barchart : name=mom_bar origin=0 width=200 color=green alarm : name=negative type=le Value=0.0 alarm_color=red $_$_END_PRE Will help turn this table :- $_$_BEGIN_PRE -4 days -3 days -2 days -1 day Today MOM -------- -------- -------- -------- -------- -------- ABC CLOSED Scudde 71.32 73.36 75.11 78.60 79.97 6.07 DEFGH ABPrice Small 72.82 72.18 71.18 72.20 71.90 2.39 IJKLM Sit Trucking 69.96 69.74 66.52 64.58 65.48 4.74 NOPQR ABPrice Emerg 88.95 87.24 85.23 82.00 83.27 -4.52 STUVW Fidelity Cont 68.95 69.27 66.91 67.59 66.67 -1.72 XYZAB IntlFunds AB: 72.15 70.69 71.78 70.44 68.88 -2.41 CDEFG IntlFunds CD: 67.65 67.38 66.42 66.91 65.16 0.05 HIJKL JafSoft Micro 74.10 72.26 70.17 68.72 65.77 -4.97 MNOPQ IntlFunds EF: 70.14 69.80 68.36 68.57 66.82 -0.61 $_$_END_PRE into the following (only visible in the HTML version) $_$_BEGIN_TABLE -4 days -3 days -2 days -1 day Today MOM -------- -------- -------- -------- -------- -------- ABC CLOSED Scudde 71.32 73.36 75.11 78.60 79.97 6.07 DEFGH ABPrice Small 72.82 72.18 71.18 72.20 71.90 2.39 IJKLM Sit Trucking 69.96 69.74 66.52 64.58 65.48 4.74 NOPQR ABPrice Emerg 88.95 87.24 85.23 82.00 83.27 -4.52 STUVW Fidelity Cont 68.95 69.27 66.91 67.59 66.67 -1.72 XYZAB IntlFunds AB: 72.15 70.69 71.78 70.44 68.88 -2.41 CDEFG IntlFunds CD: 67.65 67.38 66.42 66.91 65.16 0.05 HIJKL JafSoft Micro 74.10 72.26 70.17 68.72 65.77 -4.97 MNOPQ IntlFunds EF: 70.14 69.80 68.36 68.57 66.82 -0.61 $_$_END_TABLE In which column 5 has it's data shown as a number of bargraphs, zeroed on 0.0, with negative values changed to alarm states and shown in red. TDF line: Barchart ------------------ The "barchart" line specifies how cells in a particular column should have their data represented by a bargraph. The format is as follows (shown here over two lines for convenience) $_$_BEGIN_PRE barchart : name=<name> min=<value> max=<value> width=<size> origin=<value> bgcolor=<html_colour> color=<html_colour> value_location=<position> null_value=<value> null_display=<option> $_$_END_PRE where $_$_BEGIN_TABLE name (mandatory). The unique name given to this column format. This is used to match the name listed for the column in the [[popup TDF line: Column names, column names]] line. min (optional). The minimum value to show on the bargraph. If omitted the minimum value seen in the column of data will be used. max (optional). The maximum value to show on the bargraph. If omitted the maximum value seen in the column of data will be used. width (optional). The width (in pixels) that the bargraph should be. If omitted, the default value will be 200. origin (optional). A data value taken to be an "origin" for the bargraph. Any values less than this will be shown as a negative bar to the left, any values greater than this will be shown as a positive bar to the right. If omitted, the origin will be set to the bargraph's "min" value so that all bargraphs point to the right. bgcolor (optional). The background colour for the bargraph. This is the colour used for that part of the bargraph that doesn't correspond to the data value. If omitted, the background will be transparent, allowing the background colour of the table cell, table or HTML page to show through. color (optional). The colour for the active part of the bargraph, i.e. that part that represents the data value itself. If omitted the default colour will be "blue". value_location (optional). Determines where the cell value should be placed relative to the barchart. The options are left - value is placed to the left right - value is placed to the right middle or center - value is placed on the bar itself none - value is not displayed The default value is "left", and if an *origin* is specified then this is ignored an "left" is used instead. null_value (optional). Specifies a "null" value, that is a value in the cell that indicates this value is not valid. This can be useful for example when showing instrument readings to indicate am "out of service" value. Cells whose data indicates a null value will not have a bargraph shown, they will instead display the *null_display* value. null_display (optional). Where a cell matches the supplied *null_value*, this specifies the text that should be shown in the cell in place of the bargraph. $_$_END_TABLE $_$_HELP_CHAPTER 2,"Locating data in a table" $_$_HELP_SUBJECT "Locating data in a table" Locating data in a table ======================== It's possible to define [[goto TDF line: Table Data, table data]] lines, which specify a row and column of a table from which to extract a data value. This value is then made available in an appropriate [[POPUP Pre-processor command: VARIABLE, VARIABLE]] tag, allowing the extracted data to be displayed elsewhere in the document. Here's a real-life example:- A customer had data tables exported from an application recording temperatures in a number of device names. The data was exported from an Excel spreadsheet and consisted of a series of rows showing time, and the temperature. What they didn't have was a nice table header, but they could get their application to stick the device name into each row of the table as an extra column. Using a [[goto TDF line: Table Data, table data]] line as follows $_$_BEGIN_PRE table data : name=device_name row=2, col=1 $_$_END_PRE allowed them to define a TABLE_HEADER [[goto using HTML fragments, HTML fragment]] as follows $_$_BEGIN_PRE $_$_DEFINE_HTML_FRAGMENT TABLE_HEADER <H2>Here are the results for device [[OT]]VARIABLE device_name[[CT]]</H2> $_$_END_BLOCK $_$_END_PRE This HTML fragment was then output before the table, but used the "device_name" extracted from the table. Finally to hide the added column all that was needed was a [[goto TDF line: show columns]] line as follows $_$_BEGIN_PRE show columns : no, yes, yes $_$_END_PRE In this particular case the user also made full use of the [[goto Defining table graphs and barcharts, barchart]] feature and [[goto Defining table alarms, alarms]] feature to represent the temperatures graphically, and to show through use of colour those that were out of spec. TDF line: Table Data -------------------- The "table data" line specifies in item of data that may be extracted from a table of known structure. The value extracted can then be accessed in any subsequent [[POPUP Pre-processor command: VARIABLE, VARIABLE]] tag, and in particular in a VARIABLE tag placed into either the TABLE_HEADER or TABLE_FOOTER [[goto Using HTML fragments, HTML fragments]]. The format is as follows: $_$_BEGIN_PRE table data : name=<name> row=<number> col=<number> where $_$_BEGIN_TABLE name (mandatory). The unique name given to this table data item. row (mandatory). The row number of the cell to extract the data from. col (mandatory). The column number of the cell to extract the data from. $_$_END_TABLE $_$_HELP_CHAPTER 2,"An example TDF file" $_$_HELP_SUBJECT "An example TDF file" An example TDF file =================== The example TDF file shown below is meant to work on a text file that contains the following table $_$_BEGIN_PRE -4 days -3 days -2 days -1 day Last MOM -------- -------- -------- -------- -------- -------- ABC CLOSED Scudde 71.32 73.36 75.11 78.60 79.97 6.07 DEFGH ABPrice Small 72.82 72.18 71.18 72.20 71.90 2.39 IJKLM Sit Trucking 69.96 69.74 66.52 64.58 65.48 4.74 NOPQR ABPrice Emerg 88.95 87.24 85.23 82.00 83.27 -4.52 STUVW Fidelity Cont 68.95 69.27 66.91 67.59 66.67 -1.72 XYZAB IntlFunds AB: 72.15 70.69 71.78 70.44 68.88 -2.41 CDEFG IntlFunds CD: 67.65 67.38 66.42 66.91 65.16 0.05 HIJKL JafSoft Micro 74.10 72.26 70.17 68.72 65.77 -4.97 MNOPQ IntlFunds EF: 70.14 69.80 68.36 68.57 66.82 -0.61 $_$_END_PRE First the TDF file identifies the table type as follows $_$_BEGIN_PRE table type : 4day must contain : -4 days -3 days -2 days -1 day Last Mom use format : Format_4day use structure : Struct_4day $_$_END_PRE The [[goto TDF line: Must contain, must contain]] line matches the heading line in the table (since the spacing is ignored). Once this connection is made, the software knows which structure and format to use. The table structure is defined as follows: $_$_BEGIN_PRE table structure : Struct_4day Layout : 8, 6,20,30,40,50,60,70,80 $_$_END_PRE In this the [[goto TDF line: layout, layout]] identifies the table has 8 columns, and where these start and end. The software could have auto-detected this structure, but by supplying a layout the possibility of errors or ambiguities is eliminated. The formatting of this table is fairly complex. The table represents a series of stock price movements, and the user wants to apply an external JavaScript to make this table sortable by clicking on the column headings. For this to work the table has to have a CSS class of "sortable" and to have some JavaScript events defined. The data columns have to have unique CSS IDs so that data in the same column can be identified by the script. The table formatting definition starts as follows $_$_BEGIN_PRE column names: ,,-4days,-3days,-2days,-1day,Last,Mome column format : name=-4days css_id=-4days alarms="green,yellow,red" column format : name=-3days css_id=-3days alarms="green,yellow,red" column format : name=-2days css_id=-2days alarms="green,yellow,red" column format : name=-1day css_id=-1day alarms="green,yellow,red" column format : name=Last css_id=Last alarms="green,yellow,red" column format : name=Mom css_id=Mom alarms="Mom_green,Mom_red" $_$_END_PRE The [[goto TDF line: column names, column names]] names the columns, but only the data columns, as the first two columns don't contain numeric data. The various [[goto TDF line: column format, column format]] defines the formats for each line. In this case this consists of giving each column a different CSS ID, and defining some alarm conditions. All bar the last column get three alarms defined to turn the cell green, yellow or red, whereas the last column gets just two - also green and red, but on different conditions). These alarm names are indicative of what should be done, but are only names in this case. The alarms themselves are defined as follows $_$_BEGIN_PRE alarm : name=red type=lt Value=50.0 alarm_color=red cellatts='bgcolor="ffa7a7"' alarm : name=yellow type=ge Value=50.0 alarm_color=yellow cellatts='bgcolor="ffffa7"' alarm : name=green type=ge Value=65.0 alarm_color=green cellatts='bgcolor="a7ffa7"' alarm : name=Mom_red type=le Value=0.0 alarm_color=red cellatts='bgcolor="ffa7a7"' alarm : name=Mom_green type=gt Value=0.0 alarm_color=green cellatts='bgcolor="a7ffa7"' $_$_END_PRE In this example each [[goto TDF line: alarm, alarm]] is triggered by comparing the numerical value to some limit, and then adding cell attributes and alarm colours when the alarm triggers. Finally the line $_$_BEGIN_PRE HTML attributes : class="sortable" onMouseover="changeto(event, 'white')" onMouseout="changeback(event, '')" $_$_END_PRE specifies the necessary HTML attributes to add to the <TABLE> tag for the external sorting JavaScript to locate and work on the table. All put together the TDF file looks like this $_$_LINERULE $_$_BEGIN_PRE ! ! Stocks and shares table ! !- define table type "4day" ! table type : 4day must contain : -4 days -3 days -2 days -1 day Last Mom use format : Format_4day use structure : Struct_4day ! !- structure of table type "4day" ! table structure : Struct_4day Layout : 8, 6,20,30,40,50,60,70,80 ! !- formatting of table type "4day" ! table format : Format_4day ! !- only care about the numerical columns. No need to name the others column names: ,,-4days,-3days,-2days,-1day,Last,Mome ! each column gets a CSS_ID and several alarm conditions applied column format : name=-4days css_id=-4days alarms="green,yellow,red" column format : name=-3days css_id=-3days alarms="green,yellow,red" column format : name=-2days css_id=-2days alarms="green,yellow,red" column format : name=-1day css_id=-1day alarms="green,yellow,red" column format : name=Last css_id=Last alarms="green,yellow,red" column format : name=Mom css_id=Mom alarms="Mom_green,Mom_red" ! ! alarm conditions. ! Red turns cell red if value is very low ! yellow turns cell yellow if value is low ! green turns cell green is value is above acceptable minimum ! alarm : name=red type=lt Value=50.0 alarm_color=red cellatts='bgcolor="ffa7a7"' alarm : name=yellow type=ge Value=50.0 alarm_color=yellow cellatts='bgcolor="ffffa7"' alarm : name=green type=ge Value=65.0 alarm_color=green cellatts='bgcolor="a7ffa7"' alarm : name=Mom_red type=le Value=0.0 alarm_color=red cellatts='bgcolor="ffa7a7"' alarm : name=Mom_green type=gt Value=0.0 alarm_color=green cellatts='bgcolor="a7ffa7"' ! HTML attributes added to <TABLE> tag. In this case the table is marked ! as sortable and gets a couple of mouse events. An external JavaScript module ! contains code to sort columns by clicking on the header. That script requires ! the table to be labelled as "sortable" and for sortable columns to all have the ! same CSS ID on the cells (achieved via the "column format" definitions above. ! HTML attributes : class="sortable" onMouseover="changeto(event, 'white')" onMouseout="changeback(event, '')" $_$_END_PRE $_$_BEGIN_IGNORE ! ! NOTE: SDF's were added for AscToRTF and RTF conversion. They are not (yet) ! supported by HTML production in AscToHTM ! !------ section starts here ------------------ ! ! $_$_HELP_CHAPTER 1,"Using Style Definition Files to improve table handling" ! $_$_HELP_SUBJECT "Overview of Style Definition Files (SDF)" ! Using Style Definition Files (SDF) ! ********************************** ! $_$_HELP_TOPIC_ID HIDD_SDF_FILE ! As of version 2.0, AscToHTM allows more control over the fonts used to ! add style to the document text. ! ! Several users of AscToHTM are feeding output of typesetting software into ! AscToHTM as text input. In many cases these users commented that they had ! detailed knowledge of how the HTML should be formatted, but were having to ! discard that information in the text passed to AscToHTM, with a resulting ! loss of details. ! ! Changes have been made in version 2.0 to allow better integration between ! the original document and the HTML created by AscToHTM. ! ! These changes allow you to define various font styles in a _Style Definition File_ ! and to then invoke these files by placing FO (font) tags into the source document. ! ! You can choose to have a FO tag apply from that point onwards, until the next ! paragraph/heading/table or just until the end of the current input line. In any ! case a new FO tag will override the previous setting. ! ! $_$_SECTION MAKINGHTML ! *Contents of this section* ! $_$_CONTENTS_LIST 2,,2 ! $_$_SECTION MAKINGRTF ! See also ! - [[goto Loading the Style Definition File (SDF)]] ! - [[goto Pre-processor command: FO]] ! - [[goto Scope for font tags]] ! $_$_SECTION ALL ! ! Loading the Style Definition File (SDF) ! ======================================= ! All the style definition information should be placed in a "Style Definition File" ! (SDF). By convention this file should have a ".inc" extension, but this ! isn't a requirement. ! ! To have the file loaded, you will need to set a policy line in your policy ! file of the form ! ! $_$_BEGIN_PRE ! [config files] ! Style Definitions file : Style_definitions.inc ! $_$_END_PRE ! ! This will normally appear in the "[config files]" section of your policy ! file, but again this isn't strictly necessary. ! ! Once this option appears in your policy file, the style definition file ! will be loaded before the conversion process starts. ! ! You can choose the Style Definition File by selecting the menu option ! ! _Conversion Options -> Configuration Files -> Style Definition File_ ! ! This will take you to a dialog for [[goto Selecting the Style Definition File]] ! ! ! An Example Style Definition File ! ================================ ! At present only font declarations can be included in a Style Definition File. ! Below is a simple example that simply defines the three font styles Fixed, ! Heading and Body. ! ! $_$_BEGIN_PRE ! define font : Fixed, Courier New, regular, 10 ! define font : Heading, Arial, regular, 10 ! define font : Body, Times New Roman, regular, 10 ! $_$_END_PRE ! ! See [[goto SDF line : define font]] ! ! SDF Line : define font ! ---------------------- ! The *define font* line defines a font that can be referenced by a FO tag ! in the source document. ! ! Syntax: ! ! $_$_BEGIN_PRE ! define font : <font_ID>, <Font_specification> ! $_$_END_PRE ! ! Where, ! ! $_$_BEGIN_TABLE ! font_ID This is a unique name given to the font specification ! as it will be used in the FO tag ! ! font_specification This is the specification of the font to be used ! whenever an FO tag references this font_ID. ! $_$_END_TABLE ! ! The *font_specification* consists of a comma delimited list of the font ! name, the weight and the font size. This is the same format as described ! in the [[goto The Font Selection Dialog]] ! ! Example: ! ! define font : Fixed, Courier, bold, 12 ! ! This defines a *font_ID* called "fixed". This equates to a Courier font ! which is set bold and to be 12pt. If in my source text I add the tag ! ! [[OT]]FO fixed,,14[[CT]] ! ! The the following text will be Courier, Bold and 14pt (because the FO tag ! has overridden the specified font size). ! ! See also [[goto Pre-processor command: FO]] ! $_$_END_IGNORE $_$_HELP_CHAPTER 1,"Using Text commands to modify the source text" $_$_HELP_SUBJECT "Overview of Text Command File" Using Text Command Files ************************ $_$_HELP_TOPIC_ID HIDD_TEXTSUBS_FILE _(New in version 5.0)_ As of version 5.0, AscToHTM allows the use of "Text Commands". These are commands that allow you to modify the text before it is converted, or to label certain lines as being of a particular type. The commands should be placed in an external "Text Command File". This file can be chosen from _Conversion Options -> Config File Locations_ menu option. $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION MAKINGRTF Various commands are available as follows $_$_BEGIN_DELIMITED_TABLE [[goto Text Command : ignore_line,ignore_line]] Identifies lines to be discarded from the input [[goto Text Command : remove_text,remove_text]] Identifies text to be removed from the input [[goto Text Command : replace_text,replace_text]] Identifies text to be replaced by other text [[goto Text Command : treat_line,treat_line]] Identifies how a line should be treated [[goto Text Command : meta_tag_line,meta_tag_line]] Identifies lines to be converted into META tags in HTML $_$_END_DELIMITED_TABLE $_$_SECTION ALL $_$_HELP_CHAPTER 2,"Text Commands" Text Commands available ======================= $_$_SECTION MAKINGRTFHELP Various commands are available as follows $_$_BEGIN_DELIMITED_TABLE [[goto Text Command : ignore_line,ignore_line]] Identifies lines to be discarded from the input [[goto Text Command : remove_text,remove_text]] Identifies text to be removed from the input [[goto Text Command : replace_text,replace_text]] Identifies text to be replaced by other text [[goto Text Command : treat_line,treat_line]] Identifies how a line should be treated [[goto Text Command : meta_tag_line,meta_tag_line]] Identifies lines to be converted into META tags in HTML $_$_END_DELIMITED_TABLE $_$_SECTION ALL Text Command : ignore_line -------------------------- The *ignore_line* command identifies lines that should be ignored in the input. Syntax: $_$_BEGIN_PRE ignore_line <line_selection> $_$_END_PRE Any line matching the specified [[goto line_selection]] criteria will be ignored in the output. This can be a useful way of ignoring page markers in an input file, as these don't always transfer well under the conversion. Text Command : remove_text -------------------------- The *remove_text* command identifies text that should be removed from the input. Syntax: $_$_BEGIN_PRE remove_text <match_type> "match string" $_$_END_PRE Any line containing text that matches the specified [[goto match_type]] for the supplied "match string" will have the matching text removed. Text Command : replace_text --------------------------- The *remove_text* command identifies text that should be removed from the input. Syntax: $_$_BEGIN_PRE replace_text <match_type> "match string" by_string "new string" or replace_text <match_type> "match string" by_character "<char>" $_$_END_PRE Any line containing text that matches the specified [[goto match_type]] for the supplied "match string" will have the matching text replaced. If the replacement is specified as $_$_BEGIN_PRE by_string "new string" $_$_END_PRE then the text is replaced by the new string. If the replacement is specified as $_$_BEGIN_PRE by_character "<char>" $_$_END_PRE then the string is replaced by a string of equal length consisting of this single character repeated. This can be useful for example to replace change bar characters by spaces in a document where the change bars have confused the program, or to replace other characters inside a table that are confusing the detection of the table's true layout. Text Command : treat_line ------------------------- The *treat_line* command allows you to specify how a line should be regarded during the analysis of the file. Syntax: $_$_BEGIN_PRE treat_line <line_selection> <as_line_type> $_$_END_PRE With this command any line that matches the specified [[goto line_selection]] criteria will be regarded as the specified [[goto as_line_type]]. For example the command $_$_BEGIN_PRE treat_line starting_with string "news" as_header_1 $_$_END_PRE specifies that any line in which the string "News" is found at the start should be considered as a level 1 heading. Text Command : meta_tag_line ---------------------------- The *meta_tag_line* is meant solely for HTML conversion. It identifies lines that should be converted into HTML META tags. Syntax: $_$_BEGIN_PRE meta_tag_line "tag name" <line_selection> [remove_match_text] $_$_END_PRE This command specifies that any line matching the [[goto line_selection]] criteria should be used to create a META tag called "tag name". The value of this META tag will be the line itself. If the *remove_match_text* argument is supplied, the match text itself will be removed from the value. For example the command $_$_BEGIN_PRE meta_tag_line "author" starting_with string "author: " remove_match_text $_$_END_PRE Will match the line $_$_BEGIN_PRE Author: Dr John A Fotheringham $_$_END_PRE will remove the "author: " from this line, and create a META tag as follows $_$_BEGIN_PRE <META NAME="author" CONTENT="Dr John A Fotheringham"> $_$_END_PRE This can be useful when processing text files created by other systems that add "tagging" and catalogue information at the top. Note: You could combine this command with a matching [[goto Text Command : ignore_line,ignore_line]] command to ensure that the line became a META tag, but wasn't included in the conversion output itself. $_$_HELP_CHAPTER 2,"Text Command Line syntax elements" Text Command line elements ========================== $_$_SECTION MAKINGRTFHELP The following Text command line elements are used by several commands $_$_BEGIN_DELIMITED_TABLE [[goto line_selection]] Complete specification of how to match a line [[goto line_match]] Location of text within line [[goto match_type]] Type of text matching required [[goto replace_type]] Type of text replacement wanted [[goto as_line_type]] How to treat a "treat_line" line $_$_END_DELIMITED_TABLE $_$_SECTION ALL line_selection -------------- The *line_selection* element is actually a combination of a number of simpler elements as follows Syntax: $_$_BEGIN_PRE <line_match> <match_type> "match string" $_$_END_PRE That is the *line_selection* consists of a [[goto line_match]], a [[goto match_type]], and then the actual "match string" to be matched. All three elements must be present in order for the *line_selection* to be valid. The following are all valid examples $_$_BEGIN_PRE starting_with string "Chapter" starting_with exact_phrase "Author : " containing phrase "click here" containing string "http://" $_$_END_PRE line_match ---------- The *line_match* element specifies where on the input line the specified text should be located. The options are $_$_BEGIN_DELIMITED_TABLE starting_with Text should be at start of line (ignoring any white space) containing Text can be anywhere on the input line $_$_END_DELIMITED_TABLE Care should be used when using the *containing* option, as false matches are more likely to occur. match_type ---------- The *match_type* element specifies how any supplied match string should be matched. The options are $_$_BEGIN_TABLE string This specifies that a string should be matched. This is, in fact, the most general of match types and is the one that would normally be used. This match type is case-insensitive. exact_string Same as "string", but case-sensitive. phrase A "phrase" is a string that is surrounded by white space and/or punctuation on either side (see below). This match type is case-insensitive exact_phrase Same as "phrase", but case-sensitive. wildcard Not yet supported (*) $_$_END_TABLE The *match_type* _phrase_ is a special case. This is a _string_ that is surrounded by white space or punctuation on either side. So whereas the _string_ "the" would match "then", the _phrase_ "the" wouldn't because the "n" in "then" is not a white space character. The start and end of a line count as white space, and any leading or trailing punctuation is allowed. _Phase_ is therefore a more precise match - even for single words - than _string_. Consider the following example, concentrating on the letters "ten" in the word "tense" $_$_BEGIN_PRE This is a tense situation.... $_$_END_PRE The following would apply $_$_BEGIN_TABLE $_$_TABLE_LAYOUT 2,32,90 match_type Matches? ------------------------------------------------------- string "ten" Yes. The "ten" matches the first three characters in "tense" in the middle extact_string "Ten" No. The "t" in "tense" is lower case, so the match fails phrase "ten" No. "ten" is not surrounded by white space or punctuation because it is followed by "se" exact_phrase "tense situation" Yes. The case matches, and there is a space before and punctuation (the "...") afterwards. $_$_END_TABLE replace_type ------------ The *replace_type* element is used in the [[goto Text Command : replace_text,replace_text]] command to specify what type of text replacement should be executed. The element should be immediately followed by the replacement text in quotes. There are two options:- $_$_BEGIN_TABLE by_string The matched text should simply be replaced by the replacement text. by_character The matched text should be replaced by an equal length string composed solely of the single character in the replacement text. $_$_END_TABLE The *by_character* option allows a string to be "blanked out" by the character of your choice, but without altering the line length or spacing etc. This can be useful, for example to replace all DOS line drawing characters by blanks in table, so as to let the software make a better stab at detecting the table layout. as_line_type ------------ The *as_line_type* element is used by the [[goto Text command : treat_line,treat_line]] command to specify how the matching line should be treated. The *as_line_type* assigns to the matching line a type that would otherwise have to be automatically be detected by the program. It can therefore help the analysis if you can tell the program how such lines should be treated. The options are $_$_BEGIN_TABLE as_heading_<n> Where <n> is "1","2"..."6". The matched line is treated as a heading of level <n> as_bullet The matched line is treated as being an unordered list item (bullet) as_alpha_bullet The matched line is treated as being an item on an alphabetic list. as_capalpha_bullet The matched line is treated as being an item on an UPPER CASE alphabetic list. as_roman_bullet The matched line is treated as being an item on an roman numeral list. as_caproman_bullet The matched line is treated as being an item on an UPPER CASE roman numeral list. as_quoted The matched line is treated as being "quoted text" such as lines in emails that start with a ">" are. as_new_page The matched line is treated as being the start of a new page. as_number_bullet The matched line is treated as being an item on a numbered list. $_$_END_TABLE For example the command $_$_BEGIN_PRE treat_line starting_with string ":" as_quoted $_$_END_PRE can be used to ensure that lines that start with ":" are treated as if they are "quoted text" such as one finds inside emails. See [[goto quoted line detection]] $_$_HELP_CHAPTER 2,"Text Command tags" $_$_HELP_SUBJECT "Text Command tags" Text Command tags ================= To add further flexibility to your text command, the DATA tag has been added. This tags allows your replacement strings to have variable text - although only to a limited extent The DATA tag ------------ Syntax: $_$_BEGIN_PRE DATA <type_of_data> $_$_END_PRE where <type_of_data> can be $_$_BEGIN_TABLE VERSION Program name and version TITLE Document title AUTHOR Document Author (if known) IN_FILENAME Input filename OUT_FILENAME Output filename IN_FILESIZE Input file size OUT_FILESIZE Output file size (approximate if known) IN_FILEDATE Input file's date TIMESTAMP Current time $_$_END_TABLE Text commands are executed against the input text, and can be used to substitute data on input before conversion. For example the command $_$_BEGIN_PRE replace_text string "Created by [author]" by_string "created by [[OT]]DATA AUTHOR[[CT]]</TD>" $_$_END_PRE Would allow a standard line to have the author's name embedded in it. Note, for this to work the DATA tag has to know the value of Author at execution time, so you would most likely need to set this is the policy file. For this reason some of the DATA statements will be less useful than others (for example OUT_FILESIZE won't work in AscToHTM) $_$_HELP_CHAPTER 2,"An example Text Command File" $_$_HELP_SUBJECT "Text Command file" An example Text Command File ============================ Below is an example Text Command file: $_$_BEGIN_PRE treat_line starting_with exact_string "new page" as_new_page treat_line starting_with string "head_1" as heading_1 treat_line starting_with string "head_2" as heading_2 treat_line starting_with string "head_3" as heading_3 remove_text exact_string "head_1" remove_text exact_string "head_2" remove_text exact_string "head_3" ignore_line containing exact_string "PAGE" $_$_END_PRE In this example lines starting with "new_page" are treated as page breaks. Lines starting with "head_1" etc are treated as headings, and then the text "head_1" is removed. In this way you could label your heading lines without the labelling appearing in the output. Finally any line containing the exact_string "PAGE" is discarded. Note that by using "exact_string" you ensure that the case is matched so "PAGE" matches but "page" does not. $_$_HELP_CHAPTER 1,Working with Unicode $_$_HELP_SUBJECT "Working with Unicode" Working with Unicode ******************** $_$_HELP_TOPIC_ID ID_UNICODE _(New in version 5.0)_ AscToHTM was not originally designed with Unicode in mind, and as a result support for Unicode text has been gradually added over time, with the result that earlier versions of AscToHTM may not support all the features described in this manual. If in doubt, please contact JafSoft for details. $_$_SECTION MAKINGRTFHELP - [[goto What is Unicode?]] - [[goto Unicode Byte Order Marks (BOMs)]] - [[goto Auto-detecting Unicode input]] - [[goto Creating Unicode output]] - [[goto Controlling Unicode handling through use of policies]] $_$_SECTION_ALL What is Unicode? ================ Traditional single-byte character sets interpret the 8-bit character values (128-255) as special characters. So on a Russian machine this would be interpreted as Cyrillic, but on a different machine this could be read (wrongly) as Arabic (and vice versa). On most English-based PCs, the 8-bit characters are used for accented character used in certain European languages, so a Russian text would appear to have lots accented 'i's, 'e's and 'a's. Unicode is a way of implementing text that supports multiple types of character sets at the same time so that - for example - it is possible to display Chinese and Cyrillic on the same page unambiguously. It does this by allocating each character in each language a unique code value, so that codes used for Cyrillic characters no longer overlap and conflict with those assigned to Arabic. However, these code values are in most cases larger than can be represented in a single byte. As a result a way has to be chosen to represent each character by one or more bytes. The following Unicode representations are commonly used *UTF-8* Each character is represented by 1, 2 or 3 bytes, depending on the which range the Unicode code value falls into. This has the advantage that all ASCII characters are a single byte, so for example all the HTML tags in a document are represented by a single byte each. This also means there are no null bytes contained in the text, which can make programming software to work with this text easier. *UTF-16* Each character is represented by a 2-byte pair (future characters may require 2 such pairs). The 2-byte pair is just the numerical representation of the Unicode value of each character. This makes the files easier to interpret, but also means that the byte order depends on how the machine stores its bytes - i.e. is the machine big-endian or little-endian. Because ASCII characters have a Unicode value less than 255 the ASCII characters map onto a byte pairs in which one of the bytes is null. Because each character requires two bytes, a single byte wrongly inserted into a UTF-16 stream will render all text that follows is as gibberish. Unicode Byte Order Marks (BOMs) =============================== Files that contain Unicode identify themselves by inserting a "Byte Order Mark" (BOM) at the top of the file. This is a two-byte marker for UTF-16 files and a three-byte marker for UTF-8 files. Modern applications will test for this byte marker and if present will then know how to interpret the contents of the file. For example Notepad as supplied with Windows XP can do this, whereas Notepad as supplied with Windows 98 could not. In UTF-16 each character is represented by two bytes, and computers can store a two-byte value in different ways (known as "big-endian" and "little-endian"). Each operating system uses one method or another and it isn't usually an issue, but when Unicode files get passed from one machine to another, this becomes important. The BOM allows the two forms of UTF-16 (known as "UTF-16BE" and "UTF-16LE") to be distinguished. Auto-detecting Unicode input ============================ The software has some ability to auto-detect Unicode text, and will generally do so under the following circumstances - a 3-byte Byte Order Mark (BOM) is detected at the top of a UTF-8 input file - a 2-byte Byte Order Mark (BOM) is detected at the top of a UTF-16 input file - the input HTML contains an HTML entity that maps onto a Unicode code value which can't be converted into an ANSI or ASCII equivalent, In this case although the input HTML may not have been encoded as Unicode, the output will need to be in order to correctly display the Unicode character. Creating Unicode output ======================= The software will create Unicode output whenever it detects that the input files were Unicode, or wherever Unicode characters have been detected in the HTML entities of the original. At present all Unicode output files will be UTF-8. Controlling Unicode handling through use of policies ==================================================== The following policies can be used to control the handling of Unicode during the conversion :- - [[popup Character encoding]]. Where the input file is ASCII, it could still contain Unicode-encoded data. You can use this policy to set the HTML character encoding to be a suitable value $_$_HELP_CHAPTER 1,"Diagnosing conversion errors" $_$_HELP_SUBJECT "Overview of handling errors" Diagnosing conversion errors **************************** $_$_HELP_TOPIC_ID ID_FAULTS If you get any unexpected conversion problems:_ - Try generating some diagnostic files (see output policies... file generation). This will generate a .lis file which will show how AscToHTM has analysed each line in your source file (there is a key at the foot of the .lis file). - Try executing a "simple" conversion. - Review the analysis policies, checking for anything that doesn't look right. - Read through the [[goto Documentation available]] as this is expected to give more detail If you've registered the software, you can contact the author for advice. $_$_HELP_CHAPTER 1,"Change History" Change History ************** $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 3,,2 $_$_SECTION MAKINGRTF Here are the versions of AscToHTM that have been released to date. - [[goto Version 5.0 (November 2004)]] - [[goto Version 4.1 (August 2001)]] - [[goto Version 4.0 (May 2001)]] - [[goto Version 3.3 (June 2000)]] - [[goto Version 3.2 (October 1999)]] - [[goto Version 3.0 (August 1998)]] - [[goto Version 2.3 (April 1998)]] - [[goto Version 2.2 (Feb 1998)]] - [[goto Version 2.1 (never officially released)]] - [[goto Version 2.0 (October 1997)]] - [[goto Version 1.1 (August 1997)]] - [[goto Version 1.05 (July 1997)]] - [[goto Version 1.04 (July 1997)]] - [[goto Version 1.01 (April 1997)]] $_$_SECTION ALL $_$_HELP_CHAPTER 2,"Version 5.0 (November 2004)" Version 5.0 (November 2004) =========================== Version 5.0 is the first major update to AscToHTM in 3 years. As such it contains a large number of enhancements and changes from the previous version 4.1. - [[goto New functions in version 5.0]]. Several major new features are added in this release to support more advanced conversions. - [[goto New policies in version 5.0]]. A large number of new policy options have been added in this version, and other previously not accessible via the user interface now are, and are fully documented for the first time - [[goto API version now available]]. An API interface is now available under separate license to developers wishing to add conversion abilities to their own software. - [[goto Other changes in version 5.0]] $_$_HELP_CHAPTER 3,"New functions" New functions in version 5.0 ---------------------------- Several major new features are added in version 5.0. - [[goto Ability to fully control table generation]]. This includes the ability to define alarm states for individual cells in a table, and the ability to represent the data in a column as a series of bar graphs. - [[goto Ability to "tag" your own tables for greater accuracy]]. Ideal for interfacing to software generating the text files which knows the table structure, as this bypasses all of AscToHTM's analysis (world-beating though that is!) - [[goto "Input text manipulation and labelling using ""Text commands"""]]. Perform text manipulation on the input text to label lines as headings or achieve other affects. - [[goto Support for non-ASCII character types and character encodings]] - [[goto Support for Definition Blocks]]. Define standard block of text to place into your document at key points (e.g. page footers, disclaimers etc). - [[goto Support for comma-delimited and tab-delimited tables]] Ability to fully control table generation ......................................... To aid in processing tables, the program now allows you to identify various table structures by specifying various match conditions. Each time the software encounters a candidate table, it tests this against the match conditions to see if the "table" is of a known type. For each table you can specify its structure, and various formatting rules to be used in its conversion. These structure and formatting definitions can be shared between multiple table types for your convenience. All the table type, structures and formatting rules should be placed in an external text file, known as a *Table Definition File* (or TDF for short). A new policy allows you to identify which Table Definition File is to be used, and you can select this from the new _Config File Location_ menu. When a table matches a known table definition it is possible to:- - specify the layout of the table to ensure it is correctly converted into columns - customise the <TABLE> tag, and each cell in specified columns to have the CSS ID and HTML attributes of your choice added. This facilitates the fine tuning of appearance and the use of JavaScript on an almost cell-by-cell basis. - define "alarm" conditions for cells in a specified column, and have cells that are in alarm change colour, or to be placed in a different CSS class, so that they can be marked out through your stylesheet definitions. See [[goto Defining table alarms]] - define a "barchart" for cells in a given column, so that each cell's value is displayed as a bar sized to represent the value of the cell. See [[goto Defining table graphs and barcharts]] - selectively extract data form the table for use elsewhere in the HTML. See [[goto Locating data in a table]] For full details see [[goto Using Table Definition Files (TDF)]]. Ability to "tag" your own tables for greater accuracy ..................................................... The program now supports [[goto Tagged Table commands]]. These commands allow you to completely markup a table, specifying the column details, the row details and the contents of each table cell. This approach can be used by those who want complete control over how their tables are constructed, or who are generating text files from a source which knows the table layout and can explicitly state it. By using the tagged approach, you avoid the prospect of the program making mistakes when analysing the layout of the table. As an example of using tagged table commands, the following sequence in the source file $_$_BEGIN_PRE $_$_BEGIN_USER_TABLE C,1 in $_$_COLUMN_DETAILS 1,,,L, 2 in $_$_COLUMN_DETAILS 2,,,C, 1 ins $_$_TABLE_BORDER 1 $_$_NEW_ROW HEAD $_$_NEW_CELL Substance (units) $_$_NEW_CELL Year Sampled $_$_NEW_ROW DATA $_$_NEW_CELL Alpha emitters (pCi/L) $_$_NEW_CELL 1999 $_$_NEW_ROW DATA $_$_NEW_CELL Asbestos (MFL) $_$_NEW_CELL 1993 $_$_END_TABLE $_$_END_PRE becomes $_$_BEGIN_USER_TABLE C,1 in $_$_COLUMN_DETAILS 1,,,L, 2 in $_$_COLUMN_DETAILS 2,,,C, 1 ins $_$_TABLE_BORDER 1 $_$_NEW_ROW HEAD $_$_NEW_CELL Substance (units) $_$_NEW_CELL Year Sampled $_$_NEW_ROW DATA $_$_NEW_CELL Alpha emitters (pCi/L) $_$_NEW_CELL 1999 $_$_NEW_ROW DATA $_$_NEW_CELL Asbestos (MFL) $_$_NEW_CELL 1993 $_$_END_TABLE Input text manipulation and labelling using "Text commands" ........................................................... The program now allows you to apply "text commands" to the input text, before it is converted. There are several commands possible, which allow you to identify lines in the input text that should be ignored, and text in the input file that should be removed or replaced. You can also use commands to tell the software how to interpret certain types of line. For example to say which lines are headings, and which should be regarded as bullet points etc. The Text Commands to be used should be placed in an external *Text Command File*. A new policy allows you to identify which Text Command File is to be used, and you can select this from the new _Config File Location_ menu. For full details see [[goto Using Text Command Files]] Support for non-ASCII character types and character encodings ............................................................. _Non-latin and Unicode character sets_ Some support has been added for non-latin character sets. The character set names are based on those used in HTML charsets. Support has been added for auto-detecting the character set used, but this is far from foolproof. If you are using non-latin character sets you may need to set the character set manually. It is not possible at present to support multiple character sets in one document (unless you are using Unicode) To support this feature the following policies have been added - the [[goto character encoding]] policy to allow the character encoding of a document to be set. The software has limited ability to detect Japanese ("x-sjis") and Cyrillic ("koi-8") text, but in some cases this will need to be set. - The auto-detect of character sets can be switched off by using the [[goto Look for character encodings]] policy. You might want to do this if the software wrongly suspects your document is a non-latin character set. See [[goto Working with Unicode]]. _other special characters_ - Added support for parsing files with some Mime-encoded quotable strings in them. The new policy [[goto Input file contains MIME encoding]] can be found under _Analysis->File structure_. At present there is some (very limited) auto-detect for this feature. - Added support for documents with change bars. By default change bars are stripped out, and the changed text coloured red this behaviour may be changed in later versions. Added the new policy [[goto Input file has change bars]] which can be found under _Analysis->File Structure_. - Added support for converting DOS characters. The new policy [[goto Input file contains DOS characters]] can be found under _Analysis->File Structure_. There is a limited auto-detect of DOS characters when diagrams are present. - Added [[goto Input file contains PCL codes]] policy. Again there is a limited ability to detect these codes. A few of the PCL codes are interpreted. Most are just discarded. - Improved handling of VT escape characters. These are either removed from the output or converted to "line" characters Support for Definition Blocks ............................. [[goto Using text definition blocks, Definition blocks]] allow you to define blocks of text that you may then insert at any point in the text (e.g. to give an "end of page" effect). You can also "define variables" whose value is then inserted wherever a VARIABLE tag is used. This feature, though supported by the core analysis engine, is expected to be used more by the users of the [AscToHTM] converter. The pre-processor commands involved are: - [[goto Pre-processor command: DEFINE_BLOCK, DEFINE_BLOCK]] - [[goto Pre-processor command: DEFINE_VARIABLE, DEFINE_VARIABLE]] - [[goto Pre-processor command: EMBED_BLOCK, EMBED_BLOCK]] - [[goto Pre-processor command: INSERT_BLOCK, INSERT_BLOCK]] - [[goto Pre-processor command: VARIABLE, VARIABLE]] - [[goto Pre-processor command: SAVE/RESTORE_CONTEXT, SAVE/RESTORE_CONTEXT]] Support for comma-delimited and tab-delimited tables .................................................... Pre-processor commands have been added to allow you to mark up a section of comma-delimited or tab-delimited data you want turning into a table. The new pre-processor directives are the [[goto Pre-processor command: COMMA_DELIMITED_TABLE,COMMA_DELIMITED)TABLE]] command and the [[goto Pre-processor command: DELIMITED_TABLE,DELIMITED_TABLE]] command - New [[goto command line qualifiers: /COMMA,/COMMA]] and [[goto command line qualifiers: /TABBED,/TABBED]]command line qualifiers that allow comma delimited and tab delimited files be converted into tables. - New [[goto command line qualifiers: /TABLE,/TABLE]] command line qualifier that allows the input file to be treated as a single plain text table In addition to this, the software now has the ability to automatically detect tab-delimited data tables. $_$_HELP_CHAPTER 3,"New policies" New policies in version 5.0 --------------------------- A large number of new policy options have been added in version 5.0, and several that weren't previously accessible via the user interface can now be accessed. $_$_SECTION_MAKINGRTFHELP - [[goto New added HTML policies]] - [[goto New configuration file policies]] - [[goto New contents list policies]] - [[goto "New file, page, paragraph and line structure policies"]] - [[goto New file splitting policies]] - [[goto New font policies]] - [[goto New heading policies]] - [[goto New hyperlink policies]] - [[goto New table analysis policies]] - [[goto New table generation policies]] - [[goto Other new policies]] $_$_SECTION_ALL New added HTML policies ....................... The "added HTML" section acquires a number of new policies that allow you to create appropriate META tags in the HTML <HEAD> sections - Added [[goto Author URL]] policy to allow the author URL for this document to be defined. - Added [[goto Bookmark URL]] policy to allow the bookmark URL for this document to be defined. - Added [[goto Copyright URL]] policy to allow the URL of any copyright notice to be defined. - Added [[goto Shortcut Icon URL]] policy to allow the URL of any shortcut icon to be defined. New general analysis policies ............................. - Added [[goto Hanging paragraph position(s)]] policy. This allows the indentation positions used for follow-on paragraphs in definitions to be specifies. New configuration file policies ............................... In version 5.0 there is a new menu option under Conversion options pointing to *Configuration Files*, that is files loaded in addition to the policy file to control different aspects of the conversion. The choices made on that menu are also saved as option in your policy file. - The [[goto Text command file]] allows you to define text manipulations that should be done to the source text as it is read during the conversion. This allows you to ignore certain lines, mark them out as headings, or perform substitutions on the input text. See [[goto Using Text Command Files]]. - The [[goto Definitions file]] allows you to define table definitions. Tables that match the supplied definitions can have their layout and format tightly controlled. See [[goto Using Table Definition Files (TDF)]] - The [[goto Fragments File]] allows you to define snippets of HTML that will be copied into the output at key points. See [[goto Using HTML fragments]] - The [[goto Link Dictionary File]] allows you to define text that should be converted into hyperlinks. See [[goto Using link dictionary files]] New contents list policies .......................... - Added policy [[goto Add mail headers to contents list]] to control whether or not email headers which are turned into headings should be included in the contents list New file, page, paragraph and line structure policies ..................................................... _File structure_ - Added [[goto Lines to ignore at start of file]] and [[goto Lines to ignore at end of file]] policies to allow lines at the start and end of the source file to be discarded. This can be useful if you source text is coming from a third party source that adds extra, unwanted, lines. - Added auto-detect of double spaced files (files where every second line is blank). This will set the [[goto Input file is double spaced]] policy whenever double-spaced text is detected (unless the policy has already been set). - Added [[goto Input file contains UNICODE characters]] policy. When enabled the program will create a UTF-8 output file. _Page structure_ - Added [[goto Pre-processor command: PAGE, PAGE]] command. This marks a page boundary. In the HTML this creates a <HR> page separator _Page markers_ - Added [[goto Input file has page markers]] and [[goto Page marker size (in lines)]] policies. These allow you to identify that the file has page markers containing form feeds and that the first so many lines after the form feed should be discarded. _Paragraph structure_ - Added [[GOTO Preserve new paragraph offset]] policy. In documents where a first line offset is detected at the start of each paragraph you can elect to have this preserved in the output. _Line structure_ Added options to allow more control over how the original document's file structure should be preserved - Added [[goto Treat each line as a paragraph]] policy. If this option is selected, every line in the source file is treated as a paragraph. This may be suitable if the file has been authored using an editor that wraps the lines (i.e. doesn't put in hard breaks) and which doesn't add blank lines between paragraphs. - Added [[goto Preserve line structure]] policy. If this option is selected a line break is added to every line, thereby preserving the line structure of the original. _File generation_ - Added [[goto Break up long HTML lines]] policy. If this option is selected, the output HTML will be broken into smaller lines to make it more readable. New file splitting policies ........................... Added policies to allow greater control over splitting large files into a set of smaller linked HTML pages - Added [[goto Number of words to include in filename]] policy to allow some control over file naming when deriving filenames from underlined headings. - Added [[goto Use numbered sequence in file names]] policy to allow generated files to be numbered, rather than named. - Added [[goto Split at page markers]] policy to allow filers to be split at page markers New font policies ................. Added policies to allow different fonts to be applied to different types of text as follows Normal text [[goto Default font]] Headings [[goto Heading Font]] Text in tables [[goto Table font]] Table of contents [[goto Table of contents Font]] Fixed-pitch text [[goto Fixed font]] New heading policies .................... There are two new heading types that can be supported :- - Added support for embedded headings with the [[goto Expect embedded headings]] policy (see [[goto Embedded heading detection]]). These are "headings" that are embedded as the first sentence in a paragraph. - Added support for headings that start with particular words or phrases via the [[goto Heading key phrases]] policy (see [[goto Key phrase headings]] for more on this). Also added :- - Added the policy [[goto Check indentation for consistency]] so that it could be disabled in documents where headings were centred (and thus all at different indentations) - Added support for headings that span up to 3 lines, previously this was only 2. New hyperlink policies ...................... - Added [[goto Max length of heading links]] to limit the display length of any hyperlink derived from an observed heading. - Added the policy [[goto Create Gopher links]] to toggle the conversion of gopher links into hyperlinks. - Added the policy [[goto Create Telnet links]] to toggle the conversion of telnet links into hyperlinks. - Added [[goto Check domain name syntax]] policy to toggle the checking of domain name syntax in detected URLs. You can now switch this off to allow intranet links to be accepted. - Changed hyperlink detection to only allow explicit FTP URLs and email addresses that don't start with numbers. These behaviours can be reversed using the new policies [[goto Only allow explicit FTP links]] and [[goto Allow email beginning with numbers]], both of which are on the _Output->Hyperlinks_ tab. - Added support for new top level domains (.info, .biz etc) - Added support for the "snews://" secure news server protocol - URLs of the form http://username@domain_name/... are now supported - Added support for "obfuscated" URLs such as http://3640005069/ http://7934972365/ http://0330.0366.0021.0315/ http://%6c%6f%63%6b%65%72%67%6e%6f%6d%65%2e%63%6f%6d/ Although the display text is left unchanged, the hyperlink will point to a non-obfuscated URL (either the domain name, or an IP address). This is because the obfuscated URLs such as there are often used by spammers, and the author has no intention of allowing his software to aid spammers in their goals. If someone cares to give me a valid reason for using such URLs I may reconsider this behaviour. New styling policies .................... - Added [[goto Allow automatic centring]] and [[goto Automatic centring tolerance]] policies. These allow you to look for text that is centred and to specify a tolerance used in this detection. - Added [[goto Use <EM> and <STRONG> markup]] policy to allow a choice of markup for phrases highlighted in asterisks or underscores. New table analysis policies ........................... - Added [[GOTO Default TABLE layout]] policy (also the pre-processor [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] command) This allows you to specify the number of columns in each table, and the attributes of each column, specifically the character position that marks the end of each column. Rather than use this policy, it is probably better to use the related pre-processor [[goto Pre-processor command: TABLE_LAYOUT,TABLE_LAYOUT]] command in the source text on a per-table basis. - Added [[goto Ignore table header during analysis]] policy (also pre-processor [[goto Pre-processor command: TABLE_IGNORE_HEADER,TABLE_IGNORE_HEADER]] command) Specifies that table headers should be ignored when columns are being auto-detected. Some tables have complex headers that confuse the analysis. This policy can be used to help them be ignored. - Added [[goto Table extending factor]] policy. This controls the degree to which pre-formatted lines should be expanded into adjacent text. - Added [[goto Column merging factor]] policy which controls the degree to which columns which don't appear to be very clear should be "merged" together - Added [[goto Could be blank line separated]] policy Indicates that tables could be using blank lines to separate rows of data. This affects the analysis and detection of the tables extent. - Added [[goto Column boundaries have zero width]] policy for tables that have no separator character between columns. Can be useful for some tables generated by software - Added [[goto Look for diagrams]] policy. Can be used to stop complex tables being wrongly interpreted as "diagrams" - Added [[goto Default TABLE cell alignment]] and [[goto Default TABLE alignment]] policies to allow you to set the default alignments of data within table cells and of tables on the page. - Added [[goto Column boundaries have zero width]] policy to allow for tables generated with a fixed layout an no gap between columns. - Added [[goto Default TABLE delimiter character]] policy to allow the delimiter used for delimited data tables to be specified (when not comma or tab) - Added [[goto Expect multiple COLSPAN values]] policy to allow you to identify that tables may have many cells which span columns, and to therefore relax the criteria when searching for columns in a table. - Added [[goto Max length of candidate table lines]] policy to allow you to limit the length of input line that could be considered for inclusion in a candidate table. New table generation policies ............................. - Added [[goto Keep original table lines in output]] policy to allow lines that separated rows in the input data to be maintained in the output. - Added [[goto Default table html attributes]] policy to allow the definition of HTML attributes to be added to the <TABLE> tags that are generated - Added [[goto Default table html cell attributes]] policy to allow the definition of HTML attributes to be added to the <TH> and <TD> tags that are generated New 'what to look for' policies ............................... - Added [[goto Look for underlined text]] policy. This allows text detected as underlined (other than headings) to be underlined in the output. - Added [[goto Look for hanging paragraphs]] and [[goto Minimum ruler length]] policies. these allow horizontal lines in the soured to be turned into <HR> tags. Other new policies .................. The following policies can't be accessed via the User Interface, but are listed here for completeness. - [[goto Contents style code]] - [[goto Default TABLE caption]] - [[goto Default TABLE header cols]] - [[goto Expect Second Word Headings]] - [[goto First Section Number]] - [[goto Use <CODE>..</CODE> markup]] $_$_HELP_CHAPTER 3,"New programs" New programs in version 5.0 --------------------------- As well as the Windows and console versions, AscToHTM is also available (under separate licence) in [[goto API version now available, API form]] so that developers can harness the power of AscToHTM's conversion abilities for use in their own software. Also the [[goto New utility A2HDETAG]] allows documents marked up using the AscToHTM pre-processor to be converted into plain text files (e.g. for sending out as newsletters). API version now available ......................... As with all JafSoft converters, AscToHTM is available under separate license as an Application Programming Interface (API). This API allows software developers to harness the powerful abilities of AscToHTM from within their own software products. The API is written in C++, and is supplied as either a library or a DLL under Windows. As such it can easily be invoked from C, C++ and Visual Basic software and has also been successfully invoked from inside Java and C# programs. New utility A2HDETAG .................... For users who register, there is a new, separate command line utility called A2HDETAG available so they can "de-tag" their source files of all AscToHTM pre-processor tags, leaving a plain text fit for publishing, e.g. on Usenet. In conjunction with this new BEGIN/END_ASCII ... END_ASCII pre-processor tags have been added. These identify text that will be copied to the output of A2HDETAG. It is ignored in all other conversions, and is intended to allow alternative text to be placed in text and HTML versions of a document. $_$_HELP_CHAPTER 3,"Other changes" Other changes in version 5.0 ---------------------------- Other changes include :- - [[goto New Pre-processor tags]] - [[goto Changes to the Windows version]] - [[goto Changes to the command line version]] - [[goto Changes to document analysis]] - [[goto Changes to documentation]] - [[goto Other new options]] New Pre-processor tags ...................... Added several new pre-processor in-line tags :- $_$_BEGIN_DELIMITED_TABLE [[goto Pre-processor command: FILENAME, FILENAME]] outputs name of file being converted [[goto Pre-processor command: FRACTION, FRACTION]] outputs a fraction [[goto Pre-processor command: VERSION, VERSION]] outputs AscToHTM program name and version number [[goto Pre-processor command: IGNORE, IGNORE]] multi-line text to be ignored [[goto Pre-processor command: IGNORE_THIS,IGNORE_THIS]] in-line text to be ignored $_$_END_DELIMITED_TABLE Changes to the Windows version .............................. - The main screen now allows access to Policy file selection. Previously this was only available on the menu structure. The Menu structure has been left unchanged, meaning you now have two ways of choosing your policy files. - The main screen now allows you to search sub folders when using wildcards. - The main screen also allows you to specify the File conversion type. You can choose to treat the input file as a number of different table types (e.g. tab-delimited data). - You no longer get prompted to "save policy" just because you pressed OK on one of the policy sheets. Now this only happens when something has been changed. - The main menu now has a "check for updates" option. If you select this you'll be taken to the JafSoft website where you'll be told if any newer versions of the software have been released. - Program now remembers positions of windows from one invocation to the next. - The user interface is now available in Italian, French and Swedish. Changes to the command line version .................................... - Command line now allows multiple filespecs, separated by spaces. Policy file must now be a .pol file, rather than the second argument. Changes to document analysis ............................ - More changes on bullet characters, in particular to disallow 'O' (upper case) from becoming a bullet character through analysis. This really doesn't work in Portuguese documents :-) 'o' (lower case) may still be detected. If upper case 'O' is wanted this can still be manually switched on. - Horizontal lines are now implemented as line rules whose length attempts to approximate the original (e.g. 50% or whatever). Previously lines would become full width. - Bookmark names from filename are now lower case (to reduce possible mismatches) - Shareware version now expires after 30 days + 5 uses. This will allow people to use the software on 5 different days after the first 30 days, giving people more time to evaluate the software at their leisure. - Now strip out leading and trailing "---" from heading text to make them more presentable in HTML - Changed emphasis handling to allow hyphenated parts to be emphasised independently, e.g. pre-_formatted_ or _pre_-formatted. - Fine-tuned the detection of whether or not a file has an in-situ contents list - The [[goto Pre-processor command: LINKPOINT, LINKPOINT]] pre-processor tag can now be used as a directive as well as an in-line tag. (see the [Tag Manual] for details). - Increased maximum width allowed for input lines in tables to 5.0 (after encountering a sample at 165). Lines longer than this are still disregarded as candidate table lines. - Improved analysis for tables using bar ('|') column separators - Improved detection of ASCII art diagrams. - Improved handling of heavily indented blocks of text. Previously these were (poorly) rendered as tables. Now the tables more accurately preserve the large indentation (see [[goto Text block detection]]). - The software will now automatically detect where a table is in fact tab-delimited data. Where detected it will then and use that tab structure to calculate columns. Changes to documentation ........................ - This document has been completely re-written. It is converted from a single text file into the HTML pages, an RTF file and the Windows Help file using the [AscToHTM] and [AscToHTM] programs. You can view the [[SOURCE_FILE]] for this document as file "AscToHTM.txt". - The [Tag Manual] describes the tagging systems available to JafSoft conversion utilities. Note that not all of the tags described there are relevant (or supported) in HTML generation. However many are common between the converters, should you wish to convert the same text file into other formats - A "Table manual" is under production to explain how to get the most from tables in your conversions. This is expected to appear some time after AscToHTM 5.0 is released. Other new options ................. - Added the "Suppress URL messages" option to the [[goto Diagnostic settings]]. When enabled all URLs, email addresses etc will be listed in the log file. Since this file can be saved to disk, this is one way of identifying all the candidate hyperlinks from your text file. - The new [[goto Pre-processor command: ALLOW and DISALLOW, ALLOW and DISALLOW]] tags allow you to enable/disable the search for headings and lists to sections of the document. This helps with eliminating faulty analysis that confuses numbered lists with headings, or lines of text ALL IN CAPITALS as headings. $_$_HELP_CHAPTER 2,"Version 4.1 (August 2001)" Version 4.1 (August 2001) ========================= Version 4.1 was a major update from the previous release 4.0. $_$_SECTION MAKINGRTFHELP - [[goto New functions in version 4.1]] - [[goto Other Changes in version 4.1]] $_$_SECTION ALL New functions in version 4.1 ---------------------------- - New [[goto command line qualifiers: /TABLE, /TABLE]] command line qualifier that allows the input file to be treated as a single plain text table - Added support for HEAD_SCRIPT [HTML fragment]. This allows HTML to be defined that can be copied into the <HEAD> of a document. This can included <META> tags of <SCRIPT>...</SCRIPT> sections. - Added Swedish interface. Many thanks to Dan Sverraby. - Added new policy [[popup "Only allow pages to be viewed in frames"]] - New utility A2HDETAG is available to registered users so they can "de-tag" their source files to remove all AscToHTM pre-processor tags, leaving a plain text fit for publishing, e.g. on Usenet. - Added BEGIN_ASCII ... END_ASCII pre-processor tags. These identify text that will be copied to the output of A2HDETAG. It is ignored in all other conversions, and is intended to allow alternative text to be placed in text and HTML versions of a document. - Added [[popup "character encoding"]] policy to allow the character encoding of a document to be set. The software has limited ability to detect Japanese ("x-sjis") and Cyrillic ("koi-8") text, but in some cases this will need to be set. The auto-detect of character sets can be switched off by using the [[popup "Look for character encodings"]] policy - Added policies to allow different fonts to be applied to different types of text as follows Normal text [[popup "Default font"]] Headings [[popup "Heading Font"]] Text in tables [[popup "Table font"]] Table of contents [[popup Table of contents Font, TOC Font]] Fixed-pitch text [[popup "Fixed font"]] The "Default Font" policy existed previously, the other four policies are new in this version. - Added [[goto Pre-processor command: PAGE, PAGE]] directive. This marks a page boundary. In HTML this simply results in a <HR> tag, since HTML doesn't really support pages. This may be expanded in future to allow page numbers and the like to be displayed. Other Changes in version 4.1 ---------------------------- _Windows version_ - Loading a policy file with "place policy in frames" policy will now toggle the Conversion type - You no longer get prompted to "save policy" just because you pressed OK on one of the policy sheets. Now this only happens when something has been changed. - The main menu now has a "check for updates" option. If you select this you'll be taken to the JafSoft website where you'll be told if any newer versions of the software have been released. _Documentation_ - The list of bug fixes is removed from this document and is now to be found on-line at http://www.jafsoft.com/doco/asctohtm_bug_history.html _All versions_ - Added support for HTML fragment files to $_$_INCLUDE other HTML fragment files. This allows common fragments to be shared. - Fine-tuned the detection of whether or not a file has an in-situ contents list - When Frames generation is selected the default "Split level" is set to 1 instead of 2. This means you'll get fewer files generated and - depending on the type of headings you have - no splitting may occur unless you manually increase the split level. - The [[goto Pre-processor command: LINKPOINT, LINKPOINT]] pre-processor tag can now be used as a directive as well as an in-line tag. (see the [Tag Manual] for details). - Added a "Range" attribute to the [[goto Pre-processor command: CONTENTS_LIST, CONTENTS_LIST]] tag. This allows mini-contents lists to be generated which contain only entries for a part of the document, rather than the whole document, e.g. for just a single chapter. This should help those who want to split large files into pages and to have a mini-contents list for each section. - Improved handling of VT escape characters. These are either removed from the output or converted to "line" characters - Added auto-detect of double spaced files (files where every second line is blank). This will set the [[popup "Input file is double spaced"]] policy whenever double-spaced text is detected (unless the policy has already been set). $_$_HELP_CHAPTER 2,"Version 4.0 (May 2001)" Version 4.0 (May 2001) ====================== Version 4.0 represents a major update over the previous version 3.3. $_$_SECTION MAKINGRTFHELP - [[goto New functions in version 4.0]] - [[goto Other changes in version 4.0]] $_$_SECTION_ALL New functions in version 4.0 ---------------------------- _API version_ - For those wishing to call AscToHTM programmatically, an API has been developed. This is sold under separate license. Contact *info<at>jafsoft.com* (replace "<at>" by "@") if you're interested. _Linux version_ - A Linux command line version will soon be available. Beta versions have been tested, and I hope to do a Linux command line release just after version 4 is released. _Windows version_ - You can now choose from the main screen whether you want your HTML output as one or more HTML file(s), sent to the Windows Clipboard (see [[goto Outputting HTML to the clipboard,Output to the Windows clipboard]], or turned into a set of HTML frames (see [[goto Generating a set of Frames, Frames]]). - Program now remembers positions of windows from one invocation to the next. - The user interface is now available in Italian. _All versions_ - Version 4 introduces frames support (see [[goto Generating a set of Frames, Frames]]). This introduces a large number of supporting policies :- [[popup "Place document in frames"]] [[popup "Output frame name"]] [[popup "Header Frame depth"]] [[popup "Footer Frame depth"]] [[popup "Contents Frame width"]] [[popup "Use main header in header frame"]] [[popup "Use main footer in footer frame"]] [[popup "Add contents frame if possible"]] [[popup "Add Frame border"]] [[popup "Open frame links in new window"]] [[popup "New frame link window name"]] [[popup "Add NOFRAMES links"]] [[popup "NOFRAMES link URL"]] [[popup "Number of levels in contents frame"]] [[popup "First frame page number"]] [[popup "Header frame background colour"]] [[popup "Header frame text colour"]] [[popup "Contents frame background colour"]] [[popup "Contents frame text colour"]] [[popup "Footer frame background colour"]] [[popup "Footer frame text colour"]] - Added [HTML fragments] feature, with [[popup Fragments file,HTML fragments file]] policy and DEFINE_HTML_FRAGMENT, RESET_HTML_FRAGMENT pre-processor commands. This allows you to define HTML fragments that can be used to replace the standard HTML generated by the program. This allows you to customize headers, footers, horizontal rules, contents lists, navigation bars and more. - Added support for URL parsing, including :- - new top level domains (.info, .biz etc) are supported - the "snews://" secure news server protocol type is now supported - URLs of the form http://username@domain_name/... are now supported - Added [[popup "Check domain name syntax"]] policy - Added [[popup "Create Telnet links"]] policy - Added support for "obfuscated" URLs such as http://3640005069/ http://7934972365/ http://0330.0366.0021.0315/ http://%6c%6f%63%6b%65%72%67%6e%6f%6d%65%2e%63%6f%6d/ Although the display text is left unchanged, the hyperlink will point to a non-obfuscated URL (either the domain name, or an IP address). This is because the obfuscated URLs such as there are often used by spammers, and the author has no intention of allowing his software to aid spammers in their goals. If someone cares to give me a valid reason for using such URLs I may reconsider this behaviour. - Added support for embedded headings with the [[popup "Expect embedded headings"]] policy (see [[goto embedded heading detection]]). These are "headings" that are embedded as the first sentence in a paragraph. - Added support for headings that start with particular words or phrases via the [[popup "Heading key phrases"]] policy (see section on detecting [[goto key phrase headings]]). - New [[goto command line qualifiers: /COMMA, /COMMA]] and [[goto command line qualifiers: /TABBED, /TABBED]] command line qualifiers that allow comma delimited and tab delimited files be converted into tables. - Added [[popup "Check indentation for consistency"]] policy to allow checking of headings to be relaxed (e.g. when they're centred on the page). - Added [[popup "Look for diagrams"]] policy - Added [[popup "Input file contains PCL codes"]] policy - Added [[popup "Input file contains Japanese characters"]] support. - Added [[popup "Preserve new paragraph offset"]] policy - Added [[popup "Omit <HEAD> and <BODY> from output"]] policy - Added [[popup "Document Base URL"]] policy - Added [[popup "Comment generation code"]] policy - Added [[popup "Number of words to include in filename"]] policy to allow filenames to be generated from the first few words of the title when splitting documents with underlined or capitalised headings at each heading. - Added [[popup "Lines to ignore at end of file"]] and [[popup "Lines to ignore at start of file"]] policies to allow lines at the start and end of the source file to be discarded. This can be useful if you source text is coming from a third party source that adds extra, unwanted, lines. - Added [[popup "Suppress all colour markup"]] policy - Added [[popup "Column boundaries have zero width"]] policy Other changes in version 4.0 ---------------------------- _Windows version_ - On some systems DDE doesn't always work properly. This would cause the program to hang when it attempted to display results. In such cases you would need to stop the program from the task manager. In version 4 the program will now detect when this has happened and disable use of DDE next time it runs. NOTE: DDE won't work with Netscape 6.0 (it doesn't support it) - Added the policy [[popup "Suppress URL messages"]] to the Settings | Diagnostics menu option. When enabled all URLs, email addresses etc will be listed in the log file. Since this file can be saved to disk, this is one way of identifying all the candidate hyperlinks from your text file. _All versions_ - Improved analysis for tables using bar ('|') column separators - Improved detection of ASCII art diagrams. - Improved handling of heavily indented blocks of text. Previously these were (poorly) rendered as tables. Now the tables more accurately preserve the large indentation (see [[goto Text block detection,Text blocks]]). - The first three words of an underlined heading are now used to generate the filename. Previously only the first word was used, leading to less meaningful names, with more chances of duplication. - VMS command line now allows multiple filespecs, separated by spaces. Policy file must now be a .pol file, rather than the second argument. - Anchor names from filename are now lower case (to reduce possible mismatches) - Shareware version now expires after 30 days + 5 uses. This will allow people to use the software on 5 different days after the first 30 days, giving people more time to evaluate the software at their leisure. - Now strip out leading and trailing "---" from heading text to make them more presentable in HTML or RTF - Added support for headings that span up to 3 lines, previously this was only 2. - Changed heading to allow <H4> markup to be used. Previously "level 4" headings would get <H3> markup since anything smaller would end up smaller than the main text. With the advent of CSS style sheets This should be less of a problem. - Changed emphasis handling to allow hyphenated parts to be emphasised independently, e.g. pre-_formatted_ or _pre_-formatted. $_$_HELP_CHAPTER 2,"Version 3.3 (June 2000)" Version 3.3 (June 2000) ======================= The AscToHTM [[TEXT 3.3]] release follows 6 "micro-releases" announced via the updates page on the Web. As such it will appear as a small step forward over [[TEXT 3.2.06]], but in fact it offers a fair amount of new functionality over version [[TEXT 3.2]] Major changes in version [[TEXT 3.3]] include :- - *Support for fonts*. You can now choose a font for the whole document. By default this is implemented using CSS, but you can elect to use <FONT> tags should you prefer. - *Enhanced Language support* The Spanish and German interfaces added in the last version have had Portuguese added. Also a new feature allows you to save the interface to a "language skin" text file which may be edited and then reloaded. Using this feature we can now offer - American English (simply a spell-checked UK English file) - "Babelfish" French. A French translation from http://babelfish.altavista.com/ - "Babelfish" Italian. An Italian translation from Babelfish. If anyone wants to correct these files and send them back to me, feel free. - *More table generation controls*. Several new controls have been added to give you more control over the detection, analysis and generation of tables in the text. - *Support for comma and tab delimited tables*. Pre-processor commands have been added to allow you to mark up a section of comma-delimited or tab-delimited data you want turning into a table. - *Support for preserving file/line structures*. You can now elect to preserve the original line structure of a file, or to place the whole file in <PRE> markup (which is a little defeatist, but has its uses) - *Support for non-standard characters*. The program can now recognize, to a limited extent, DOS line-drawing characters, MIME-encoded text and text documents with "change bars" in them. - *New "Tag manual"*. The [[goto Using the pre-processor]] and [[GOTO pre-processor in-line tags, in-line tags]] sections of this document have now been re-merged and their contents largely moved to a new document called the [Tag Manual]. New functions in version 3.3 ---------------------------- _Fonts_ - The default font for the whole document can now be set via the [[popup "Default font"]] policy. Headings will also adopt the selected font, and will scale with the selected font size, although the <H1> headers are slightly smaller than the default. You can choose to have the fonts implemented using <FONT> tags or CSS (e.g. according to your target audience) using the [[popup "Use CSS to implement fonts"]] policy. _Tables_ - Added several new policies and tags to help with table analysis. Policies added include [[popup "Default TABLE layout"]] (also pre-processor tag [[goto Pre-processor command: TABLE_LAYOUT, TABLE_LAYOUT]]) This allows you to specify the number of columns in each table, and the attributes of each column, specifically the character position that marks the end of each column. Rather than use this policy, it is probably better to use the related directive $_$_TABLE_LAYOUT in the source text on a per-table basis. [[popup "Default TABLE alignment]] (also pre-processor tag [[goto Pre-processor command: TABLE_ALIGN, TABLE_ALIGN]]) Allows the alignment of the table to be specified (left, right, center) [[popup "Ignore table header during analysis"]] (also pre-processor tag [[goto Pre-processor command: TABLE_IGNORE_HEADER, TABLE_IGNORE_HEADER]]) Specifies that table headers should be ignored when columns are being auto-detected. Some tables have complex headers that confuse the analysis. This policy can be used to help them be ignored. [[popup "Table extending factor"]] Controls the degree to which pre-formatted lines should be expanded into adjacent text. [[popup "Column merging factor"]] Controls the degree to which columns which don't appear to be very clear should be "merged" together [[popup "Could be blank line separated"]] Indicates that tables could be using blank lines to separate rows of data. This affects the analysis and detection of the tables extent. - Added support for embedding comma-delimited and tab-delimited table data in your source file (e.g. data exported from Excel and the line). The new pre-processor directives :- [[goto Pre-processor command: COMMA_DELIMITED_TABLE, BEGIN/END_COMMA_DELIMITED_TABLE]] [[BR]] [[goto Pre-processor command: DELIMITED_TABLE, BEGIN/END_DELIMITED_TABLE]] [[BR]] _Other_ - Added options to allow more control over how the original document's file structure should be preserved [[popup "Treat each line as a paragraph"]] If this option is selected, every line in the source file is treated as a paragraph. This may be suitable if the file has been authored using an editor that wraps the lines (i.e. doesn't put in hard breaks) and which doesn't add blank lines between paragraphs. [[popup "Preserve line structure"]] If this option is selected a <BR> is added to every line, thereby preserving the line structure of the original and giving the resulting HTML file an "A4 look" that hugs the left margin regardless of how wide the window is made. [[popup "Preserve file structure using <PRE>"]] If this option is selected the whole document is placed in <PRE> markup, and very few conversions are attempted. This is really a "last resort" option that you may want to use if the file has complex structures which the program is failing to understand. This option was added for a customer who wanted to convert all 2800 RFCs without having to manually correct each one. - Added support for parsing files with some Mime-encoded quotable strings in them. The new policy [[popup "Input file contains mime encoding"]] can be found under _Analysis->File structure_. At present there is some (very limited) auto-detect for this feature. - Added support for documents with change bars. By default change bars are stripped out, and the changed text coloured red this behaviour may be changed in later versions. Added the new policy [[popup "Input file has change bars"]] which can be found under _Analysis->File Structure_. - Added support for converting DOS characters. The new policy [[popup "Input file contains DOS characters"]] can be found under _Analysis->File Structure_. There is a limited auto-detect of DOS characters when diagrams are present. - Changed hyperlink detection to only allow explicit FTP URLs and email addresses that don't start with numbers. These behaviours can be reversed using the new policies [[popup "Only allow explicit FTP links"]] and [[popup "Allow email beginning with numbers"]], both of which are on the _Output->Hyperlinks_ tab. - Added the policy [[popup "Create gopher links"]] to toggle the conversion of gopher links into hyperlinks. - Added the policy [[popup "Check indentation for consistency"]] so that it could be disabled in documents where headings were centred (and thus all at different indentations) - Added several new pre-processor in-line tags :- [[goto Pre-processor command: FILENAME, FILENAME]] - output name of converted file[[BR]] [[goto Pre-processor command: FRACTION, FRACTION]] - output a fraction[[BR]] [[goto Pre-processor command: VERSION, VERSION]] - output program version number[[BR]] [[goto Pre-processor command: IGNORE_THIS, IGNORE_THIS]] - for comments in the source code[[BR]] - Added policy to allow selection of which version of HTML should be generated. Policy is [[HYPERLINK, POLICY,"HTML version to be targeted"]]. Only "HTML [[TEXT 3.2]]" and "HTML [[TEXT 4.0]] Transitional" are currently supported. Other changes in version 3.3 ---------------------------- _Windows_ - The main screen now allows access to Policy file selection. Previously this was only available on the menu structure. The Menu structure has been left unchanged, meaning you now have two ways of choosing your policy files. _All_ - The contents list styling has been changed slightly. For example only the major section headings are now shown in bold. People were complaining :-) - Now add BORDER=0 attribute to tables with no border, rather than just omitting the attribute. This is a workaround for a bug in Netscape where a gap appears where a border would be when coloured rows are selected. - Support for IE [[TEXT 3.0]] as the browser of choice is added, by allowing the filename rather than file URL to be passed to the browser. To do this disable the "file://localhost/" option on the _Settings->Viewers_ dialog screen. - More changes on bullet characters, in particular to disallow 'O' (upper case) from becoming a bullet character through analysis. This really doesn't work in Portuguese documents :-) 'o' (lower case) may still be detected. If upper case 'O' is wanted this can still be manually switched on. - Increased maximum width allowed in tables to 200 (after encountering a sample at 165). Lines longer than this are disregarded as candidate table lines. - Introduction of German and Portuguese user interface, with extension of the Spanish user interface. - Horizontal lines are now implemented as <HR> tags whose length attempts to approximate the original (e.g. 50% or whatever). Previously lines would become full width. - Chapters 7 and 8 of this document were merged into a single chapter 7 (about the pre-processor). Most of that material has now been moved to the new [Tag Manual]. Subsequent chapters have thus been renumbered which may lead to invalid references to chapter 11... especially if you keep old versions of the doco lying around. Also reversed the order of sections in this "Change History" section $_$_HELP_CHAPTER 2,"Version 3.2 (October 1999)" Version 3.2 (October 1999) ========================== (Version [[TEXT 3.1]] was never released, but a release of [AscToTab] occurred sometime after version [[TEXT 3.0]], and so in keeping with the policy of synchronizing version numbers *that* was labelled version [[TEXT 3.1]]) Over a year after the last release, version [[TEXT 3.2]] is a major upgrade, but is only given a minor version number change because the remainder of the functionality produced in that time will be revealed in version [[TEXT 4.0]]. Version [[TEXT 3.2]] starts to prepare the groundwork for Cascading Style Sheet (CSS) and general font support that will be introduced in version [[TEXT 4.0]]. This has required a fairly radical change to the type of HTML code generated and how this is put together. For example the HTML is now more standards compliant (this is now a stated goal of the software, although I can't always promise full compliance see [[goto Standards compliance]]), and as an aid towards CSS support "optional" end tags such as </P> are now being placed in the generated HTML. Note that the use of the <FONT> tag is deprecated in HTML [[TEXT 4.0]], and if you choose to add FONT markup to your pages they'll become much bigger, especially if they contain tables. This is because the HTML standard requires the FONT tag to continually be re-expressed to achieve the right appearance in all browsers (believe me, I only accepted this through bitter experience and grudgingly). Major changes in version [[TEXT 3.2]] include :- - The program now *always* makes three passes through the document - previously it only did this if a contents list was requested. This may make the conversion a little slower. The middle pass calculates how the file will be split into sections, where all the hyperlinks should point to and what the contents list should be. This approach should be less error prone than previously. - New "overview" options (see [[goto 'What to look for' Policies]]). These allow you to easily enable and disable the program's search for certain features. - Introduction of in-line tagging (see [[GOTO pre-processor in-line tags, in-line tags]]). These allow you to get more out of your conversion by inserting commands into your source text. - Addition of DDE support (in Windows) - New and improved command line options, and full command line support built into the Windows version - Improved message filtering. Each message is now labelled according to its type (information, warning etc), and may be optionally suppressed or filtered by severity. A new [[goto command line qualifiers: /SILENT, /SILENT]] command qualifier allows complete suppression of messages. - Improved log file capability - Added support for mail and USENET headers - (Limited) support added for stripping out page markers, converting "double spaced" files, and converting .prn and VT escape sequences. This functionality may be improved in later versions. - New options to colour the odd and even rows of tables differently (see [[GOTO Table generation policies]] and 7.1.4) New functions in version 3.2 ---------------------------- _Windows Version_ - Added "Save" option to status dialog, so that the messages can be saved into a .log file - Added DDE support to display results in existing browser window - Full drag and drop support added. You can now drag files onto the program when it is visible. - New "browse for directory" buttons added. - More menu options added to make finding policies easier. _All versions_ - Now support tab-delimited tables - Support for stripping out mail and USENET headers - New pre-processor directives :- - [[goto Pre-processor command: DELIMITED_TABLE, BEGIN/END_DELIMITED_TABLE]] section delimiters - [[goto Pre-processor command: IGNORE, BEGIN/END_IGNORE]] command - [[goto Pre-processor command: CONTENTS_LIST, CONTENTS_LIST]] command - [[goto Pre-processor command: NAVIGATION_BAR, NAVIGATION_BAR]] command - [[goto Pre-processor command: LINERULE, LINERULE]] command - [[goto Pre-processor command: TOC, TOC]] command - New and improved command line qualifiers - [[goto command line qualifiers: /CONSOLE, /CONSOLE]] - [[goto command line qualifiers: /LIST, /LIST]] - [[goto command line qualifiers: /OUTPUT, /OUTPUT=filename]] - [[goto command line qualifiers: /SILENT, /SILENT]] - (improved) [[goto command line qualifiers: /LOG,/LOG=<filespec>]]. You can now specify the log filename - (improved) [[goto command line qualifiers: /POLICY,/POLICY=filename]]. You can now specify the created policy filename - New overview "look for" analysis policies :- - [[popup "Look for indentation"]] - [[popup "Look for white space"]] - [[popup "Look for short lines"]] - [[popup "Look for quoted text"]] - [[popup "Look for preformatted text"]] - [[popup "Look for MAIL and USENET headers"]] - [[popup "Look for horizontal rulers"]] and [[popup "Minimum ruler length"]] - [[popup "Look for MAIL and USENET headers"]] - [[popup "Look for bullets"]] - [[popup "Look for hanging paragraphs"]] - [[popup "Look for white space"]] - Other new analysis policies :- - [[popup "Input file has page markers"]] and [[popup "Page marker size (in lines)"]] - [[popup "Input file is double spaced"]] - [[popup "recognize '-' as a bullet"]] - [[popup "recognize 'o' as a bullet"]] - New diagnostic policies :- - "Monitor tag generation" - [[popup Display messages]] policy and [[goto command line qualifiers: /SILENT, /SILENT]] qualifier - [[popup "Suppress INFO messages"]], - [[popup "Suppress TAG ERROR messages"]] - [[popup "Suppress URL messages"]] - [[popup "Suppress WARNING messages"]] - [[popup "Suppress program ERROR messages"]] - Other new output policies :- - [[popup "Maximum level to show in contents"]] - [[popup "Preserve underlining of headings"]] - [[popup "Use <EM> and <STRONG> markup"]] - [[popup "Colour data rows"]] and related policies (see [[GOTO TABLE generation policies]]). - [[popup "Default TABLE cell alignment"]] and [[goto Pre-processor command: TABLE_CELL_ALIGN, TABLE_CELL_ALIGN]] directive - [[popup "Suppress all colour markup"]] - [[popup "Open links in new browser window"]] and [[popup "new browser window name"]] - [[popup "Break up long HTML lines"]] Other changes in version 3.2 ---------------------------- _On the web site, and documentation_ - A dedicated site www.jafsoft.com now deals with AscToHTM and related products. - An [updates] page has been added to the Web site. This will list all the updates available for AscToHTM, although in most cases you'll need to be a registered user to receive details for you to obtain the update. - An [FAQ] has been added to the web site. It's not finished yet (what part of the web is?), but it may help answer some of your questions. - Created a new document called "The [Policy Manual]". This replaces what was becoming the largest section of this document. _Windows version_ - The Windows help file now has a better Index. It also has a full contents list as a topic, showing you the structure of the RTF file used to generate the Help file. Unfortunately I've been unable to hyperlink this topic. - The Windows version now "remembers" which options page you were on so that each time you go back there the same sheet is shown. - The Windows version is now "statically linked" against the necessary .DLLs. This makes the program slightly larger, but makes the download smaller as it is no longer necessary to ship .DLLs with the program. This makes overall version management simpler. _VMS version_ - The VMS version now converts all filenames to lower case internally. This is so that all hyperlinks and references to the file are in lower case, making them more Internet-friendly and portable to other systems. _All versions_ - Changes to the tagging to aid [[goto standards compliance]] and CSS support. this includes the addition of the </P> tag which was previously omitted. These changes have introduced slight differences in the amount of vertical white spacing produced in places. - Improvements have been made to the file splitting algorithms. In particular - The program will no longer generate two output pages with the same name. Where duplicate names are detected, the second file is given a generated name, usually by appending "_n" (n=1,2,3...) to the filename. All hyperlinks pointing to sections in the duplicate file will be adjusted accordingly. - A file with underlined headings can now be split into pages at the heading boundaries. The subsequent pages have _U1, _U2... appended to the name of the first page. - Local links (i.e. to anchors in the same file) are now recognised as such, and the filename is omitted. This should make it easier to rename files after production without breaking local hyperlinks. Links to/from other files would still stop working though. - link names for underlined or capitalised headings that are more than 60 characters long are now truncated. They are given a link name derived from the first 30 characters of the section name with a unique identifier tagged on the end. This avoids long link names being split over two or more lines and becoming unusable. - Allow relative links to subtract out filename (e.g. in contents list) when target is in same file - Can now recognize URLs with commas in then such as recognize http://cgi.pathfinder.com/netly/opinion/0,1042,1692,00.html in addition to comma separated lists of URLs. - The KEYWORDS, DESCRIPTION and TITLE pre-processor commands can now be multi-line. This allows long lists of keywords to be placed over several lines (each beginning with the command), making then easier to manage. - The default name for the directory index file is now "dirindex.html" rather than "index.html" to prevent overwriting of any existing index file. - Program now always does a "contents pass". Benefits of this are - can now generate in situ contents lists /contents bars - can now generate navigation bars wherever wanted - can now eliminate duplicate filename generation - can check hyperlink cross references are correct - Improved table/diagram recognition - Now support conversion of tab-delimited data into tables, provided it's placed inside [[goto Pre-processor command: DELIMITED_TABLE, BEGIN/END_DELIMITED_TABLE]] directives - Relaxed indentation test on "n.n" headings. Heading can now be 2 characters to the left, or 1 character to the right of the expected position - Now recognize use of asterisk and underscore combined to produce bold-italic emphasis. Previously only asterisk (bold) and underscore (italic) by themselves were recognised. - Now recognize "]" as a possible "quoting" character. - Now recognize '+' as an underling character - Improved error reporting when file errors occur. The program will now abort the conversion on error, instead of continuing and reporting errors for each line. - Now detect read-only output directories and abort conversion. This would occur if you tried to convert a file on CD. - Definitions now use <DL compact> offering a more-faithful rendition of the original text - Underlined heading and text will now be rendered as underlined by default. Previously this either promoted the previous line to be a heading, or was drawn as a line. - Improved handling of first line indents on paragraphs. Now these are preserved in the output by the inclusion of &nbsp; characters, and the error whereby the following line was deemed to be a different indentation (and thus acquire a <BLOCKQUOTE>) has been largely solved. - Introduction of the TEXT in-line tag now allows numbers like "Windows [[TEXT 3.1]]" to be protected from conversion into a hyperlink to section 3.1. $_$_HELP_CHAPTER 2,"Version 3.0 (August 1998)" Version 3.0 (August 1998) ========================= There are a fair number of small changes in functionality over V2.3, together with a fair number of bug fixes and refined algorithms. A lot of development during this time was directed towards the production of a text-to-RTF converter ([AscToRTF]) using the same analysis engine. Consequently there are a lot of changes "under the bonnet". The main functional change has been the revamp of the Windows User Interface. A new section (4.1.2) has been added to this document describing the Windows interface in some detail. The changes include :- - the button bar is replaced by a proper Windows menu, allowing easier access to the programs functions. - under the Help menu a link to the HTML documentation shipped with the software is now provided. - the policy sheets are now "non-modal". This means you no longer have to dismiss them in order to do a conversion, you can leave them up whilst the conversion is going on, making it easier to go through the convert-change policy-convert cycle. New functions in version 3.0 ---------------------------- _Windows Version_ - Major re-structuring of the user interface - Program's Help options now provide access to the online and offline versions of the HTML doco. A lot of people were downloading the software and then picking up a version of the doco, unawares they already had it. Don't you people read README.TXT files or what? :-) _All Versions_ - New [[popup "Search for Definitions"]] policy - New [[popup "TAB size"]] policy - New [[popup "Expect sparse tables"]] policy and [[goto Pre-processor command: TABLE_MAY_BE_SPARSE, TABLE_MAY_BE_SPARSE]] pre-processor command - New [[popup "Add <BR> to lines with URLs"]] policy - New [[popup "Output file extension"]] policy - New [[popup "Minimise HTML file size"]] policy - New [[popup "Headings colour"]] policy. Eventually I hope to add a whole suite of heading styling options, as these have been requested by a number of people. - New [[popup "Convert TABLE X-refs to links"]] policy and [[goto Pre-processor command: TABLE_CONVERT_XREFS, TABLE_CONVERT_XREFS]] pre-processor command - New [[goto Pre-processor command: CHANGE_POLICY, CHANGE_POLICY]] pre-processor command - New [[popup "Error reporting level"]] policy Other changes in version 3.0 ---------------------------- - Improved Windows interface - Empty lines in a table cell now get an extra &nbsp; added, in addition to the <BR>. This is to compensate for a bug in Internet Explorer 3 which would ignore the <BR> otherwise, leading to alignment errors. - Now treat phrases with all the words connected by underscores, and with underscores at both ends as well as underlined e.g. _this_type_of_thing_ - Improved handling of tables with long URLs in them. Previously these would not be recognised as part of a table. Increased "long line" limit inside tables to 110 characters - Improved error reporting/handling - Report unrecognised pre-processor lines - Report results of table analysis (e.g. if diagrams are detected) - Report failure to find requested files - Abort conversion if can't find requested policy file - Improved detection of "mal-formed" tables. Previously this was over-cautious, especially on short tables. - Now add a trailing "/" to www etc URLs if none present (e.g. www.jafsoft.com). This is a more correct URL, which should be accessed slightly more efficiently. - Now recognised "....." underlining, although why people do this is beyond me :) - Improved contents list detection in short documents with only level one headings, and documents with a chapter "0". - Improved headings detection in small files. Made this less trigger happy. - Improved code detection, and now add bold emphasis of C++ like comments inside a code section - No longer allow "{" and "}" to be detected as probable bullet characters when code is expected - I've produced (with help from antipodean friends) an icon for files converted by AscToHTM. It's called a2hlogo.gif. Feel free to use it should you wish on any pages created with AscToHTM. An example piece of HTML code would be $_$_BEGIN_PRE <A HREF="http://www.jafsoft.com/asctohtm/?from=doco"> <IMG SRC="a2hlogo.jpg" WIDTH=100 HEIGHT=36 BORDER=0 ALT="Converted by AscToHTM"></A> $_$_END_PRE - With the introduction of the [[popup "Add <BR> to lines with URLs"]] policy this behaviour is no longer default. That is, if you *do* want <BR> added at the end of all lines containing URLs you will need to switch this behaviour on using the new policy. - With the introduction of the [[popup "Convert TABLE X-refs to links"]] policy this behaviour is no longer default. That is, if you *do* want section links inside your tables, you will need to switch this behaviour on using the new policy. - ".htm" files are now with a lowercase extension, unless [[popup "Use DOS filenames"]] policy selected $_$_HELP_CHAPTER 2,"Version 2.3 (April '98)" Version 2.3 (April 1998) ======================== Minor bug fixes and upgraded functionality over V2.2. The main functional changes have been a) The introduction of wildcard support to allow conversion of multiple files at once. b) (related to the above) the introduction of the [[GOTO Generating a directory page, Directory Page]] feature that allows the generation of a hyperlinked document spanning all the files in a directory. c) Major re-write of the contents-list generating routines. The program now makes a third, intermediate, pass through the document to analyse the contents structure. This means that contents lists are now placed at the top of the HTML file be default, rather than in a separate file as previously - though that behaviour is still supported if wanted. This approach is expected to pay further dividends in later releases. New functions in version 2.3 ---------------------------- _Windows Version_ - Added a "Preform simple conversion" tick box on the front panel. This does exactly the same as the [[popup "Keep it simple"]] policy. - Improved the Headings dialog to allow headings policies to be more easily edited now. - Pre-processor document sections now working. _All versions_ - Wildcard support has been added (see [[goto Using Wildcards]]). - Major re-writing of contents list generation has occurred. Includes new [[popup "Use any existing contents list"]] and [[popup "Generate external contents file"]]. More changes are expected here in later versions. - New [[GOTO Generating a directory page, Directory Page]] feature. Supporting policies include:- $_$_CHANGE_POLICY preserve line structure: yes [[popup "Make Directory"]] [[popup "Directory filename"]] [[popup "Show file titles in Directory"]] [[popup "Indent headings in Directory"]] [[popup "Directory title"]] [[popup "Directory keywords"]] [[popup "Directory description"]] [[popup "Directory return hyperlink text"]] [[popup "Directory Script file"]] [[popup "Directory header file"]] [[popup "Directory footer file"]] $_$_CHANGE_POLICY preserve line structure: no - New [[popup "Minimum TABLE column separation"]] policy and [[goto Pre-processor command: TABLE_MIN_COLUMN_SEPARATION, TABLE_MIN_COLUMN_SEPARATION]] pre-processor command to allow some tuning of table analysis. - New [[popup "Use first heading as title"]] policy - New [[popup "Use first line as title"]] policy - New [[popup "Recognised USENET groups"]] policy - New [[popup "Automatic centring tolerance"]] policy - New [[popup "Use <P> markup for paragraphs"]] policy to allow choice of either <P> or <BR> markup to be used for paragraphs. - New [[popup "Default table width"]] policy and [[goto Pre-processor command: TABLE_WIDTH, TABLE_WIDTH]] pre-processor command to allow table widths to be specified as percentages - New pre-processor command [[goto Pre-processor command: HTML_LINE, HTML_LINE]] Other changes in version 2.3 ---------------------------- - Reinstated some of the "error" messages removed in the last version, to do with section numbering. This should make it more visible when the section heading analysis goes wrong. - Added error reporting to file open. You should now get an error message if the program fails to find/open a file somewhere. - Now support headings down to 5 levels (previously this was 4). Note, if you only have a couple at this level, the program may still ignore them as statistically insignificant. - Removed certain policies (such as "generate policy file") from the output when generating a full policy file. This is because, when they were read back in, they could cause problems. - The "Include document section" policy is now renamed to "Include document section(s)" reflecting the fact that you can now enter multiple values on one line, rather than requiring multiple lines with one value each as previously. - Major re-structuring and additions to [[GOTO Understanding the HTML generated,HTML markup produced]] to make the section more coherent and up to date. Some of the sections marked as new in this version are simply the documentation catching up on the features added in earlier releases. Sometimes I just work too hard :^) $_$_HELP_CHAPTER 2,"Version 2.20 (Feb 1998)" Version 2.2 (Feb 1998) ====================== First major release after V2.0 (when AscToHTM first went fully-Windowed). Major change this time has been the introduction of TABLE generating algorithms. These were first made available as a separate freeware utility [AscToTab]. This version is reviewed by ZDNet and awarded 5-stars, their highest award. New functions in version 2.2 ---------------------------- _Table generation_ This is the biggest change in this version. AscToHTM now incorporates the technology first introduced in [AsctoTab]. To support this the detection of pre-formatted text has been improved, new policies added, and new pre-processor commands added. New policies include :- [[popup "Attempt TABLE generation"]] [[BR]] [[popup "Default TABLE border size"]] [[BR]] [[popup "Default TABLE header rows"]] [[BR]] [[popup "Default TABLE header cols"]] [[BR]] [[popup "Default TABLE cell spacing"]] [[BR]] [[popup "Default TABLE cell padding"]] [[BR]] [[popup "Default TABLE colour"]] [[BR]] [[popup "Default TABLE border colour"]] [[BR]] [[popup "Default TABLE caption"]] [[BR]] New Pre-processor commands include :- [[goto Pre-processor command: CODE, BEGIN/END_CODE]] [[BR]] [[goto Pre-processor command: DIAGRAM, BEGIN/END_DIAGRAM]] [[BR]] [[goto Pre-processor command: TABLE, BEGIN/END_TABLE]] [[BR]] [[goto Pre-processor command: TABLE_BORDER, TABLE_BORDER]] [[BR]] [[goto Pre-processor command: TABLE_BORDERCOLOR, TABLE_BORDERCOLOR]] [[BR]] [[goto Pre-processor command: TABLE_BGCOLOR, TABLE_BGCOLOR]] [[BR]] [[goto Pre-processor command: TABLE_CAPTION, TABLE_CAPTION]] [[BR]] [[goto Pre-processor command: TABLE_CELLSPACING, TABLE_CELLSPACING]] [[BR]] [[goto Pre-processor command: TABLE_CELLPADDING, TABLE_CELLPADDING]] [[BR]] [[goto Pre-processor command: TABLE_HEADER_ROWS, TABLE_HEADER_ROWS]] [[BR]] [[goto Pre-processor command: TABLE_HEADER_COLS, TABLE_HEADER_COLS]] [[BR]] _Other changes_ - Added pre-processor [[goto Pre-processor command: CODE, BEGIN/END_CODE]] commands to allow sections of code samples to be identified and distinguished from tables - Added pre-processor [[goto Pre-processor command: DIAGRAM, BEGIN/END_DIAGRAM]] commands to allow diagrams and sections ASCII art to be identified and distinguished from tables Other changes in version 2.2 ---------------------------- _Documentation_ - Added the "Policy Dictionary" (since superceded by the [Policy manual]), and renumbered the document accordingly. _All versions_ - "tables/pre-formatted text" - Various improvements to detecting the start and end of pre-formatted regions of text. - Shareware now expires after 30 days, rather than after a fixed date. - Headings policies have been revised. Still more work to be done in this area. - Slight improvement in detection of centred text. Still not good enough to offer as a default though (too prone to errors). - Added section on saving/using policy files - Shareware version now adds nag lines at top and bottom of the page, instead of just the top. - A number of improvements in code sample detection - Reduced number of "error" messages reported. These may be made optional in a later version, and are still placed in the diagnostic files if these are created. _Windows version_ - Now added a "Settings" dialog to allow you to configure various aspects of how the program runs such as what browser to view files with, what policy file to use as default etc, etc. - New [[goto command line qualifiers: /COMMA, /COMMA]] and [[goto command line qualifiers: /TABBED, /TABBED]] command line qualifiers that allow comma delimited and tab delimited files be converted into tables. $_$_HELP_CHAPTER 2,"Version 2.10 (never officially released)" Version 2.1 (never officially released) ======================================= V2.1 was never officially released, but much of this functionality "crept out" as the shareware version was updated. Some of these versions were shown as V2.01 instead of V2.1. There's nothing like a bit of consistency (and yeah, this was *nothing* like a bit of consistency). New functions in version 2.1 ---------------------------- - New [[popup "Document keywords"]] policy and pre-processor [[goto Pre-processor command: KEYWORDS, KEYWORDS]] command. - New [[popup "Document description"]] policy and pre-processor [[goto Pre-processor command: DESCRIPTION, DESCRIPTION]] command. - New [[popup "Hyperlinks on Numbers"]] contents policy - New [[popup "Document style sheet"]] policy and pre-processor [[goto Pre-processor command: STYLE_SHEET, STYLE_SHEET]] command. Other changes in version 2.1 ---------------------------- _All versions_ - Now recognize domain names without a protocol specified (such as http:// or ftp:// etc.) that end in standard domains (e.g. .edu, .net, .org etc) as probable FTP sites. This allows references to sites like rtfm.mit.edu to be correctly turned into hyperlinks. - Some renumbering of this document has occurred - Quoted text is now marked up using <em>..</em> markup _Windows version_ - Now stores data in the Registry under the HKEY_CURRENT_USER root with a "\Software\JafSoft\AscToHTM\..." key - Now supports "most recently used" lists for both policy files and files to be converted. These are accessed via a drop-down Combo box. - Now remembers last source directory each time the program is run. This is used as the initial directory next time the Browse button is pressed. - The filenames now include the path. This is to allow the most recently used (MRU) file drop-down list to function correctly. $_$_HELP_CHAPTER 2,"Version 2.00 (October 1997)" Version 2.0 (October 1997) ========================== Version 2.0 marks the production of the first fully-windowed version for Windows 95/NT. This took a few months to be produced, so a fair number of other features have been added over this time. New functions in version 2.0 ---------------------------- - New [[popup "Output policy filename"]] policy - New [[popup "Use .HTM extension"]] policy - New [[popup "Generate diagnostics files"]] policy - New [[popup ""External contents list filename"]] policy - New [[popup "Use <DL> markup for defn. paras"]] policy - New [[popup "Ignore multiple blank lines"]] policy - New [[popup "Look for *this* and _that_ emphasis"]] policy - New [[popup "Allow definitions inside PRE"]] policy - New Pre-processor [[goto Pre-processor command: CONTENTS, BEGIN/END_CONTENTS]] command - New Pre-processor [[goto Pre-processor command: HTML, BEGIN/END_HTML]] command - New Pre-processor [[goto Pre-processor command: TITLE, TITLE]] command - New Pre-processor [[goto Pre-processor command: INCLUDE, INCLUDE]] command Other changes in version 2.0 ---------------------------- - White space immediately adjacent to PRE sections now ignored. - Changed anchor names to contain no spaces (makes URL's easier to quote) - Title defaults to "Converted from filename" instead of "No title" (see also 7.1.2) - Introduced some support for use of ctrl-H (backspace) in Unix documents to underlined and highlighted words - Automated "simple" file detection now attempted - Automated "code samples" detection now attempted - Some policies have been renamed as follows :- $_$_BEGIN_TABLE Was Now --- --- Expect Numbered sections Expect Numbered Headings HTML header HTML header file HTML footer HTML footer file $_$_END_TABLE - The policy section headings have been renamed as well. This may cause "ignored policy line" messages when old policy files are used. $_$_HELP_CHAPTER 2,"Version 1.1 (August 1997)" Version 1.1 (August 1997) ========================= New functions in version 1.1 ---------------------------- - Added a [[popup "Only use known groups"]] policy to improve accuracy of newsgroup hyperlink detection. - Added more document colour policies - Added a [[goto command line qualifiers: /POLICY, /POLICY]] and [[popup "Output Policy file"]] option to make the generation of an output policy file optional - Added pre-processor support for user-formatted sections Other changes in version 1.1 ---------------------------- - Indentation is now done using <BLOCKQUOTE> markup. - Changed default background colour to white. - Generation of a .pol file is no longer default - The use of <PRE> ... </PRE> to mark up user-formatted text is replaced by the new pre-processor commands [[goto Pre-processor command: PRE, BEGIN/END_PRE]] - re-write of section 4.1 - Improved error reporting. The .LIS file created if the [[goto command line qualifiers: /DEBUG, /DEBUG]] qualifier is used now has error and information messages included in it. $_$_HELP_CHAPTER 2,"Version 1.05 (late July 1997)" Version 1.05 (July 1997) ======================== New functions in version 1.05 ----------------------------- - Added an [[popup "Output policy file"]] policy. This allows the suppression of output policy files where not wanted. - Added a [[popup "Expect code samples"]] policy. This helps in technical documents that include samples of C code. - Added pre-processor support to allow variant documents to be produced (see [[GOTO Pre-processor policies]] and [[GOTO Using the pre-processor]]) Other changes in version 1.05 ----------------------------- - Policies now accept "Yes/No" as well as "True/False". "Yes/No" is now the default when outputting policies. - shareware version now limited to processing the first 500 lines only. - Lines with email addresses no longer have <BR>'s forced on the end. Lines with http, ftp and news links still do. This will become fully configurable in later versions. $_$_HELP_CHAPTER 2,"Version 1.04 (early July 1997)" Version 1.04 (July 1997) ======================== $_$_SECTIONM MAKINGRTFHELP - [[goto New functions in version 1.04]] - [[goto Other changes in version 1.04]] $_$_SECTION ALL New functions in version 1.04 ----------------------------- - Added policy [[popup "Minimum automatic <PRE> size"]]. This replaces the policy "Allow automatic 1-line <PRE>" - Added policies [[popup "Largest allowed <Hn> tag"]] and [[popup "Smallest allowed <Hn> tag"]] to allow control over generated heading sizes. - Added policy [[popup "Short line length"]] - Added batch processing to allow multiple files to be converted at the same time. Other changes in version 1.04 ----------------------------- - Created a 16-bit DOS version - VMS version now available as freeware. - Added "SendTo" tips for Windows 95/NT users section to the documentation. $_$_HELP_CHAPTER 2,"Version 1.01 (April 1997)" Version 1.01 (April 1997) ========================= - Added the [[goto command line qualifiers: /CONTENTS, /CONTENTS]] qualifiers. - Added the [[goto command line qualifiers: /SIMPLE, /SIMPLE]] qualifier. $_$_HELP_CHAPTER 1,"Ordering" $_$_HELP_SUBJECT "How to order your copy" Ordering your copy ****************** $_$_HELP_TOPIC_ID ID_ORDERING $_$_HELP_TOPIC_ID HIDD_ABOUTBOX AscToHTM costs $30 per copy. Anyone who buys a copy of AscToHTM may freely take backup copies, and install it on all their home machines, and one desktop and one portable at work. Details on how to register AscToHTM can be found on the web page http://www.jafsoft.com/asctohtm/register_online.html This URL is also shown on the "About" window. Discounts are available to anyone wishing to purchase multiple copies. Site licenses are also available. Users who register will also get access to the [[goto console version]] which may be better suited to batch processing or performing automated conversions Software developers wishing to incorporate AscToHTM's functions into their own systems may be interested in the [[goto API version]]. For more information, visit the web page, or email *info<at>jafsoft.com* $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION ALL What happens if I don't register the shareware version of AscToHTM? =================================================================== Originally I wanted to produce a fully-featured, but time-limited shareware version. However, for various reasons we've had to move to move to producing a largely-featured version with a 30 day time limit. Sorry 'bout that. At present the shareware version of the program expires 30 days after installation. Each time the program runs it will tell you how may days left you have. There are other limitations of the shareware version :- - If you don't register, it will cease to function properly after 30 days. Specifically after 30 days any conversions will convert all your text to UPPER case. This will still allow you to evaluate the software, but the resulting HTML will be of little use to you. - In the shareware version you're limited to only the first 500 lines of any source file. After 1000 lines a warning is placed in the output, and all subsequent lines are converted to upper case. This allows you to gain an impression of what the HTML will look like for evaluation purposes. - In the shareware version, wildcard conversions are limited to only 5 files - In the shareware the output is "watermarked" I don't like limiting the software, but people need reminding, so there you go. Upgrade Policy ============== $_$_HELP_TOPIC_ID ID_UPGRADES It is our intention to continue development of this product, and for as long as possible make upgrades available freely via the Internet to registered users at no cost. We can't actually promise this, but this is our intention. In any case we will reward early commitment by ensuring the cumulative cost of upgrades is never more that making a fresh first-time purchase. For example, this windowed version is offered as a free upgrade to those who bought the console version (at a lower price). Updates are listed on the web at http://www.jafsoft.com/asctohtm/updates.html Other products by the same author ================================= Other products by the same author include $_$_BEGIN_TABLE [AscToHTM] text-to-HTML converter, shareware $30 [AscToRTF] text-to-RTF converter, shareware $59 [AscToTab] text-to-Table converter for HTML and RTF, available as postcardware [Detagger] HTML-to-text converter, shareware $25 $_$_END_TABLE There's a lot of common technology between the three products (in terms of the conversion engine and the user interface), so if you like one, you should try the others. For more details visit the web site at http://www.jafsoft.com/products/ or email the author at *info<at>jafsoft.com* Contacts on the Web =================== *The home page* The [AscToHTM] home page is hosted on the [JafSoft] web site. *Feedback* E-mail any feedback to *info<at>jafsoft.com* (replace the "<at>" by "@"). Most people are pleasantly surprised to get a reply. Some are amazed at the short response time. Sadly, we cannot guarantee either :-) Support ======= A limited amount of support is available to registered users by emailing *info<at>jafsoft.com* (replace the "<at>" by "@"). Any enquiries should be directed to the same address. Sadly, we cannot guarantee any replies, though we do try to be helpful. Priority is given to people who have registered copies. $_$_HELP_CHAPTER 1,"Other versions of AscToHTM" Other versions ************** As well as the more conventional Windows version, AscToHTM functionality is now available in a number of additional forms to suit the special needs of users. $_$_SECTION MAKINGHTML *Contents of this section* $_$_CONTENTS_LIST 2,,2 $_$_SECTION ALL API version =========== For those wishing to call AscToHTM programmatically, an API has been developed. This is sold under separate license. Contact *info<at>jafsoft.com* if you're interested (replace the "<at>" by "@"). You can get more details and an evaluation copy from http://www.jafsoft.com/developers/api_demos.html The same API is used for all JafSoft converters. You can read more in the API documentation at http://www.jafsoft.com/doco/docindex.html Console version =============== Although AscToHTM is primarily offered as a Windows application, the program is also available as a console application which is made available at no extra cost to registered users. There are a number of command line options described in this document. The Windows version is also capable of accepting command line options. A console version is more suited to certain modes of batch processing, (for example it can use a steering data file, and won't get focus when executed). The conversion engine is identical in each case, it's just GUI-less. Please note this console version is *not* a DOS version, that is it will run in a "DOS" window under windows, but not on a system booted under DOS. Although available before to registered users, the console version is now also available for evaluation, due to it's popularity amongst those doing automated batch conversions to RTF. You can get more details and an evaluation copy from http://www.jafsoft.com/developers/console_demos.html Linux version ============= Linux versions of JafSoft converters have been successfully built as both command line programs, and in API form. Unfortunately JafSoft are unable to support Linux versions directly at the current time, and have only supplied versions in the past under a source code license. $_$_HELP_CHAPTER 1,"Documentation available" $_$_HELP_SUBJECT "Documentation available" Documentation available *********************** $_$_HELP_TOPIC_ID ID_HTMLDOCO A set of HTML documentation is maintained for AscToHTM. This is generated by AscToHTM and is expected to be more comprehensive, up to date, and easier to read than this help file (especially when wanting a broader view). You should have got a set of this documentation when you got your copy of AscToHTM, however you can get more recent versions by visiting the web site http://www.jafsoft.com/doco/docindex.html where you will also find instructions on how to get a .zip copy for your own use. This HTML documentation is, of course, entirely generated by AscToHTM itself. The text files used for the conversion are usually included in the .zip file. _Documents available_ *The “main program documentation”* This is the best overview of what the software does and how it works, It relies heavily in turn on the following documents. http://www.jafsoft.com/doco/a2hdoco.html *The “Policy manual”* Gives a description of using policies and policy files to tailor the program’s conversions. Includes a section listing all policies and their effects, including a few that can’t be set directly through the user interface of the Windows program. http://www.jafsoft.com/doco/policy_manual.html *The “Tag manual”* Gives a description of using the program’s pre-processor and tagging system that can turn the program from a useful conversion utility into a more serious web authoring tool. Includes a chapter on the use of HTML fragments. http://www.jafsoft.com/doco/tag_manual.html *The “FAQ”* Answers some commonly asked questions, and gives pointers as to how the program works (and why it sometimes doesn’t). Far from complete, it may at least give you a start on what to look at with your conversion problems. http://www.jafsoft.com/faq/a2hfaq.html This HTML documentation is, of course, entirely generated by AscToHTM itself, with no post-conversion editing. The text files used for the conversion are usually included in the .zip file. RTF versions of some of these documents are also available, converted by our text-to-RTF converter [AscToRTF]. $_$_HELP_CHAPTER 1,"Acknowledgements" $_$_HELP_SUBJECT "Impossible without..." Acknowledgements **************** $_$_HELP_TOPIC_ID ID_ACKNOWLEDGEMENT I'd like to thank all the people who have helped me produce AscToHTM and its related products. Although AscToHTM is a one-man programming effort, I really wouldn't have come this far without the support and encouragement of friends and users. I'd like to thank my beta testers Naz Alam, Roy Vernon and Gonzalo San Martin. Special thanks go to Elliott Roper and all at Yezerski Roper for their tremendous support during the software's development. A special thanks to the people who volunteered to translate aspects of the software into other languages for the benefit of users. For a full list see [[goto Language menu]] Finally, my biggest thanks are to my registered customers who keep asking me for features that would never even have occurred to me. If you think AscToHTM has too many options, I can assure you that each and every one of them has been added for a reason and is being used by some happy customer or other. $_$_SECTION MAKINGRTFHELP Topic not covered in this document ********************************** $_$_HELP_TOPIC_ID HID_ANAL_BULLETS $_$_HELP_TOPIC_ID HID_ANAL_CONTENTS $_$_HELP_TOPIC_ID HID_ANAL_FILESTRUCT $_$_HELP_TOPIC_ID HID_ANAL_HEADINGS $_$_HELP_TOPIC_ID HID_ANAL_LAYOUT $_$_HELP_TOPIC_ID HID_ANAL_LOOKFOR $_$_HELP_TOPIC_ID HID_ANAL_PREFORM $_$_HELP_TOPIC_ID HID_ANAL_TABLE $_$_HELP_TOPIC_ID HID_CONFIG_HTMLFRAG $_$_HELP_TOPIC_ID HID_CONFIG_LINKDICT $_$_HELP_TOPIC_ID HID_CONFIG_SDF $_$_HELP_TOPIC_ID HID_CONFIG_TDF $_$_HELP_TOPIC_ID HID_CONFIG_TEXTSUBS $_$_HELP_TOPIC_ID HID_DUMMY_MENU $_$_HELP_TOPIC_ID HID_FILE_CONVERT $_$_HELP_TOPIC_ID HID_FILE_EXIT $_$_HELP_TOPIC_ID HID_HELP_ABOUTXXXTOXXX $_$_HELP_TOPIC_ID HID_HELP_CONTENTS $_$_HELP_TOPIC_ID HID_HELP_HTML $_$_HELP_TOPIC_ID HID_HELP_HTML_NET $_$_HELP_TOPIC_ID HID_HELP_REGISTER $_$_HELP_TOPIC_ID HID_MERRILL $_$_HELP_TOPIC_ID HID_OUT_FILE_CONTENTS $_$_HELP_TOPIC_ID HID_OUT_FILE_DIRECTORY $_$_HELP_TOPIC_ID HID_OUT_FILE_FILE $_$_HELP_TOPIC_ID HID_OUT_FILE_FRAMES $_$_HELP_TOPIC_ID HID_OUT_FILE_GENERATION $_$_HELP_TOPIC_ID HID_OUT_FILE_NAMES $_$_HELP_TOPIC_ID HID_OUT_HTML_ADDED $_$_HELP_TOPIC_ID HID_OUT_HTML_HYPERLINKS $_$_HELP_TOPIC_ID HID_OUT_HTML_LINKDICT $_$_HELP_TOPIC_ID HID_OUT_HTML_STYLE $_$_HELP_TOPIC_ID HID_OUT_MISC_PREPRO $_$_HELP_TOPIC_ID HID_OUT_OVERVIEW $_$_HELP_TOPIC_ID HID_OUT_RTF_SETTINGS $_$_HELP_TOPIC_ID HID_OUT_STYLE_COLOURS $_$_HELP_TOPIC_ID HID_OUT_STYLE_CSS $_$_HELP_TOPIC_ID HID_OUT_STYLE_FONT $_$_HELP_TOPIC_ID HID_OUT_STYLE_HTML $_$_HELP_TOPIC_ID HID_OUT_TABLE_TABLE $_$_HELP_TOPIC_ID HID_POLICIES_ANALYSIS $_$_HELP_TOPIC_ID HID_POLICIES_CHANGE $_$_HELP_TOPIC_ID HID_POLICIES_LOAD $_$_HELP_TOPIC_ID HID_POLICIES_OUTPUTTOHTML $_$_HELP_TOPIC_ID HID_POLICIES_RELOAD $_$_HELP_TOPIC_ID HID_POLICIES_RESETTODEFAULTS $_$_HELP_TOPIC_ID HID_POLICIES_SAVE $_$_HELP_TOPIC_ID HID_PROD_ASCTOHTM $_$_HELP_TOPIC_ID HID_PROD_ASCTORTF $_$_HELP_TOPIC_ID HID_PROD_ASCTOTAB $_$_HELP_TOPIC_ID HID_PROD_DETAGGER $_$_HELP_TOPIC_ID HID_PROD_JAFSOFT $_$_HELP_TOPIC_ID HID_REANALYSE $_$_HELP_TOPIC_ID HID_REMEMBER_SETTINGS $_$_HELP_TOPIC_ID HID_RTF_CONTENTS $_$_HELP_TOPIC_ID HID_RTF_DOCUMENT $_$_HELP_TOPIC_ID HID_RTF_FORMATTING $_$_HELP_TOPIC_ID HID_RTF_HELP $_$_HELP_TOPIC_ID HID_RTF_LINKDICT $_$_HELP_TOPIC_ID HID_SETTINGS_DIAGNOSTICS $_$_HELP_TOPIC_ID HID_SETTINGS_DOCO $_$_HELP_TOPIC_ID HID_SETTINGS_DRAG $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_DUTCH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_ENGLISH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_FRENCH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_GERMAN $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_ITALIAN $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_OTHER $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_PORTUGUESE $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_SPANISH $_$_HELP_TOPIC_ID HID_SETTINGS_LANGUAGE_SWEDISH $_$_HELP_TOPIC_ID HID_SETTINGS_LOADLANG $_$_HELP_TOPIC_ID HID_SETTINGS_POLICY $_$_HELP_TOPIC_ID HID_SETTINGS_VIEWER $_$_HELP_TOPIC_ID HID_SHOW_RESULTS $_$_HELP_TOPIC_ID HID_SHOW_STATUS $_$_HELP_TOPIC_ID HID_SHOW_TIPSONSTARTUP $_$_HELP_TOPIC_ID HID_SHOW_TOOLTIPS $_$_HELP_TOPIC_ID HID_UPGRADE $_$_HELP_TOPIC_ID HID_VIEW_LASTCONVERSION $_$_HELP_TOPIC_ID HID_VIEW_MESSAGES $_$_HELP_TOPIC_ID HIDD_CHOOSE_LANGUAGE $_$_HELP_TOPIC_ID HIDD_DETAG $_$_HELP_TOPIC_ID HIDD_DETAG_TABLES $_$_HELP_TOPIC_ID HIDD_EXPIRED $_$_HELP_TOPIC_ID HIDD_FILESPLIT_RTF $_$_HELP_TOPIC_ID HIDD_HEADING_LEVELS $_$_HELP_TOPIC_ID HIDD_HTML_FRAGMENTS $_$_HELP_TOPIC_ID HIDD_MAKEHELP $_$_HELP_TOPIC_ID HIDD_MERRILL $_$_HELP_TOPIC_ID HIDD_RTF_DOCUMENT $_$_HELP_TOPIC_ID HIDD_RTF_FORMAT $_$_HELP_TOPIC_ID HIDD_RTF_SETTINGS $_$_HELP_TOPIC_ID HIDD_SDF_FILE $_$_HELP_TOPIC_ID HIDD_SETTINGS $_$_HELP_TOPIC_ID HIDD_SETTINGS_SINGLEVIEWER $_$_HELP_TOPIC_ID HIDD_SPLASH $_$_HELP_TOPIC_ID HIDD_STATIC $_$_HELP_TOPIC_ID HIDD_TAG_MANIPULATION $_$_HELP_TOPIC_ID HIDD_Template $_$_HELP_TOPIC_ID HIDD_TEXT_FRAGMENTS $_$_HELP_TOPIC_ID HIDD_TEXT_MARKERS $_$_HELP_TOPIC_ID HIDD_TEXT_MISC $_$_HELP_TOPIC_ID HIDD_TEXT_PARAGRAPHS $_$_HELP_TOPIC_ID HIDD_TEXTFORMAT $_$_HELP_TOPIC_ID HIDD_TEXTLINK $_$_HELP_TOPIC_ID HIDD_TEXTTABLE $_$_HELP_TOPIC_ID HIDR_ACCELERATOR1 $_$_HELP_TOPIC_ID HIDR_ASCTOHTM $_$_HELP_TOPIC_ID HIDR_MAINFRAME $_$_HELP_TOPIC_ID HIDR_MENU1 $_$_HELP_TOPIC_ID HIDR_MENU2 $_$_HELP_TOPIC_ID HIDR_MENU_ASCTOHTM $_$_HELP_TOPIC_ID HIDR_MENU_ASCTORTF Sorry, there’s no such topic in this particular help file. You can see a [[goto Complete contents list for this document]]. $_$_SECTION_ALL