! !xmodmap--compact--rpi-kyb ! xmodmap--compact--rpi-kyb !
Reference:
! A buttonboard layout with one button per letter
! of the English (U.S.) alphabet, and four symbols
! per button.  Two layout buttons, "lower" and "right",
! provide access to all four layouts of the presumed
! 2x2 matrix (Diagram for typing symbols).
!
! Spacing and deleting is handled by the left thumb
! (Diagram for spacing and deleting).
!
! Movement and placement is handled by the right thumb
! (Diagram for placing content).


! Ideally, there would be one button per layout
! for activating each rather than temporarily switching.
! The Xserver and the programs depending on it seem to be
! without that support (StumpWM and the X Window System).
!
! Perhaps that will be overcome by StumpWM (SBCL) becoming
! either an Xserver, or as a Wayland compositer,
! or as the kernel itself.

!

#buttonboard model

! For a Raspberry Pi buttonboard.
!  Model No.: RPI-KYB
!  78 buttons
!
! It has movement buttons for left/up/down/right
! in a common layout inconvenient for the thumb.


!---------------------------------------------------------.
!esc|F1  F2  F3   F4  F5  F6  F7  F8  F9  F10|num prt fdel|
!---^----------------------------------------^------------|
! `   1   2   3   4   5   6   7   8   9   0   -   = | bdel|
!---------------------------------------------------^-----|
!tab  | q   w   e   r   t   y   u   i   o   p   [   ]   \ |
!-----^---------------------------------------------------|
!caps  | a   s   d   f   g   h   j   k   l   ;   ' | enter|
!------^-------------------------------------------^------|
!shift   | z   x   c   v   b   n   m   ,   .   / |   shift|
!--------^---------------------------------------^--------|
!ctl|fn |spr|alt |     barbutton     |altg|ctl|   | up|   |
!   |   |   |    |                   |    |   |---+---+---|
!   |   |   |    |                   |    |   |lft|dwn|rt |
!---^---^---^----^-------------------^----^---^---^---^---'


! All keycodes as understood by an Xserver (8-255),
! which are merely offset by +8 from Linux console.
! Second keycode is while holding the Fn button
! (keycode still unknown).
!
! [The SysRq button (Fn + PrtScn) is still unknown.]
!
!---------------------------------------------------------.
! 9 | 67  68  69   70  71  72  73  74  75  76| 77 107  119|
!   | 95  96                               78|    srq  118|
!---^----------------------------------------^------------|
! 49  10  11  12  13  14  15  16  17  18  19  20  21|   22|
!---------------------------------------------------^-----|
!23   | 24  25  26  27  28  29  30  31  32  33  34  35  51|
!-----^---------------------------------------------------|
!66    | 38  39  40  41  42  43  44  45  46  47  48|    36|
!------^-------------------------------------------^------|
!50      | 52  53  54  55  56  57  58  59  60  61|      62|
!--------^---------------------------------------^--------|
!37 |fn |133|64  |        65         | 108|105|   |111|   |
!   |   |   |    |                   |    |   |---+---+---|
!   |   |   |    |                   |    |   |113|116|114|
!---^---^---^----^-------------------^----^---^---^---^---'

!

#buttonboard failures

! On rare occassion, a button press will continuosly repeat itself,
! as if it were still held.  When typing, this appears as a single
! letter continuously typed.
!
! The only way to stop it seems to be to randomly type as many
! buttons as possible until the something else (from one of those
! randomly typed buttons) appears on the screen.  Then, delete
! the mess.


! The PrtScn button (keycode 107) seems incompatible
! with Shift Lock in the X Window System, at least
! when using xmodmap to set the buttonboard map.
!
! In other words, the character mapped to
! PrtScn (keycode 107) for Shift
! fails to be produced with Shift Lock.
! (Currently untested with Shift.)
!
! For example, with the following mapping:
!  keycode 107 = g 3  G asterisk
! The "3" will be unattainable with Shift Lock.


! The PrtScn button (keycode 107) is slightly incompatible
! with Mode switch of the X Window System.
!
! A character mapped to the PrtScn button
! for the "Mode switch" is produced only after
! the Mode switch button has been released.
!
! In other words, hold the Mode switch button then
! type the PrtScn button, but nothing appears
! to happen.  Release the Mode switch button and
! the character is produced.
!
! Typing anything else before releasing Mode switch
! will prevent whatever character was mapped
! to the PrtScn button from appearing.

!

#diagrams

! Four fingers means four buttons in a row.
! One row above and one row below means three rows.
! Twelve buttons per hand means 24 buttons total.
!
! There are usually 47 buttons with symbols,
! two per button.  Two "shift" buttons for
! the other half, but only one needed.
!
! As that is almost twice as many as 24, four symbols
! per button encompasses all.  Two "shift" buttons
! can suffice for three additional layouts by holding
! both for the third.
!
! Consider StumpWM commands for locking a layout button
! by sending the Xserver a "press" key-event for one
! without a "release" key-event.  Actual typing of the
! corresponding layout button would release its lock.
! Ensure the layout lock buttons are always available
! by defining them in a "primary" keymap listed prior
! to the StumpWM *top-map*.


! Consider having four symbols per button in a
! 2 by 2 matrix, the one at left-top as default.
!
!   default   right
!   lower     lower-right
!
! The layout buttons, t.i. "shift" buttons,
! are "right" for the symbol right of the default,
! "lower" for the symbol below the default,
! and both for the lower-right symbol.

!

#diagram of buttons for typing symbols

! Letters are listed in familiar alphabetical order
! from left to right and then top to bottom,
! the same as when writing and reading.  Add two more
! buttons outside the forefingers for "y" and "z".
! Small letters are the default layout and their
! capitals are a separate layout, as usual.
!
! Numbers are sequential as when counting,
! and familiarly arranged as on phones and ATMs.
! The ten digits are grouped within the twelve buttons
! of the right half, with the minus, plus, and period.


! esc  F1   F2   F3                  F9   F10  Prt FDel
! ---  ---  ---  ---                 ---  ---  --- ----
! a (  b )  c [  d ]                 e 1  f 2  g 3  h -
! A {  B }  C <  D >                 E \  F /  G *  H =
!
!  `    1    2    3    4         9    0    -    =  BDel
! ---  ---  ---  ---  ---       ---  ---  ---  --- ----
! i "  j ,  k ʻ  l !  y ?       z 0  m 4  n 5  o 6  p .
! I ¨  J ¸  K ¯  L ¡  Y ¿       Z #  M &  N |  O @  P :
!
! tab   q    w    e                   p    [    ]    \
! ---  ---  ---  ---                 ---  ---  ---  ---
! q `  r ~  s ^  t '                 u 7  v 8  w 9  x +
! Q `  R ~  S ^  T ´                 U _  V $  W %  X ;


