
     --------------------------------------------------------------------
                 Magic Keyboard Patch v1.1 (December 10, 2013)
                      Written by Daniel Hedberg, New Beat

                             http://nb.atari.org
     --------------------------------------------------------------------



     FREEWARE
     --------------------------------------------------------------------
     The Magic Keyboard Patch is freeware. It may be copied and passed on
     freely as long as it is left unchanged and contains all relevant
     files.

     PLEASE READ!
     Despite the fact that this program is freeware, and you have no
     obligations at all towards me, I would appreciate some feedback
     if you find this program useful. Contact details can be found at
     the end of this text file. Thank you.


     FILE INFORMATION
     --------------------------------------------------------------------
     A complete archive includes the following files:

       MKBDP10\
         MKBDPTCH.TOS   Executable
         SWE.KBD        Swedish keyboard configuration
         UK.KBD		English (UK) keyboard configuration
         CUSTOM.KBD     Custom keyboard configuration (an alternative
                        Swedish keyboard configuration)
         DOC\
           MKBDPTCH.TXT   Documentation (this file)
           UPDATES.TXT    Version history information
           SCANCODE.GIF   The keyboard scan codes of the Atari keyboard
           ASCII1.GIF     The Atari ASCII codes, part 1
           ASCII2.GIF     The Atari ASCII codes, part 2
           ASCII3.GIF     The Atari ASCII codes, part 3


     OVERVIEW
     --------------------------------------------------------------------
     MagiC has a fixed keyboard configuration and if it does not match
     your actual keyboard, it may be hard to find out what key to press
     to get the character you want, or even worse, some letters of your
     spoken language may not be accessible by a single key press at all.

     The Magic Keyboard Patch will update the MAGIC.RAM file with a new
     keyboard configuration. Currently two predefined configurations are
     included:

     Swedish - SWE.KBD
     English (UK) - UK.KBD

     If your keyboard does not match any of these configurations, there
     is the possibility to create your own configuration by editing the
     file CUSTOM.KBD. Read more under CREATING A CUSTOM KEYBOARD
     CONFIGURATION.

     The distributed CUSTOM.KBD is an alternative Swedish keyboard
     configuration. Try it out for a surprise!


     HOW TO USE
     --------------------------------------------------------------------
     To patch your installation of MagiC, copy the MAGIC.RAM file to the
     directory that contains the MKBDPATCH.TOS and the *.KBD files.
     The MAGIC.RAM file is located on the boot partition, typically
     C:\MAGIC.RAM.

     Before applying the patch, create a backup of the MAGIC.RAM file
     so that it can be restored in case something would go wrong.

     Run MKBDPATCH.TOS and follow the instructions. The patch is applied
     to the MAGIC.RAM file in the directory of the MKBDPATCH.TOS file.

     Replace the original MAGIC.RAM file on the boot partition with the
     patched version and reboot the computer. Note that if the patch
     was applied while MagiC was running, a cold reboot is required for
     Magic to reread the MAGIC.RAM file.


     CREATING A CUSTOM KEYBOARD CONFIGURATION
     --------------------------------------------------------------------
     If none of the predefined keyboard configurations match your
     keyboard it is possible to create a custom configuration. This is
     easiest done by making a copy of the the configuration file that is
     the closest match to your keyboard. Give the copy the name
     CUSTOM.KBD (overwrite the existing file).

     Edit the file in a HEX editor. The file has 5 sections:
       $0 -  $79: Unshifted keys
      $80 -  $FF: Shifted keys
     $100 - $179: Keys with CAPS LOCK activated
     $180 - $1FF: Keys with ALT
     $200 - $279: Shifted keys with ALT

     Each section is a map from IKBD scan codes to Atari ASCII codes. The
     IKBD scan code being the index of the byte (counting from the start
     of the section), and the ASCII code being the value of the byte. The
     index is zero-based. The first and last 14 bytes, as well as some
     intermediate bytes in each section are unused and should be null.

     For an illustration on how the IKBD scan codes map to the physical
     keys of the Atari keyboard, refer to the SCANCODE.GIF image. The
     image was created by Unseen Menace.

     For a table of the Atari ASCII codes, see the ASCII<n>.GIF images.
     The images were taken from the Atari Compendium.

     If you create a keyboard configuration that you think would be of
     interest to others, do not hesitate to contact me. I would be happy
     to include it in the next version of MagiC Keyboard Patch.


     TECHNICAL NOTES
     --------------------------------------------------------------------
     So far, this patch has only been tested and verified to work with
     the German version of MagiC v6.20. Most likely it will work with
     other versions as well as the patch does not rely on a fixed offset
     of the keyboard table in the MAGIC.RAM file.

     The byte sequence that is searched for in order to find the
     location of the keyboard table in the MAGIC.RAM file is:
     
     $00,$1B,$31,$32,$33,$34,$35,$36,$37,$38,$39,$30,*,*,$08,$09

     The asterisk represents "any value". The bytes correspond to the
     following keys.

     [NOT-USED][ESC]1234567890[ANY][ANY][BACKSPACE][TAB]

     DO NOT change any of these keys in a CUSTOM.KBD as the program will
     no longer be able to find the correct offset for the keyboard table
     in the MAGIC.RAM file if such a configuration is applied.


     HOW TO CONTACT ME
     --------------------------------------------------------------------
     Feel free to contact me for any reason. Suggestions how to improve
     the Magic Keyboard Patch or bug reports are welcome!

     E-Mail: daniel.hedberg@gmail.com
        WWW: http://nb.atari.org
