¢ =================================¢ B T C 1 . 0¢ (Bewesoft's Text Converter)¢ By Jiri Bernasek - BEWESOFT 1999¢ =================================¢¢¢BTC is a tool for converting texts between different codes. It gives a simple solution when you've problems with transfering text files between different systems or programs.¢As you know, almost all software on all computers use the ASCII code for storing texts. But unfortunately, there are lots of different modifications of this standard, and so it's sometimes quite difficult to transfer your files from one system to another. If you've already seen a text file from PC displayed on Atari XL/XE, or if you've tried to send a BASIC listing with control-graphics characters to an EPSON printer, then you surely know what am I talking about. And if you're using a language other than English, and so you need some special characters which are not in the original ASCII code, then it's almost easier to write the text again, than to transfer the file and repair problems with a text-editor...¢¢BTC allows you to easily convert texts between any codes you want. All you need is the BTC.COM program file, and a matching definition-file for the code-conversion you want. These definition-files are in fact ASCII text-files (you can create your own definitions or change them with almost any text editor). BTC allows you to define:¢--- Simple byte-to-byte conversion (of course)¢--- Byte-to-string expansion¢--- String-to-string replacing¢--- Simple operations (+/-/AND/OR/EXCLUSIVE-OR) on data-bytes¢--- Wildcards or number-range for source string searching¢--- Expanding TABs to spaces, with user-defined TAB positions¢--- Text re-formatting in one of 3 possible modes, up to 255 characters per line¢--- Adding headers at the begin and the end of file¢--- All strings and numbers may be defined as decimal, hexadecimal or binary number(s), as a string, or as a "byte*amount" multiplication.¢¢¢ HOW TO USE THE PROGRAM¢ ======================¢¢BTC should run with almost any DOS, when it allows opening of two files at a time, and MEMLO isn't higher than $5200 (valid for BTC version 1.0). As far as I know, all existing DOSes are OK for this specification. BTC doesn't use OS-RAM, and also the bank-select memory (Ramdisk) isn't affected.¢¢With SpartaDOS or BW-DOS, the BTC works just like any other external command. The syntax is:¢¢ BTC source destination [definition]¢¢(The "[ ]" brackets are marking optional parameters.)¢¢Note: With SpartaDOS or BW-DOS, BTC will stop any running batch file in the case of an error-message - to prevent problems (for example: erasing source files that haven't been successfully converted).¢¢With any other DOS, you should just run the BTC.COM file. You'll be then prompted to enter the three filenames from keyboard.¢¢After accepting the parameters, BTC will read and compile the definition file. Mostly it's finished very quickly, but when the definition is very long or complicated, it'll take several seconds, and you may even get the "Out of memory" message - try to remove all cartridges, and disable interanl BASIC in this case (to increase buffer-size).¢Then, the text-conversion itself begins. There's no limit on the size of converted files - BTC reads and writes long files part-by-part. When the definition is more complicated, the delays between reading and writing may increase to several seconds.¢¢All the three filenames may be entered without of drive numbers and extensions - in this case the standard settings will be used: .TXT extension for source/destination files, .BTC for the definition file, the working drive under SpartaDOS or BW-DOS, or D1: under an other DOS. When the name of definition file is not entered, the program will use DEFAULT.BTC (this allows a simplified syntax for most often used conversion-type, when you rename or copy the definition to DEFAULT.BTC).¢¢The definition files are usually named as "xxx2yyy.BTC", where "xxx" and "yyy" are abbreviations for source and destination codes. The files supplied with BTC use the following abbreviations:¢¢ATA - Full ATASCII, including all inverse and graphics characters.¢ASC - Pure 7 bit ASCII, without of any special characters, but with the Atari XL/XE EOL ($9B). Should be easily printable on any printer accessible from the XL/XE system (i.e. with a kind of EOL conversion), as well as on the screen.¢ATM - ATMAS II. source files¢PC - The standard IBM PC ASCII code (the oldest version for USA - according to my printer's manual it's "PC437").¢EED - The text files from ENERGY EDITOR. This editor is often used for disk-magazine articles in Poland.¢¢Note: Definitions for more codes are contained in the CZECH.ARC archive. This archive contains some files especially for use in the Czech republic: Czech version of this text, and definitions for converting some specific Czech codes.¢¢Example: To convert the file EXAMPLE.TXT in full ATASCII into TEMP.TXT in the IBM PC ASCII code (under SpartaDOS or BW-DOS), you should type:¢¢ BTC EXAMPLE TEMP ATA2PC¢¢(The files EXAMPLE.TXT, BTC.COM, and ATA2PC.BTC should be in the working directory.) If you're converting files in this way very often, you can rename ATA2PC.BTC to DEFAULT.BTC, and then you can do the same conversion using a simplified syntax:¢¢ BTC EXAMPLE TEMP¢¢¢ HOW TO CREATE A DEFINITION¢ ==========================¢¢The definition files are ASCII text files, so you can create them with almost any text editor. (The Atari XL/XE EOL ($9B) must be used.)¢¢Note: BTC does accept the full ATASCII, so all the commands and numbers may be normal/inverse upper/lower-case - excepting the quote at the end of a string (inverse quote isn't terminating the string). But still it's strongly recomended to use only standard ASCII characters (no inverse, no graphics and control characters, better upper-case), to allow easy viewing and printing with all the different text-editors and printers.¢¢Names of the definition-files should match the model "xxx2yyy.BTC", as mentioned above. (Actually, the name needn't to be in this form, but any "random" names are not so easy to understand...)¢¢When your new definition is finished, you should test it using the BTC (simply use it for a test-conversion). BTC will report any errors found in the definition file, together with the number of line in the file. (Only the first error in the file is reported, so you should test it again after removing the error.) It's also good to analyze the result of a test-conversion to be sure, that all the code-conversions are defined correctly. Remember that BTC doesn't report errors like "34" instead of "43" - only the syntax is tested.¢¢¢ The Syntax¢¢Each line in the definition file may define a code-conversion, contain a special command (see later), or a comment after ";". Empty lines and spaces (even ATASCII TAB $7F) may be used (outside quotation marks) where you want to improve readability of your file, and will be ignored by BTC.¢¢Examples:¢ 13>155/EOL;No spaces¢ 13 > 155 /EOL ;This is the same¢ 1 3 > 1 5 5 / e o l ;Also the same¢ 13>"[ C R ]";Here the spaces ARE present in the string!¢ ; Comment line...¢¢All parameters (numbers or characters) may be defined as a decimal number, a hexadecimal number after "$", a binary number after "%", or as a string inside " " or ' ' quotation marks. The numbers are limited to a single byte (0-255), while strings may be up to 128 characters long (where allowed). A string containing only one character is a valid replacement for any numeric parameter.¢¢Examples:¢ SETTAB 33 ;All these¢ SETTAB $21 ;lines are¢ SETTAB %100001 ;actually¢ SETTAB "!" ;the same!¢ SETTAB '!'¢¢¢ Code-conversion lines¢¢The basic syntax of a line that define a code-conversion is:¢¢ source > [destination] [/EOL] [;comments]¢¢When the "source" string is found in the source file, it'll be replaced with the "destination" string in the destination file, or simply ignored when "destination" isn't defined. (The "/EOL" parameter will be described later.)¢¢Note: All characters that don't match any definition will be copied into the destination file without of any changes.¢¢Both the "source" and "destination" strings may be combined from multiple numbers or strings as follows:¢¢ string[*amount][,string[*amount]]...¢¢When the "*amount" parameter is present (where "amount" is a number between 1 and 255), the string will be repeated that number of times.¢¢Note: Both "source" and "destination" strings are limited to max. 255 characters (in its compiled form, i.e. with all the "*amount" multiplications executed).¢¢Examples:¢ 13 > $9B ;Convert CR to ATASCII EOL¢ 13 > $9B*2 ;Convert CR to double ATASCII EOL¢ 13 > "[EOL]",$9B*2 ;Convert CR to "[EOL]" text, followed by two ATASCII EOLs¢ 13>"(","EOL"*4,")" ;Convert CR to "EOL" text repeated four times and closed inside round brackets¢ 13 > '"EOL"' ;Convert CR to "EOL" inside quotation marks (the use of '...' string definition allows you to use the quotation marks inside the string)¢ 13,10,13,10 > 155 ;Convert double CR/LF to ATASCII EOL¢ "Good bye" > "Bye" ;Replace string "Good bye" with "Bye"¢ $FF*16 > ;Ignore a string of 16 characters with the code $FF¢¢The "source" definition may also contain a special wildcard "?" instead of a string - it means "any character".¢¢Examples:¢ "A",? > "All" ;Replace "A" followed by any character with "All"¢ "(",?*5,")" > "()" ;Delete any string of 5 characters, when it's inside round brackets¢¢Another way of "source" definition is a range "number1-number2". Such a definition is valid for all codes between the two numbers (including these). Only single bytes are allowed in this kind of definition.¢¢Example:¢ 0-$1F > "." ;Convert all characters with codes under $20 (non-printable characters) into dots¢¢Note: You may define exceptions from "range" or "wildcard" type definitions by putting another lines AFTER that definition. The "source" string must be the same (or greater) length.¢In general, longer "source" strings have higher priority than shorter ones. When the length is the same, the later defined strings have the priority. (The "range" definitions are taken as a single byte definition for each matching byte.) Any strings with a wildcard at the first position are tested after all other ones.¢¢Examples:¢ 0-$FF > "." ;Convert all characters into dots¢ "A" > "?" ;But "A" into the question mark!¢¢ "A" > "?" ;The same as above. The wildcard at first¢ ? > "." ;position is tested after everything else.¢¢ "A" > "?" ;The second line have priority, so "A"¢ 0-$FF > "." ;will be also converted to a dot!¢¢ "#" > ;Delete all "#" characters¢ "#1" > "#1" ;But not before "1"!¢¢ "#",? > "#" ;Delete any character after "#"¢ "#9" > "#9" ;But not the "9" !¢¢The "destination" definition may contain the following special commands (instead of a string):¢ "=" - One character without of change (i.e. taken from the same position in the string, that was found in the source file)¢ "-" - No character¢ "I character" - Insert one character without of moving source string pointer¢ "+ number" - Add the number to original character from source file¢ "- number" - Subtract the number from original character¢ "& number" - Bitwise AND with the original character¢ "! number" - Bitwise OR¢ "@ number" - Bitwise EXCLUSIVE-OR¢ "TAB" - The tabulator (explained later)¢¢Examples:¢ "a"-"z" > -$20 ;Convert lower-case to upper-case¢ "(",?,")" > -,= ;Convert any single character inside round brackets to the same character without of brackets¢ "0"-"9">I"(",=,")" ;Put every number inside round brackets¢¢¢ The Tabulator¢¢When you define "TAB" in the "destination" definition, it'll be replaced with a variable number of spaces (min. 1), to position the next character right on the next tabulation-mark. By default, these marks are at each 8th position, and the space-character is $20. You can change it using the following special command:¢¢ SETTAB [SPC number,] number [,number]...¢¢The number after "SPC" (if present) is a new space-character, all the other numbers are the tabulation positions (0-254 allowed). You may use this command several times to define more positions, than what'll fit on a single line (depending on the text-editor you're using - BTC have no limit on line length), but it's senseless to define the space character more than once - only the last definition will be used. Once you define any tabulation position, the default positions (each 8th) are cancelled.¢¢Note: The tabulator operates on destination file (before text formatting - explained later), so the space-character should be in the destination code. All the string-replacements defined by code-conversion lines are executed before the tabulation.¢¢For correct function of the tabulator, you must define which characters (or strings) are terminating text-lines (the EOLs - returning the position to zero). This is done using the "/EOL" parameter.¢¢Example:¢ 13,10 > $9B /EOL ;Convert CR/LF to ATARI EOL, and terminate line¢ $9B > = /EOL ;Leave the character unchanged, but terminate line¢¢Note: The "/EOL" parameter is the same for the tabulator and text-formatting (explained later). There's no way how to set an "/EOL" for the tabulator but not for text-formatting. Any characters generated by a line with "/EOL" are standing outside normal text-positions, and so such a line may not contain a "TAB".¢The right margin, as set for text-formatting (explained later), is allways taken as a tabulation position. When no formatting is active, the tabulation uses lines of 255 characters (so that on longer text-lines, the position 255 is allways a tabulation position, and then all the previous positions will repeat - moved from 0 to 255). For example:¢¢SETTAB 128 ;The tabulation positions will be 128, 255, 383, 510, 638, 765, 893 etc...¢¢Examples:¢¢*** Definition ***¢"-" > TAB ;Uses the default settings¢$9B > = /EOL ;EOL terminates the tab-lines¢*** Source ***¢A-BB-CCC-DDDD¢EEEEE-FFFFFF-GGGGGGG-H¢IIIIIIII-JJJJJJJJJ¢*** Destination ***¢A BB CCC DDDD¢EEEEE FFFFFF GGGGGGG H¢IIIIIIII JJJJJJJJJ¢¢*** Definition ***¢SETTAB SPC"_",5,7¢SETTAB 9,21,30,35¢"-" > "\",TAB,"/"¢$9B > = /EOL¢*** Source ***¢A-B-C-D-E-F¢Atari XL/XE-BTC 1.0-!¢*** Destination ***¢A\___/B\_/C\_________/D\______/E\__/F¢Atari XL/XE\_________/BTC 1.0\_____/!¢¢¢ Text Formatting¢¢The Text formatting function allows you to reduce the length of single text-lines to a defined limit. When a longer line is found in the text-file, BTC will insert an extra end-of-line character. Text formatting is set up with the following command:¢¢ FORMAT mode line_length [,space_character]¢¢The "line_length" (1-255 allowed) and "space_character" (default is $20) are numbers, while "mode" is a single letter:¢¢ "N" - No text formatting (default). No more parameters are allowed after "N" !¢ "C" - Character-oriented formatting. Works just like the output to screen - simply inserts an extra EOL when the line is full.¢ "W" - Word-oriented formatting. Works like most text-editors do - replacing spaces with EOLs, and so never dividing words into parts. Also removes extra spaces between words (but any spacing at the left margin isn't affected). Lines shorter than the limit are not changed. When a word is longer than the line-length limit, it'll do the same as the mode "C" (divide the word).¢ "R" - Word- and right margin-oriented formatting. The same function as "W", plus adding extra spaces between words to keep the right margin constant on every lines.¢¢Note: The space-character for text formatting is independent of the space-character for the tabulator, and should be in the destination code. All the string-replacements and tabulations defined by code-conversion lines are executed before the text formatting. When the space-characters for tabulation and text formatting are the same, and the "W" or "R" modes are used, then the tabulation on long lines will be affected by the text formatting (extra spaces deleted). If you've used the "FORMAT" command more times in the same file, only the last one is valid.¢¢For correct text-formatting, you must define the end-of-line character(s) in the same way, as for the tabulator (the "/EOL" parameter).¢¢The extra EOLs generated by text-formatting function may be different (so called "soft EOLs"). By default, the soft EOL is the code $9B (ATARI EOL), but it may be changed with the following command:¢¢ EOL > destination¢¢In this way, you can define any code or string to be generated as soft EOL.¢¢Note: Such characters are standing outside normal text positions, and so may not contain the TAB. (Also commands related to source data (=+-&!@) aren't allowed. The "-" (no character) and "I" (insert character) commands are possible, but senseless in this case.)¢¢Examples:¢*** source ***¢ This is an example of text file for the demonstration of BTC.¢A short line.¢A very long word: This_word_is_50_characters_long_without_any_space!¢¢*** definition ***¢FORMAT C 30¢$9B > = /EOL¢*** destination ***¢ This is an example of text f¢ile for the demonstration o¢f BTC.¢A short line.¢A very long word: This_word_is¢_50_characters_long_without_an¢y_space!¢¢*** definition ***¢FORMAT W 30¢$9B > = /EOL¢*** destination ***¢ This is an example of text¢file for the demonstration of¢BTC.¢A short line.¢A very long word:¢This_word_is_50_characters_lon¢g_without_any_space!¢¢*** definition ***¢FORMAT R 30¢$9B > = /EOL¢*** destination ***¢ This is an example of text¢file for the demonstration of¢BTC.¢A short line.¢A very long word:¢This_word_is_50_characters_lon¢g_without_any_space!¢¢*** definition ***¢FORMAT W 30¢$9B > = /EOL¢EOL > "**",$9B¢*** destination ***¢ This is an example of text**¢file for the demonstration of**¢BTC.¢A short line.¢A very long word:**¢This_word_is_50_characters_lon**¢g_without_any_space!¢¢¢*** definition ***¢FORMAT W 35 ;This will remove single EOLs, and re-format¢$9B*2 > = /EOL ;the text. Only double EOLs (empty lines) will¢$9B > " " ;be accepted, and changed to single EOLs.¢*** source ***¢This is a file¢formatted to 20¢chars/line.¢¢This is after empty¢line.¢*** destination ***¢This is a file formatted to 20¢chars/line.¢This is after empty line.¢¢¢ Adding Headers¢¢If you want to add a kind of header at the begin, or at the end of destination file, just define one or both of the following:¢¢ START > destination¢ END > destination¢¢The "destination" string will be inserted at the begin (end) of the file.¢¢Note: The "destination" string may not contain any commands related to source data (=+-&!@). TAB is possible.¢¢¢ THE SUPPLIED FILES¢ ==================¢¢Inside the archive BTC.ARC you should find all the files listed below. If you didn't get some file(s), then the archive isn't in its original version, as sent from the author. Almost all the supplied definition files (*.BTC) are commented, so you can view them (using a text-editor, or just by copying them to "E:"), and look how these definitions are written...¢¢BTC.COM - The program-file¢BTC.DOC - This text¢¢ASC2ATM.BTC, ATA2ASC.BTC, ATA2PC.BTC, ATM2ASC.BTC, EED2ASC.BTC, PC2ATA.BTC - Definition files for the most common codes. It's possible that you'll need to edit the files a bit before it match your personal needs. (For example, the ATA2PC definition converts from ATASCII to the PC ASCII, including a part of the graphics characters (the ones that are also on the PC), but double CR/LF end-of-line codes are generated to prevent PC text-editors from re-formatting the text. If you want to use this definition for direct printing, you may need to change the EOLs to single CR/LF, or even only CR (if you've the AUTO FEED function set on your printer, as necessary for most XL/XE printer interfaces), to remove extra empty lines in the printout.)¢¢EPSUBSCR.BTC - This definition demonstrates the use of adding headers, and text re-formatting. It's designed to print common documentation files at 137 characters per line, on EPSON compatible printer (just try "BTC file P: EPSUBSCR"). The definition tells BTC to switch the printer to condensed-subscript mode before sending the actual data, re-format the text (remove single EOLs to override the original 40 column formatting, but accept double EOLs, and then add new EOLs for 137 chars/line without of dividing words into parts), and at the end, reset printer to the standard mode.¢¢ATAEPSGR.BAS - This is a program in ATARI-BASIC. It does create the file ATAEPSGR.BTC (this file wasn't included in the archive because of its length - about 11kB). It's another demonstration how to use BTC for printing. This definition converts all ATASCII characters into EPSON graphics-sequences, and so allows you to print all the characters in the same form as on the screen. Well, this is only a demonstration - for real use it's quite slow and uncomfortable, because single characters are sent as independent small pictures (instead of one large picture of whole line) - but when you've no other solution for the problem "how to print it?", then it might be useful...¢¢CZECH.ARC - Another small archive with specific Czech files: BTC.TCH (a czech version of this text), ASC2CAP.BTC, CAP2ASC.BTC, CAP2ATA.BTC, CAP2KAM.BTC, CAP2TCH.BTC, KAM2ATA.BTC, KAM2CAP.BTC, KAM2TCH.BTC, TCH2ATA.BTC, TCH2CAP.BTC, TCH2KAM.BTC (definitions for converting specific Czech file formats).¢¢¢ FINAL WORDS¢ ===========¢¢BTC is FreeWare, so you can copy it and give to your friends without of any limits, as long as the original archive isn't changed. I hope that you'll find this small program useful. If you've any message for the author, write to:¢¢ Jiri Bernasek¢ Na Hrebenkach 42¢150 00 Praha 5¢ Czech republic¢¢ Sorry, but I've no Internet address! (There are two kinds of messages: First ones are worth enough for a classic letter, and the second ones aren't worth enough even for a few keystrokes :-))¢¢