! The ʻokina consonant and the kahakō accent (macron)
! are the right half of "k".
!
! Composition with the accent for
!  umlaut (diaeresis),  cedilla,
!  grave,               tilde,     circumflex,  acute
! are with the traditional mnemonic symbols that were
! combined with an AltGr or Compose button:
!  double-quote,        comma,
!  backtick,            squiggly,  caret,       apostrophe
! That is from the lower-right of:  i, j, q, r, s, t.
!
! Composition of the circumflex accent with a digit
! results in an exponential (superscript):  ⁰¹²³⁴⁵⁶⁷⁸⁹.

!

#diagram of buttons for spacing and deleting

! The left thumb is for spacing and deleting.
!
! The left thumb rests comfortably on the gap
! at the 4-way intersection of the buttons for
! space, the view management with StumpWM,
! and the "lower" layouts.
!
! That has also helped with locating by feel,
! and the sound of the barbutton when jostled.


!         s         d
!      -------   -------
!      delete    delete
!      -left     -right
!
!    z         x         c
! -------   -------   -------
! return            |  space
!                   v nobreak
!                --> <--
!          Alt      ^     barbutton
!     ------------- | -----------------
!     "lock lower"    "view management"


! StumpWM expects Return instead of Linefeed
! for finalizing its prompts.
!
! The forward delete ("Delete") seems
! unavailable when Shift is active.
!
! The x button was accidentally typed too easily.
! Ideally, it would activate the left-top buttonmap.
!
! The "nobreakspace" is less accidental
! with "lower" rather than "right".
!
! The "lower" layout button is Mode_Switch,
! at left Command.  There seems to be no lock
! supported for Mode_switch.

!

#diagram of buttons for placing content

! The right thumb is for placing the
! text insertion point or the viewed content.
!
! The right thumb rests comfortably on the gap
! at the sort of 4-way intersection of the buttons
! for Left, Right, the "right" layouts, and the
! the Alt button for menus from programs.
!
! That has also helped with locating by feel,
! and the sound of the barbutton when jostled.


!          l         ;
!       -------   -------
!         Up       Down
!        Prior     Next
!
!     ,         .         /      Shift R
!  -------   -------   -------   -------
!   Left   |  Right      Tab     "lower"
!   Home   v   End
!       --> <--
!  Alt Gr   ^ Control
! --------- | -------
!   menus     "lock
!              right"


