!xmodmap-compact ! xmodmap-compact !
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 an Apple buttonboard.
!  Model No.: A1243  EMC No.: 2171
!  109 buttons
!
! Very odd physical design, and peculiar failures when
! holding multiple buttons.  The modifier buttons are
! wide enough for thumbs, as if the hands were meant
! to be crossed, wrist on top of wrist.  Perhaps so,
! then the palm could press that extra wide barbutton.
!
! It also has movement buttons and an extra set
! of number buttons.


!---------------------------------------------------------.
!esc|F1  F2  F3   F4  F5  F6  F7  F8  F9  F10  F11 F12|ejt|
!---^-------------------------------------------------^---|
! `   1   2   3   4   5   6   7   8   9   0   -   = |  del|
!---------------------------------------------------^-----|
!tab  | q   w   e   r   t   y   u   i   o   p   [   ]   \ |
!-----^---------------------------------------------------|
!caps  | a   s   d   f   g   h   j   k   l   ;   ' |return|
!------^-------------------------------------------^------|
!shift   | z   x   c   v   b   n   m   ,   .   / |   shift|
!--------^---------------------------------------^--------|
!ctrl |opt |comm |       barbutton       | comm| opt| ctrl|
!-----^----^-----^-----------------------^-----^----^-----'


! 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,
! which is keycode 464 in the console.
!
!---------------------------------------------------------.
! 9 |232 233 128  212 237 238 173 172 171 121  122 123|169|
!   | 67  68  69   70  71  72  73  74  75  76   95  96|   |
!---^-------------------------------------------------^---|
! 49  10  11  12  13  14  15  16  17  18  19  20  21|   22|
!                                                   |  119|
!---------------------------------------------------^-----|
!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|
!      |                                           |   118|
!------^-------------------------------------------^------|
!50      | 52  53  54  55  56  57  58  59  60  61|      62|
!--------^---------------------------------------^--------|
!37   |64  |133  |           65          |  134| 108|  105|
!-----^----^-----^-----------------------^-----^----^-----'

!

#buttonboard circuit failures


! Failures when holding buttons
! before typing final button.
!
!  v + 4 = success    v + m + 4 = nothing
!  v + r = success    v + m + r = nothing
!  v + f = success    v + m + f = nothing
!
! For this buttonboard, buttons other than
! modifier buttons are limited as modifiers.
! A whole column becomes unresponsive while holding
! two other buttons, though it will likely depend on
! the row and column of the held buttons.
!
! Likely the common limit of an efficiently designed
! buttonboard circuit rather than infinitely designed.
!
! Consider assigning keysyms to the other buttons
! in the same column with no need of that button
! as their modifier, or depend on the buttons
! intended as modifier buttons instead.


! It seems like both of the same modifier buttons
! assigned with different modifier keysyms
! fail when both are held.
!
!  Option_L  + Option_R + a = nothing
!  Shift_L   + Shift_R  + q = nothing
!  Control_L + Option_R + a = success
!  Control_L + Option_R + q = success
!
! Both Option buttons combined with any button
! from "a" to apostrophe fail.
! Both Shift buttons combined with any button
! from "q" to "[" fail.
! However, the left Control combined with
! the right Option work with both of those rows.
!
! Consider assigning a modifier lock keysym to the
! other modifier button, hence no need for holding it.

!

#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  F12 eject
! ---  ---  ---  ---                 ---  ---  --- -----
! 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    -    =   DEL
! ---  ---  ---  ---  ---       ---  ---  ---  ---  ---
! 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.


!         d         f
!      -------   -------
!      delete    delete
!      -left     -right
!
!    z         x         c
! -------   -------   -------
! Return            |  space
!                   v nobreak
!                --> <--
!       Command L   ^     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 4-way intersection of the buttons for
! Left, Right, the "right" layouts, and the
! view management with StumpWM.
!
! 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
!                --> <--
!     barbutton     ^   Command R
! ----------------- | -------------
! "view management"   "lock right"


! The Home, End, Prior, and Next keysyms are typically
! ineffective in programs when Shift is active.
! Therefore, the right Shift 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


! Option   Command     barbutton     Command   Option
! ------   -------   -------------   -------   -------
!  Alt     "lock     "view           "lock     Control
!           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 Mode_switch =

!

#symbols for row 1


! Row 1:
!  esc (9), F1-F12, eject (169)
!
! F1  F2  F3  F4  F5  F6  F7  F8  F9  F10 F11 F12
! --- --- --- --- --- --- --- --- --- --- --- ---
! 232 233 128 212 237 238 173 172 171 121 122 123


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

! Unassigned
keycode 212 =

! Only F1, F3, and F4 have been useful, f.e. Emacs.
! Re-assign to the primary F5-F8 keycodes.
keycode 237 = F1 F1  F1 F1
keycode 238 = F2 F2  F2 F2
keycode 173 = F3 F3  F3 F3
keycode 172 = F4 F4  F4 F4

! Right hand: top row.
! The F10 button was too far left for the forefinger.
! The F11 button was awkward for typing, but might be
! convenient as the Alt button for toggling a menubar.
keycode 171 = e 1  E backslash
keycode 121 = f 2  F slash
keycode 122 = Alt_R
keycode 123 = g 3  G asterisk
keycode 169 = 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 questiondown  L exclamdown
keycode 13 = y question  Y exclam

! 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  ;  '  return
! --- -- -- -- -- -- -- -- -- -- -- -- ------
! 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 opt comm barbutton comm opt ctrl
! ---- --- ---- --------- ---- --- ----
!  37   64  133     65     134 108  105


! Unassigned
keycode 37 =


! Assign the left Option button as the only Alt.
! Nevermind.  F11 is more convenient (Row 1).
!keycode 64 = Alt_L
keycode 64 =


! The "lower" layout button, at left Command.
keycode 133 = Mode_switch


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


! The "lock right" layout button, at right Command.
keycode 134 = Shift_Lock


! Assign the right Option button as the only Control.
! Easy to hold with thumb for any small letter.
keycode 108 = Control_R


! Unassigned
keycode 105 =

!

#secondary keycode assignment


! Simpler console terminal switching.
! Still the secondary keycodes for the F# buttons,
! but without the Control-Alt modifiers.
! There is just one VT on piCore, by default.
keycode 67 = XF86Switch_VT_1

!

#extra buttons


! Unassign the left arrow button because the right hand
! sometimes rests on it.
keycode 113 =

!

#add to modifier groups


add lock = Shift_Lock

add control = Control_R

add mod1 = 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

!

#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.html
!
! View without blank lines or comments, with grep:
!  grep -v '^$\|^!' xmodmap-compact.html


! Apply with the "xmodmap" program in the console:
!  xmodmap xmodmap-compact.html
!
! Or, for StumpWM within its "init.lisp":
!  (run-shell-command "xmodmap xmodmap-compact.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

!