Cloanto AmiToRTF v. 4.2 Introduction AmiToRTF can extract text from a variety of Amiga document formats, and save data in the Rich Text Format (RTF, ".rtf" file name suffix) or as plain text (ISO 8859-1 "ASCII", ".txt" suffix). The resulting files can easily be loaded by the most common programs under different operating sysytems. AmiToRTF was written as an Amiga Rexx script which interacts with Cloanto's Personal Write (version 4.2 or higher) word processor, which is included and launched automatically by AmiToRTF. AmiToRTF can extract texts from the following file formats: - Amiga ANSI - Amiga IFF-FTXT - ASCII (Amiga, DOS, Mac, Atari, CBM, C-64, 7-bit ASCII and others) - Cloanto Personal Write (FTXT, compressed, encrypted) - Cloanto C1-Text (FTXT, compressed, encrypted) - PowerPacker (compressed, encrypted) - Documents created by ProWrite, FinalWriter and Wordworth - Unrecognized formats Most formats are recognized automatically, and do not require user intervention. Texts in one of the PowerPacker formats can only be loaded if the "powerpacker.library" is installed in the system (this library is not included with AmiToRTF). Please refer to the section titled "Advanced Options" for instructions on how to set the program to load non Amiga-ASCII texts. AmiToRTF tries to preserve paragraph and style data (bold, italic, etc.). Other attributes are not processed. After conversion, the "Comment" field inside each RTF document contains additional information about the source data (original file location and date, etc.). AmiToRTF can convert a single file, or all the files in a directory and all its subdirectories. Documents can be converted in a way that the original (Amiga) files are preserved in the same location as the new files, or leaving only the new files. To launch AmiToRTF, double-click on its icon. A warning requester will appear, recommending to back-up all data before processing. After this, the most important options are available from an extended file requester. If a single file is selected in the file requester, then AmiToRTF will process only that file. If instead the File field is left empty, then AmiToRTF will process all files in the selected directory (and subdirectories). If encrypted files are found (Personal Write, C1-Text or PowerPacker), the script automatically asks for a key, if not already set. If more than one key is used in different files, then the files must be grouped and processed one key at a time, each time with the single correct key. AmiToRTF cannot use different encryption keys in a single run. The preset configuration (all four file requester settings to YES) is recommended for most applications, and will create a ".rtf" or ".txt" copy of each text file, or just rename some files if no further action is necessary. No original Amiga files are changed or lost with these settings (only some text files may be renamed, if both "Reuse ASCII files" and "Apply Windows names" are selected). An alternative configuration could be to set the first option to NO, and all other settings to YES. In this case, it is recommended to leave the original Amiga files in their original location, and to apply AmiToRTF to a copy of the files. The following sections explain the available options. Preserve Amiga Files This option determines whether AmiToRTF should preserve the original Amiga files, or not. If this option is set to NO, then only the RTF or TXT version of each file remains in the directory (not the original Amiga text files) after conversion. If this option is set to YES, it is recommended to also activate "Apply Windows Names". When converting data with AmiToRTF, it is always recommended to keep a copy of the original files, so that they can be loaded with an Amiga program, either on a real Amiga or in an emulation environment. The decision to take is in general whether to keep the original Amiga documents in the same directory tree as the converted documents, or to keep them separate. Accordingly, this option should be set to YES or NO. In the second case, a copy of all data must be made before processing, because AmiToRTF will overwrite all original files. Reuse ASCII Files If this option is enabled, AmiToRTF will detect and preserve plain text files as they are (without re-saving them). Text files are all files containing only text in the Amiga character set (but not style control sequences), and the special characters LF, CR and TAB. If this option is disabled, then the files still end up as text files, but they are loaded and saved, which, depending on the current program settings (see "Additional Settings"), may mean that some characters are converted. This usually occurs with horizontal tabs and with end-of-line characters, which by default AmiToRTF saves as (expanded) spaces and a single LF, respectively. Regardless of this setting, ASCII files are never saved as RTF (Rich Text Format), but always as TXT (plain text) files. Apply Windows Names When this option is enabled, AmiToRTF makes sure that the file name of the converted documents is legal under Windows, and that the name ends with a suffix which reflects the file type, i.e. ".rtf" or ".txt". Skip Existing RTF Files If this option is set, then existing RTF files are not processed, but thay are left as they are. This setting is in general required because AmiToRTF cannot load RTF files, but only save in this format. If "Apply Windows Names" is set, then RTF documents are always renamed, if necessary. Advanced Options In addition to the main four settings, which are specific to the action of AmiToRTF, Personal Write (which is used by AmiToRTF) offers some additional settings which can be used to affect the conversion. To change the default settings of Personal Write, select CANCEL in the file requester which appears after starting AmiToRTF. Then change the settings, and re-start AmiToRTF without exiting from Personal Write. The "File Format/Defaults..." menu item displays a requester in which the first three settings may be of interest to customize AmiToRTF. End of Line/Paragraph: The Line Feed (ASCII LF, decimal code 10) code is normally used by the Amiga and by Personal Write to mark the end of a line or a paragraph. If the text is to be stored in a format that requires different end of paragraph/line codes, this can be specified with the parameter which is described here. The three gadgets which can be selected activate respectively the LF, CR and CR+LF end of paragraph/line codes. CR stands for Carriage Return (decimal ASCII code 13). When Personal Write loads a text file all different end-of-line codes are translated to LF codes. TAB Step: Some programs use the TAB code (ASCII code 9, also called HT, meaning "Horizontal Tab") to replace a series of space characters in a file. A TAB code inserted in a file tells the program that the following character must be placed on the next TAB position when displayed. This saves space characters. Standard TAB positions normally appear every 8 columns. This means that there are TAB positions on column 1, 9, 17 etc. If a TAB step other than 8 is defined, the positions are re-distributed accordingly. The step which can be defined through this parameter is used by Personal Write to interpret the meaning of TAB codes found in text files. TABs in Output File: TAB codes are, by default, not inserted in the files stored by Personal Write. If the YES gadget is selected, TAB codes will be used wherever possible when texts are stored in the ASCII or ANSI X3.64 formats. If the AUTO option is selected, TABs are only saved if they appeared in the file being loaded. Otherwise, Personal Write saves space characters instead. The "File Format/Encryption Key..." menu item can be used to manually enter a new encryption key. Normally, AmiToRTF displays a prompt to ask for a key only when necessary (if an encrypted file is found), and if no key was used before. If a key is already set, then it must be changed manually, if necessary. The last important option which it may be useful to change is the character set used by Personal Write to interpret the text file which is loaded. The AmiToRTF tool always saves texts using the standard ISO 8859-1 character set, which is used both by the Amiga and by Windows (since Windows 95). By changing this setting, it is possible to load non-Amiga/non-Windows text, and save them using the ISO 8859-1 character set. AmiToRTF by default explicitly resets certain Personal Write values, so that the program is ready to load Amiga texts. If the default character set used for loading texts is to be changed, then one line of the AmiToRTF Rexx program needs to be removed, so that the new setting made in Personal Write is not cleared by AmiToRTF. To do this, load the "AmiToRTF" file using a text editor (or even with Personal Write), delete the line which says "RTFResetOptions", and re-save the file. Even with this change, AmiToRTF will continue to work normally, if the Personal Write settings are changed with some care. Once AmiToRTF has been modified, the character set can be changed using the "File Format/Character Set..." menu item, as explained in the following. The first four gadgets refer to the most commonly used character sets on the systems whose name is displayed. Newer versions of Windows use the same character set as the Amiga (ISO 8859-1). The IBM PC set (Code Page 437), mainly used by DOS and older versions of Windows, can also be used to process the text output by an Amiga printer driver, redirected to a file with the "Cmd" program. This character set is the most widely used among personal printers, but some printers (e.g. HP LaserJet) may use other encodings. The following eight sets are those of the Commodore CBM and C64 computers. These computers have two sets of screen character codes (SCR1 and SCR2), and two sets of text mode codes (CHR1 and CHR2). The first two sets are those which can be used to display characters on the screen with the "Poke" Basic command. The other two sets can be printed with the "Chr$()" command. Other two gadgets, with the same names as the standards, follow in the list. Code Page 850 (CP 850 gadget) is the character set used on operating systems such as OS/2. Code Page 850 has more national characters than CP 437 ("old PC"). The last 12 gadgets refer to the national 7-bit ASCII codes. In these sets, the most commonly used national characters of each language are inserted in place of some less used characters (e.g. '[' and '\') of the standard ASCII set (i.e. 7USA). More complex conversions are also possible. If, for example, a text written using a Commodore CBM 8xxx computer with German keyboard has to be read, the text can first be processed using the CBM gadget associated with the character codes used by the program which originally saved the text (e.g. CBM SCR1). Then, the text can be processed a second time selecting the 7DEU gadget (to translate German national characters). In some cases, Personal Write cannot convert one or more characters from one set to another. This may occur if the selected character set does not contain all the codes which should be read or written. In these cases, Personal Write replaces the character which cannot be converted with a similar one. Personal Write can also expand the character into a series of multiple characters (e.g. 'ß' becomes "ss", and the "one half" sign is expanded to '1'+'/'+'2'). Diacritical signs are removed from the letters if no conversion into the selected set is possible.