\input texinfo	@c -*-texinfo-*-
@setfilename ../info/kbd-trans
@settitle Keyboard translation

@titlepage
@sp 6
@center @titlefont{Keyboard translation}
@sp 4
@center Version 2.0
@sp 5
@center Naoto TAKAHASHI
@center ntakahas@@etl.go.jp
@page

@end titlepage

@node Top, , , (mule)
@section Keyboard translation

Some quail packages, for example, Russian, Greek, Hebrew, etc.,
completely re-map the key layout.  In these cases, it is desirable to
provide the same key layout no matter what keyboard is actually used.
For this purpose, a variable *quail-keyboard-translate-table* is
introduced.  It is used to absorb the differences between the various
real keyboards and the 'ideal' standard keyboard.  Currently, 12
predefined constants are provided.  See the following carefully and
set the apropriate constant to @code{quail-keyboard-translate-table} in
your @file{.emacs} file.  For example, if you are using SUN type4 keyboard,
put
@example
(setq *quail-keyboard-translate-table*
      *quail-keyboard-translate-table-sun-type4*)
@end example

in your .emacs.

@menu
* Keyboard translate tables::
* Writing new keyboard translate table::
@end menu

@node Keyboard translate tables, Writing new keyboard translate table, , Top
@section Predefined keyboard translate tables

Here's a list of predefined keyboard translate tables.

If you don't find your keyboard in the following list, make yours by
yourself @xref{Writing new keyboard translate table}.

@itemize
@item @code{quail-keyboard-standard-table}
@example
machines: vt100, etc.

[unshifted]

Esc 1  2  3  4  5  6  7  8  9  0  -  =  `
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '  \
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

Esc !  @  #  $  %  ^  &  *  (  )  _  +  ~
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "  |
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-sun-type3}
@example
machines: SUN type3 keyboard
	  SUN type5 keyboard
	  TAKAOKA XMiNT (AX keyboard)
	  JCC Xstation / GloabalX (AX keyboard)

[unshifted]

Esc 1  2  3  4  5  6  7  8  9  0  -  =  \  `
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

Esc !  @  #  $  %  ^  &  *  (  )  _  +  |  ~
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-sun-type4}
@example
machines: SUN type4 keyboard

[unshifted]

                                  \
Esc 1  2  3  4  5  6  7  8  9  0  -  =
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '  `
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

                                  |
Esc !  @  #  $  %  ^  &  *  (  )  _  +
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "  ~
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-sony-nwp-411a}
@example
machines: NEWS-3470

[unshifted]

Esc 1  2  3  4  5  6  7  8  9  0  -  =  \
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '  `
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

Esc !  @  #  $  %  ^  &  *  (  )  _  +  |
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "  ~
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-ibm-at}
@example
machines: IBM AT keyboard

[unshifted]

 `  1  2  3  4  5  6  7  8  9  0  -  =  \
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

 ~  !  @  #  $  %  ^  &  *  (  )  _  +  |
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-ibm-rt/pc}
@example
machines: IBM RT/PC 5085 keyboard
	  RS6000 (English keyboard)
	  Apple Macintosh MO115 keyboard / Power Book
	  SGI Iris Indigo

[unshifted]

 `  1  2  3  4  5  6  7  8  9  0  -  =
     q  w  e  r  t  y  u  i  o  p  [  ]  \
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

 ~  !  @  #  $  %  ^  &  *  (  )  _  +
     Q  W  E  R  T  Y  U  I  O  P  {  }  |
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-decstation}
@example
machines: DEC DECstation3100 LK201 keyboard (vt100 mode)
	  DEC DECstation3100 LK401-AJ keyboard (vt100 mode)

[unshifted]

    1  2  3  4  5  6  7  8  9  0  -  =
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '  \
     `  z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

    !  @  #  $  %  ^  &  *  (  )  _  +
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "  |
    ~  Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-dynabook}
@example
machines: TOSHIBA Dynabook386/20 keyboard

[unshifted]

    1  2  3  4  5  6  7  8  9  0  -  =
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
           \     SPACE       `

[shifted]

    !  @  #  $  %  ^  &  *  (  )  _  +
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
           |     SPACE       ~
@end example

@item @code{quail-keyboard-translate-table-mac-mo110}
@example
machines: Apple Macintosh MO110 keyboard

[unshifted]

 `  1  2  3  4  5  6  7  8  9  0  -  =
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
                 SPACE          \

[shifted]

 ~  !  @  #  $  %  ^  &  *  (  )  _  +
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE          |
@end example

@item @code{quail-keyboard-translate-table-mac-mo116}
@example
machines: Apple Macintosh MO116 keyboard

[unshifted]

Esc 1  2  3  4  5  6  7  8  9  0  -  =
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
           `     SPACE       \

[shifted]

Esc !  @  #  $  %  ^  &  *  (  )  _  +
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
           ~     SPACE       |
@end example

@item @code{quail-keyboard-translate-table-jis}
@example
machines: NEC PC-9801 keyboard
	  NEC EWS4800/220, /260
	  EPSON PC-286 keyboard

[unshifted]

Esc 1  2  3  4  5  6  7  8  9  0  -  ^  \
     q  w  e  r  t  y  u  i  o  p  @  [
      a  s  d  f  g  h  j  k  l  ;  :  ]
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

Esc !  "  #  $  %  &  '  (  )  0  =  `  |
     Q  W  E  R  T  Y  U  I  O  P  ~  {
      A  S  D  F  G  H  J  K  L  +  *  }
       Z  X  C  V  B  N  M  <  >  ?  _
                 SPACE
@end example