! The Home, End, Prior, and Next keysyms are typically
! ineffective in programs when Shift modifier is active.
! So, the right Shift button is a second "lower" button
! for content navigation with one hand while reading
! rather than writing.
!
! The Tab is a capitulation for hyperlink navigation
! or text completion.  The Tab as a typed character
! is for substitution matches, f.e. spaces or deletion,
! because it has been phased out of personal workflows.
!
! The Tab is available without the Shift modifier,
! otherwise it automatically becomes "ISO_Left_Tab"
! in some programs.

!

#diagram of buttons for commands

! Control  Fn  Super    Alt      barbutton    Alt Gr  Control
! -------  --  -----  -------  -------------  ------  -------
! Control  Fn  Super  "lock    "view           Alt    "lock
!                      lower"   management"            right"


! A keysym or means for locking group 2 was unknown
! at the time.  A sequence of capitalized letters
! has been rare compared to a number sequence.
! Therefore, the numbers layout is with Shift_Lock,
! and capital letters are with Mode_switch.
!
! The barbutton is Escape for the "top maps"
! of StumpWM, such as for stumpwm::*escape-key*.
! Escape is the default for canceling a prompt,
! so having it as the StumpWM "top maps" button
! helps it feel like a toggle button.
!
! Phasing out the Control keysyms in personal
! workflows.  Probably need only C-x for emacs.
! Essentially, only the small letters are relevant.
! Might also be useful with other computers (VNC).
!
! Phasing out the Alt keysyms in personal workflows.
! The Alt button toggles the menubar of a program,
! then type the underlined letter for a menu
! or for one of its commands.
! Might also be useful with other computers (VNC).
!
! The Super keysyms are unneeded for the moment.
! Might be useful with other computers (VNC).

!

#keycode assignment

! Remap the whole buttonboard.  Unassign all unneeded
! buttons in order to prevent mistyping.

!

#clear modifier groups

! Empty all eight modifier groups in advance.
!
! Consider unassigning modifier symbols for
! pre-assigned keycodes of nonexistent buttons.


clear shift
!keysym Shift_L =
!keysym Shift_R =

clear lock
!keysym Caps_Lock =
! Shift_Lock is already without any buttons.
!keysym Shift_Lock =

clear control
keysym Control_L =
keysym Control_R =

clear mod1
clear mod2
clear mod3
clear mod4
clear mod5
!keysym Alt_L =
!keysym Alt_R =
keysym Super_L =
keysym Super_R =
keysym Mode_switch =

!

#symbols for row 1

! Row 1:
!  esc (9)
!
!  F1  F2  F3  F4  F5  F6  F7  F8  F9  F10
!  --- --- --- --- --- --- --- --- --- ---
!   67  68  69  70  71  72  73  74  75  76
!
!  num lock (77)
!  print screen (107)
!  forward delete (119)


! Left hand: top row.
keycode 9 = a parenleft  A braceleft
keycode 67 = b parenright  B braceright
keycode 68 = c bracketleft  C less
keycode 69 = d bracketright  D greater

! Unassigned
keycode 70 =

! Only F1, F3, and F4 have been useful, f.e. Emacs.
! Re-assign to the primary F5-F8 keycodes.
keycode 71 = F1 F1  F1 F1
keycode 72 = F2 F2  F2 F2
keycode 73 = F3 F3  F3 F3
keycode 74 = F4 F4  F4 F4

! Right hand: top row.
!
! The F10 button (76) was too far left for the forefinger.
!
! The Num Lock button (77) was awkward for typing,
! but PrtScn (107) fails with Shift Lock.
! (buttonboard failures)
!
! However, PrtScn might be convenient
! as an Alt button for toggling a menubar.
keycode 75 = e 1  E backslash
keycode 76 = f 2  F slash
keycode 77 = g 3  G asterisk
keycode 107 = Alt_R Alt_R  Alt_R Alt_R
keycode 119 = h minus  H equal

!

#symbols for row 2