@item @code{quail-keyboard-translate-table-fujitsu-sigma-230}
@example
machines: Fujitsu Sigma 230

[unshifted]

Esc 1  2  3  4  5  6  7  8  9  0  -  ^  \
     q  w  e  r  t  y  u  i  o  p  @  [
      a  s  d  f  g  h  j  k  l  ;  :  ]
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[shifted]

Esc !  "  #  $  %  &  '  (  )  0  =  ~  |
     Q  W  E  R  T  Y  U  I  O  P  `  {
      A  S  D  F  G  H  J  K  L  +  *  }
       Z  X  C  V  B  N  M  <  >  ?  _
                 SPACE
@end example
@end itemize

@node Writing new keyboard translate table, , Keyboard translate tables, Top
@section Writing new keyboard translate table

@code{quail-keyboard-translate-table} consists of two parts.  One is a
string and the other is an a-list.  The string part, which is the
@code{car} (or @code{nth 0}) of this variable, describes the
`normalised' layout of your keyboard.  (The meaning of 'normalised'
will soon be given.)  The a-list part, which is the 'cadr' (or 'nth 1')
of the variable describes the 'unusually' located keys and their
position.

Let's take IBM AT keyboard as an example.  It looks like this:

@example
[AT unshifted]

 `  1  2  3  4  5  6  7  8  9  0  -  =  \
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[AT shifted]

 ~  !  @  #  $  %  ^  &  *  (  )  _  +  |
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

First, normalise the layout of the keyboard.  'To normalise' means 'to
move some keys so that the number of columns and the number of rows
will match those of @code{quail-keyboard-standard-table}.

@code{quail-keyboard-standard-table} looks like this:

@example
[STANDARD unshifted]

    1  2  3  4  5  6  7  8  9  0  -  =  `
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '  \
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[STANDARD shifted]

    !  @  #  $  %  ^  &  *  (  )  _  +  ~
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "  |
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

Note that @code{quail-keyboard-standard-table} has no keys left to the 1!
key.  It has;
@enumerate
@item
13 keys at the top row, and
@item
12 keys at the 2nd row, and
@item
12 keys at the 3rd row, and
@item
10 keys at the 4th row, and
@item
1 space bar at the bottom.
@end enumerate

To normalise the AT keyboard, it is necessary to move the `~ key to
the right end of the 3rd row.

@example
[AT normalised unshifted]

    1  2  3  4  5  6  7  8  9  0  -  =  \
     q  w  e  r  t  y  u  i  o  p  [  ]
      a  s  d  f  g  h  j  k  l  ;  '  `
       z  x  c  v  b  n  m  ,  .  /
                 SPACE

[AT normalised shifted]

    !  @  #  $  %  ^  &  *  (  )  _  +  |
     Q  W  E  R  T  Y  U  I  O  P  {  }
      A  S  D  F  G  H  J  K  L  :  "  ~
       Z  X  C  V  B  N  M  <  >  ?
                 SPACE
@end example

Now describe this layout by a string from left to right, up to down,
unshifted to shifted.  Unshifted space should be appended at the end
of the string.  There's no shifted space.  The resulting string looks
like this:

@example
"1234567890-=\\qwertyuiop[]asdfghjkl;'`zxcvbnm,./!@@#$%^&*()_+|QWERTYUIOP@{@}ASDFGHJKL:\"~ZXCVBNM<>? "
@end example

Note that '"' (double quote) and '\' (backslash) must be escaped by a
'\'.  This string will be the 'car' of *quail-keyboard-translate-table*.

Next, specify the real location of the moved characters.  In our
example only one KEY (`~) is moved, but this causes two CHARACTERs to
be moved.

The location should be given by a vector of the form:
@quotation
@code{[ x-position  y-position  shift-or-not ]}
@end quotation

For the keys in the first row, x-position means the offset from the 1!
key.  For example, the x-position of '2' is 1, that of '3' is 2, and
that of '=' is 11.  That of '1' itself is 0.  In IBM AT keyboard, '`'
and '~' locate to the left of the 1! key, so their x-position will
be -1.

For the keys in the 2nd, the 3rd, and the bottom row, their x-position
will be the offset from 'q', 'a', and 'z', respectively.

The y-position is the offset from the top row (i.e. the row which
contains 1234...).  So the y-position of '5' is 0, 't' is 1, 'g' is 2,
and 'b' is 3.  Keys above the top row will have a negative y-position.

The third element shift-or-not is 0 if not shifted, and 1 if shifted.

So, the real location of '`' in the AT keyboard will be [-1 0 0] and
that of '~' will be [-1 0 1].  These two locations will be coded into
an a-list together with the characters they are presenting:

  '((?` [-1 0 0]) (?~ [-1 0 1]))

Now we have both the string part and the a-list part.  So the
*quail-keyboard-translate-table* for IBM AT keyboard will be as
follows.  
@example
'("1234567890-=\\qwertyuiop[]asdfghjkl;'`zxcvbnm,./!@@#$%^&*()_+|QWERTYUIOP@{@}ASDFGHJKL:\"~ZXCVBNM<>?" ((?` [-1 0 0]) (?~ [-1 0 1])))}
@end example
When you put these beasts in your .emacs, it would be better to divide
the string part according to the rows so that you can check easily.

@example
(setq *quail-keyboard-translate-table* '("\
1234567890-=\\\
qwertyuiop[]\
asdfghjkl;'`\
zxcvbnm,./\
!@@#$%^&*()_+|\
QWERTYUIOP@{@}\
ASDFGHJKL:\"~\
ZXCVBNM<>?\
 "
  ((?` [-1 0 0]) (?~ [-1 0 1]))))
}
@end example


@contents
@bye