! Row 2
!
! `  1  2  3  4  5  6  7  8  9  0  -  =  delete
! -- -- -- -- -- -- -- -- -- -- -- -- -- ------
! 49 10 11 12 13 14 15 16 17 18 19 20 21   22


! Left hand: middle row.
keycode 49 = i quotedbl  I dead_diaeresis
keycode 10 = j comma  J dead_cedilla
! The ʻokina consonant is Unicode hexadecimal "02bb".
keycode 11 = k U02bb  K dead_macron
keycode 12 = l exclam  L exclamdown
keycode 13 = y question  Y questiondown

! Unassigned
keycode 14 =
keycode 15 =
keycode 16 =
keycode 17 =

! Right hand: middle row.
keycode 18 = z 0  Z numbersign
keycode 19 = m 4  M ampersand
keycode 20 = n 5  N bar
keycode 21 = o 6  O at
keycode 22 = p period  P colon

!

#symbols for row 3

! Row 3
!
! tab q  w  e  r  t  y  u  i  o  p  [  ]  \
! --- -- -- -- -- -- -- -- -- -- -- -- -- --
! 23  24 25 26 27 28 29 30 31 32 33 34 35 51


! Left hand: bottom row.
keycode 23 = q grave  Q dead_grave
keycode 24 = r asciitilde  R dead_tilde
keycode 25 = s asciicircum  S dead_circumflex
keycode 26 = t apostrophe  T dead_acute

! Unassigned
keycode 27 =
keycode 28 =
keycode 29 =
keycode 30 =
keycode 31 =
keycode 32 =

! Right hand: bottom row.
keycode 33 = u 7  U underscore
keycode 34 = v 8  V dollar
keycode 35 = w 9  W percent
keycode 51 = x plus  X semicolon

!

#symbols for row 4

! Row 4
!
! cap a  s  d  f  g  h  j  k  l  ;  '  enter
! --- -- -- -- -- -- -- -- -- -- -- -- -----
! 66  38 39 40 41 42 43 44 45 46 47 48    36


! Unassigned
keycode 66 =
keycode 38 =

! Left thumb: top row.
keycode 39 = BackSpace BackSpace
keycode 40 = Delete Delete

! Unassigned
keycode 41 =
keycode 42 =
keycode 43 =
keycode 44 =
keycode 45 =

! Right thumb: top row.
keycode 46 = Up Up  Prior Prior
keycode 47 = Down Down  Next Next

! Unassigned
keycode 48 =
keycode 36 =

!

#symbols for row 5

! Row 5
!
! shift z  x  c  v  b  n  m  ,  .  /  shift
! ----- -- -- -- -- -- -- -- -- -- -- -----
!  50   52 53 54 55 56 57 58 59 60 61  62


! Unassigned
keycode 50 =

! Left thumb: middle row.
! The x button was accidentally typed too easily.
! Ideally, it would activate the left-top buttonmap.
keycode 52 = Return Return  Return Return
keycode 53 =
keycode 54 = space space  nobreakspace nobreakspace

! Unassigned
keycode 55 =
keycode 56 =
keycode 57 =
keycode 58 =

! Right thumb: middle row.
keycode 59 = Left Left  Home Home
keycode 60 = Right Right  End End
keycode 61 = Tab Tab  Tab Tab

! The second "lower" layout button, at right Shift.
keycode 62 = Mode_switch

!

#symbols for row 6

! Row 6
!
! ctrl fn super alt barbutton altg ctrl
! ---- -- ----- --- --------- ---- ----
!  37  fn  133  64     65     108  105


! Assign the left Control button as the only Control.
! In desperation, at least one button labeled "Control"
! will work for switching to the console with Ctrl+Alt+F1.
keycode 37 = Control_L


! The Super button is needed probably only for VNC.
keycode 133 = Super_L


! The "lower" layout button, at left Alt.
keycode 64 = Mode_switch


! The "view management" button for StumpWM,
! at the barbutton.
keycode 65 = Escape Escape  Escape Escape


! Assign the Alt Gr button as an Alt.
! Though Num Lock is generally more convenient (Row 1).
! in desperation, at least one button labeled "Alt"
! will work for switching to the console with Ctrl+Alt+F1.
keycode 108 = Alt_L Alt_L  Alt_L Alt_L


! The "lock right" layout button, at right Control.
keycode 105 = Shift_Lock

!

#add to modifier groups

add lock = Shift_Lock

add control = Control_L

add mod1 = Alt_L Alt_R


! Need "Mode_switch" (or its alias) for the button
! that is held for programs abiding the X11 protocol.
! Need "ISO_Level3_Shift" (erroneously) added
! to the same modifier group for StumpWM,
! because StumpWM matches that modifier group.
!
! The Xserver starts with "ISO_Level3_Shift" assigned
! to a non-existent button for this buttonboard,
! but that is desired for this circumstance.
!
add mod2 = Mode_switch ISO_Level3_Shift


! The Super button is sometimes needed
! in other operating systems (VNC).

add mod3 = Super_L

!

#xmodmap review

! A comment is a whole line that begins with !.
!
! Each keycode line has up to eight possible keysyms,
! recognized as four distinct groups.
!
! Group one:
!  default     Shift
!
! Group two:
!  Mode_switch     Mode_switch + Shift
!
! Group three:
!  ISO_Level3_Shift     ISO_Level3_Shift + Shift
!
! Group four is probably something to do with
! ISO_Level5_Shift.
!
! The = must have a space before and after it.
! Skip a position with NoSymbol, or when that fails
! try VoidSymbol.


! The X Window System protocol is limited to F1-F35.
!
! Non-accented letters can be referenced as is.
! Numbers can be referenced as is or by name.
! Punctuation is referenced by name.
!
! Any symbol as Unicode is U and its hexadecimal number
! from U0020 (space) and up.


! Help from xmodmap is with "-h":
!  xmodmap -h
!
! View proposed changes without changing with "-n":
!  xmodmap -n xmodmap-compact,rpi-kyb.html
!
! View without blank lines or comments, with grep:
!  grep -v '^$\|^!' xmodmap-compact,rpi-kyb.html


! Apply with the "xmodmap" program in the console:
!  xmodmap xmodmap-compact,rpi-kyb.html
!
! Or, for StumpWM within its "init.lisp":
!  (run-shell-command "xmodmap xmodmap-compact,rpi-kyb.html")

!

#StumpWM and the X Window System

! The X Window System protocol, Chapter 5,
! states "Mode_switch" is for group 2.
! The CLX library has "xlib:keycode->keysym"
! which expects a keysym index from 0 to 6,
! according to the error it gives when beyond.
!
! Group 1 is the default group and has indexes 0 and 1,
! with the second index for when the Shift modifier
! is active.
! Group 2 is for when the "Mode_switch" is active
! and has indexes 2 and 3.  The "ISO_Group_Shift"
! is an alias for "Mode_switch", so either name works.
! Group 3 is for when the "ISO_Level3_Shift" is active
! and has indexes 4 and 5.


! StumpWM favors "ISO_Level3_Shift" and equates it
! with the traditional AltGr/Compose button,
! and with group 2.  However, it also matches
! with the modifier group mask, which allows it
! to work when added to the same modifier group
! as "Mode_switch".
! See "input.lisp" for "code-state->key" at 511-528,
! which references "*modifiers*"
! which is set by "get-modifier-map" at 800-834.
!
! Need "Mode_switch" (or its alias) for the button
! that is held for programs abiding the X11 protocol.
! Need "ISO_Level3_Shift" (erroneously) added
! to the same modifier group for StumpWM,
! because StumpWM matches that modifier group.

!

#test

! Testing lock for Mode_switch.  Delete when done.
! So far, no search results for Mode_switch locking.
!
! No result with urxvt or StumpWM
! for ISO_Lock assigned to separate button.
!keycode 37 = ISO_Lock
!add mod3 = ISO_Lock
!
! No result with urxvt or StumpWM
! for ISO_Group_Lock assigned to separate button.
!keycode 37 = ISO_Group_Lock
!add mod3 = ISO_Group_Lock


! Testing latch for Shift: "ISO_Level2_Latch".
! Failed for urxvt and StumpWM prompts.
!
!keycode 37 = ISO_Level2_Latch
!add mod3 = ISO_Level2_Latch


! So far, no access to group 3.
!
! The virtual terminal urxvt works with "Mode_switch".
!
! However, urxvt fails with "ISO_Level3_Shift".
! Tested by ensuring modifier groups were cleared
! and Mode_switch was separated from ISO_Level3_Shift.
!
!add mod2 = Mode_switch
! The labeled backslash/bar button, above Return.
!keycode 51 = backslash bar comma period equal plus minus
! The left Control button.
!keycode 37 = ISO_Level3_Shift
!add mod3 = ISO_Level3_Shift


!!The "ISO_Level3_Lock" is what (erroneously) works
! with StumpWM prompts.  However, StumpWM flickers
! the prompt (indicating an error) when that button
! is typed unless it was added to a modifier group.
! Nonetheless, it works either way.
!!It also works to add the button to the same
! modifier group as "ISO_Level3_Shift".
!
!keycode 66 = ISO_Level3_Lock
!add mod2 = ISO_Level3_Lock


! Testing for "ISO_Level3_Latch" with StumpWM.
! Potential replacement for "shifting".
!
! Worked fine.
!
!keycode 37 = ISO_Level3_Latch
!add mod3 = ISO_Level3_Latch


! Testing ISO_Level3_Shift.  Delete when done.
!
! So far, no result from urxvt for Level3.  Look for
! another program for further testing.
!
!add mod2 = Mode_switch
! The labeled backslash/bar button, above Return.
!keycode 51 = backslash bar comma period equal plus minus
! The left Control button.
!keycode 37 = ISO_Level3_Shift
!add mod3 = ISO_Level3_Shift

!