path: root/keyboards/thevankeyboards/minivan/keymaps/josjoha/readme.md

# Minivan keyboard layout _Minifan_
A 40% keyboard made first by TheVan Keyboards
_https://thevankeyboards.com_ now taken over by TKC
_https://thekey.company_

![Minivan layout all](http://socialism.nl/misc/minivan/minivan-all-layers-visualization_vc.jpg)

Table of Contents
=================

      1  Overview
          1.1 Hardware compatibility
          1.2 Software compatibility
      2  'make' example
      3  Base layouts
          3.1  Normal layouts
                3.1.1 Qwerty
                3.1.2 Qwerty with arrows on Base
                3.1.3 Dvorak
                3.1.4 Dvorak² 
                3.1.5 Colemak
                3.1.6 Workman
          3.2 Special layouts
                3.2.1 Numbers pad
      4 The common system
          4.1 Layer access
          4.2 Layout in graphics
          4.3 Layout in text
          4.4 Movement layer options
          4.5 Numbers pad layer options
      5 Led colors for layers
      6 Compile options
      7 Language support
          7.1 Input methods
          7.2 Unicode symbols
      8 Speed measuring
          8.1 Speed Led color compilation assist
      9 Text size measuring
          9.1 Text size Usage
     10 Making your own base layer(s)
     11 Evisceration
     12 Key associations
          12.1 Compared to regular keyboard
     13 Trouble shooting
        • Compiling
        • Unicode
        • Leds
        • Weird layer jumping
        • Difficult/impossible key combinations ?
     14 Why you want this layout
     15 BUGS
     16 Resources
     17 Author(s)

1 Overview
==========

☑ _Intuitive:_ Key placement follows what a 10 finger typist is used
  to on a regular keyboard. Similar keys meanings are on the same
  key in different layers, or the same finger, etc. See also chapter
  12, _Key associations._ Thumbs control the most used layer access.

☑ _Feature rich:_ Dual layout, with several standard layouts to choose
  from. Expanded character set. Measure typing speed and/or amount of text
  typed. Mouse control, media control, power control, Unicode encoding for
  several platforms. In total there are about 4 times as many key functions
  than on a regular keyboard.

☑ _Configurable:_ Choose between standard layouts (Qwerty, Dvorak, etc);
  additional hardware keys ‛command/south-paw’ and/or ‛arrow’; movement
  layer WASD or flat arrows/mouse; numbers pad similar to regular numbers
  and/or like a regular numbers pad; and other settings. Easy to add your
  own layers. See ![./user_config.h](./user_config.h)

☒ What it does *not* do: work on a computer set to a non-English language,
  such as German or French. (To add such functionality requires some work,
  but it seems it should be possible. See ![./todo.md](./todo.md).)

![Minivan illustration Overview layers](http://socialism.nl/misc/minivan/minivan-all-layers-clear-visualization_1500_vg.jpg)

By key view:

![Minivan illustration Overview layers by key](http://socialism.nl/misc/minivan/minivan-all-layers-clear-visualization-by-key_2000_vi.jpg)

1.1 Hardware compatibility
==========================
This keymap functions on _Minivan_ hardware variants with 44, 45 and
46 keys.

It may be fairly easily ported to 12x12x12x[11|12|13] keyboards.

1.2 Software compatibility
==========================
This keymap relies on Unicode, in an attempt to avoid the 
“dead key” system for accented characters on many non-English keyboards.
You need to have Unicode input working on your computer.

On a Linux computer operating system, this keymap is designed to work
with this keyboard/language setting:

        > setxkbmap -layout us
        > echo $LANG
        `en_US.UTF-8`

If that works for you, you can type the most important characters in
the western European group of languages, native from the keyboard.

This keymap might not function as expected if you want to use a
different keyboard language setting in your operating system.

See also chapter 6 _Language support_.

2 'make' example
================
     … Download the repository, resolve software dependencies etc..
     … To change compile options: edit ./user_config.h (or `./minifan_config_compact.h`)
     > cd […]/qmk_firmware
     > make thevankeyboards/minivan:josjoha
     > su
     # dfu-programmer atmega32u4 erase
     # dfu-programmer atmega32u4 flash thevankeyboards_minivan_josjoha.hex
     # dfu-programmer atmega32u4 start

This “Mini*fan*” layout is explained in several readme files, with
links to the others files in this readme. The common system is explained
in this readme.md file. The options for the letters and number/symbol
layer pairs (two pairs in the dual layout) are explained in their
separate readme file, see immediately below. Compile options are detailed
in ![./user_config.h](./user_config.h)

3 Base layouts
==============
Layouts are presented here in a sort of simplified key caps view.  If a
base layer pair has its own user configuration options, they are located
in `./base_NAME.h`.

3.1 Normal layouts
------------------
These are layouts for commonly used configurations, such as Qwerty or Dvorak.

3.1.1 Qwerty
------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_qwerty_vc.jpg)

For the readme about the Qwerty version, see ➡ ![base_qwerty.md](./base_qwerty.md) ⬅

3.1.2 Qwerty with arrows on Base
--------------------------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_qwerty_basearrow_ve.jpg)

For the readme about this Qwerty variation, see ➡ ![base_qwerty_basearrow.md](./base_qwerty_basearrow.md) ⬅

3.1.3 Dvorak
-------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_dvorak_vc.jpg)

For the readme about the Dvorak version, see ➡ ![base_dvorak.md](./base_dvorak.md) ⬅

3.1.4 Dvorak² 
-------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_dvorak_descramble_vb.jpg)

Regular Dvorak for a computer already set to Dvorak.

For the readme about the Dvorak² version, see ➡ ![base_dvorak_descramble.md](./base_dvorak_descramble.md) ⬅

3.1.5 Colemak
-------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_colemak_vc.jpg)

For the readme about the Colemak version, see ➡ ![base_colemak.md](./base_colemak.md) ⬅

3.1.6 Workman
-------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_workman_va.jpg)

For the readme about the Workman version, see ➡ ![base_workman.md](./base_workman.md) ⬅

3.2 Special layouts
===================
These are unusual layouts. Most people will probably only want one of these on the ‛Alternate’ layout,
with a normal layout on ‛Default’. How this works is explained below.

3.2.1 Numbers pad
-----------------

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_numpad_single_va.jpg)

For the readme about the Numpad version, see ➡ ![base_numpad.md](./base_numpad.md) ⬅


4 The common system
===================

![Minivan layout impression](http://socialism.nl/misc/minivan/minivan_keycapview_common_vc.jpg)

4.1 Layer access
----------------
The graphic below shows how layers are reached from the ‛Default base’ layer.

This seems to be the place where one is supposed to say: “This is simple”. 
It may look more confusing than it is. If you write down an alphabet A,B, ➡ Z,
made arrows from every key on a keyboard picture to one of the letters, it could
look just as confusing. When switching to a layer, you only think about where you
want to go.

![Minivan layout Image associations](http://socialism.nl/misc/minivan/minivan-default-base-layer-activation_2000_vi.jpg)

Each of the two base layers comes with its own second layer, typically
numbers-symbols. The other layers are used common between the default and
alternate base layers.  You can switch between the default base layer
(typically letters), and another base layer, the alternate base layer
(also typically letters), on the `_RAR` layer with key ‛Other Base’.

                   Layer overview:                    Defined in:

        • Default Letters / Base                   ┓
        • Default Numbers-symbols                  ┃
                                                   ┣ ./base_….c/md files
              • Alternate Letters / Base           ┃
              • Alternate numbers-symbols layout   ┛

           • Numbers pad                           ┓
           • Accented characters                   ┃
           • Additional Unicode characters         ┃
           • More Additional Unicode characters    ┣ ./keymap.c(etc)/readme.md
           • Movement arrows/mouse                 ┃   “The common system”
           • Function keys / layer toggles         ┃
           • Power, media, Speed, Text size, etc.  ┛

4.2 Layout in graphics
----------------------

![Minivan layout Image BASEdef](http://socialism.nl/misc/minivan/minivan_base_layer_hide_def_base_ve.jpg)
Layer: `DEF_BASE`

![Minivan layout Image NSYdef](http://socialism.nl/misc/minivan/minivan_nsy_layer_hide_def_base_vc.jpg)
Layer: `DEF_NSY`

![Minivan layout Image BASEalt](http://socialism.nl/misc/minivan/minivan_base_layer_hide_alt_base_ve.jpg)
Layer: `ALT_BASE`

![Minivan layout Image NSYalt](http://socialism.nl/misc/minivan/minivan_nsy_layer_hide_alt_base_vc.jpg)
Layer: `ALT_NSY`

![Minivan layout Image PAD](http://socialism.nl/misc/minivan/minivan_pad_layer_vc.jpg)
Layer: `_PAD`

^ See below for a different configuration of the numbers pad keys. See above for a Base layout for a numbers pad.

![Minivan layout Image ACC](http://socialism.nl/misc/minivan/minivan_acc_layer_vd.jpg)
Layer: `_ACC`

![Minivan layout Image DRA](http://socialism.nl/misc/minivan/minivan_dra_layer_vd.jpg)
Layer: `_DRA`

![Minivan layout Image BON](http://socialism.nl/misc/minivan/minivan_bon_layer_vc.jpg)
Layer: `_BON`

![Minivan layout Image FUN](http://socialism.nl/misc/minivan/minivan_fun_layer_vb.jpg)
Layer: `_FUN`

![Minivan layout Image MOV](http://socialism.nl/misc/minivan/minivan_mov_layer_triangle_hw-basic-and-allkeys_vb.jpg)
Layer: `_MOV`

^ There is an alternative flat arrow configuration for this layer (see below),
and options to compile with the 'arrow' hardware layout.

![Minivan layout Image RAR](http://socialism.nl/misc/minivan/minivan_rar_layer_vc.jpg)
Layer: `_RAR`

4.3 Layout in text
------------------
     What comes on “___” is to be defined by the Base layers choice.

         Layer _DEF_BASE (Letters layer, see ./base* files for what comes on ‛__’)
                                                  | Right hand
         <pink2     <pinky<ring <middl<index<indx2| indx2>index>middl>ring> pinky>pinky2>   // Keys by finger
         -o-                                     <|>                                    ... //-o- Base access
         Esc        __    __    __    __    __    | __    __    __    __    __         Bksp
         Tab+LCtl   __    __    __    __    __    | __    __    __    __    __           __
         LSht+_PAD  __    __    __    __    __    | __    __    __    __    __    RSht+_FUN 
             +_MOV⁵                               |                                   +_RAR⁶
     ---------------------------------------------------------------------------------------
     Left+LAlt Del;_ACC _..._NSY(_DRA)  Enter+_MOV| Space  _..._NSY(_DRA) RGUI    Right;_RAR 
               hold     hold₍₁,₂٭₎      hold      |        hold₍₁,₂٭₎             hold     // switch type
               hold₍₂₎  ^-┃-----------------------+--------^ ┃                          // ₁₎ both = _DRA
               ┗━━━_BON━━━╋┅───────────┄┄┄«or»┄┄┄─+─────────┅┛                          // ₂₎ both = _BON
     <1   ±    <2       <3              <4        | 4>     3>             2>   ±  1>    // Keys by number
          ^³                                                                   ^⁴   // Optional more keys
        (LGUI)                                                               (_MOV)
     
     ₁) Dual hold for _DRA, single hold for _..._NSY. Marked by: ^--…--^
     ₂) Hold key “<2” with either٭ key “<3” or “3>” for _BON, single hold “<2” for _ACC. Marked: ┗━━…━━┛
     ³) 'South paw' hardware configuration. Configurable, default shown.
     ⁴) 'Arrow' hardware configuration  Configurable, default shown.
     ³ ⁴) There are two more optional hardware keys, to make it easier to compile for
          a 12x12x12x11 or 12x12x12x12 layouts.
     ⁵) Left Shift when pressed with another key. Medium long: to toggle _PAD. Long: toggle _MOV.
     ⁶) Right shift when pressed with another key. medium long: to toggle _FUN. Long: toggle _RAR.

Remarks: The left modifiers have a slight delay in combination with an outside pointer device (mouse, stylus).
It seems this will be difficult to fix, because it is spread over two devices. To avoid the
±0.2 second delay, activate a layer where the modifiers are direct (`_PAD`, `_MOV`), using the layer toggle on
left shift. 

The two keys with ';' (Del;`_ACC`, Right;`_RAR`) do not auto-repeat on double tap, like QMK normal layer-tap keys.

There is an uncluttered _Delete_ on `_PAD`, an uncluttered _Right_ arrow on the `_MOV` layer.

There is an uncluttered _Tab_ on both the `_DRA` and `_ACC` layers. They can be modified with _Control_ there.

Holding both `_..._NSY` keys left and right of the "split space bar" (enter, space) results in layer `_DRA`.

Holding either one of the just above mentioned `_..._NSY` layer keys (<3 and 3>), with the `_ACC` layer key
(on <2) results in layer `_BON`.

- - -

     Layer _..._NSY (Numbers and SYmbols, ./base* files for what comes on ‛__’)
    
     <pink2   <pinky<ring <middl<index<indx2| indx2>index>middl>ring>pin>pink2>
              -*-                          <|>                                  //(toggle) Access on _FUN
     BASE     __    __    __    __    __    | __    __    __    __   __     Bspc
     Tab+LCtl __    __    __    __    __    | __    __    __    __   __  __+RCtl
     -+LSht   __    __    __    __    __    | __    __    __    __   __  __+RSht 
     ---------------------------------------------------------------------------
                 Left+LAlt ___   ___   Ent  | .   ___   RGUI  Right+RAlt
                                 -*-       <|>    -*-                        //(hold) Access on _DEF_BASE
                   <1   ±  <2    <3    <4   | 4>  3>    2>  ± 1>  
                        ^                                   ^
                      (LGUI)                              (_MOV)

- - -
     
     Layer _FUN (F-keys, Layer access)
    
     <pink2<pinky<ring <middl<index<indx2| indx2>index>middl>ring> pinky>pink2>
     toggl toggl set   toggl toggl toggl | toggl toggl                            // Type of layer switch
                                        <|>                                       
     BASE: NUMS: _PAD  _ACC  _DRA  _BON  | _MOV  _RAR  xxx   xxx   xxx   Bspc       //':' are dynamic ...
     LCtl  F1    F2    F3    F4    F5    | F6    F7    F8    F9    F10   RCtl
     LSht  F11   F12   F13   F14   F15   | F16   F17   F18   F19   F20   RSht     
     ---------------------------------------------------------------------*--       //-*-  toggle on Base
              LAlt  LCtl&  LCtl&  LSht&  | FUN< +LCtl&LSht RGUI   RAlt              //... < toggle 'stay'
                    LSht   LAlt   LAlt   |      &LAlt                                    
                    +xxx   +xxx   +xxx   |      +xxx
                                        <|>
              <1  ± <2     <3     <4     | 4>   3>         2>  ±  1>                
                  ^                                            ^
                (LGUI)                                       (_MOV)

Remarks.  FUN< toggles an immediate return to the Base layer after pressing an F-key, 
or staying on the `_FUN` layer. Right led yellow indicates F-layer stays active.

- - -
    
This is the _triangle_ configuration for arrows, arrow are on left hand (WASD):

     Layer _MOV (MOVement, mouse movement on right hand)
    
     <pinky2<pinky<ring <middl<index<indx2| indx2>index>middl>ring> pinky>pink2>
                                         <|>-*-                                
     Base   PgDn  Up    PgUp  Home  Btn3  | xxx   WhDn  MsUp  WhU   WhLft Bksp
     LCtl   Left  Down  Right End   Btn1  | Btn1  MsLft MsDn  MsRht WhRht RCtl
     LSht   xxx   Acc2  Acc1  Acc0  Btn2  | Btn2  Btn3  Btn4  Btn5  xxx   RSht
     -------------------------------------------------------------------------
                     LAlt Del   Ent   ___ | PgUp  PgDn  RGUI  RAlt
                                      -*-<|>                                                 
                     <1 ± <2    <3    <4  | 4>    3>    2>  ± 1>  
                        ^                                   ^
                      (LGUI)                              (DOWN)


Remarks. For the Minivan _arrow_ hardware layout with arrow cluster, you get this on ‛Base’:

     (…)
     LSht+_PAD ;:    qQ    jJ    kK    xX    | bB    mM    wW    vV    zZ    RSht+_FUN
     -------------------------------------------------------------------------------
     Left+LAlt Del;_ACC _..._NSY(_DRA) Enter+_MOV| Space  _..._NSY(_DRA) RGUI  _MOV  Right;_RAR 
                                                                               ^^^^     // new key (toggle)

… and this on `_MOV` for the _triangle_ configuration:

     (…)
     LSht*- xxx   Acc2  Acc1  Acc0  Btn2  | Btn2  Btn3  Btn4  Btn5  _Up_  RSht
     ---------------------------------------------------------------------------
                     LAlt Del   Ent   ___ | PgUp       PgDn  _Left__Down__Right_
                                      -*-<|>                                 
                     <1 ± <2    <3    <4  | 4>         3>     2>   _±_    1>  
                        ^
                      (LGUI)

… or this on `_MOV` for the _triangle_ arrow configuration with additional _navigation_ keys:

     BASE   PgDn  Up    PgUp  Home _Btn4_ | xxx   WhDn  MsUp  WhU   WhLft Bksp
     LCtl   Left  Down  Right End   Btn1  | Btn1  MsLft MsDn  MsRht WhRht RCtl
     LSht*- xxx   Acc2  Acc1  Acc0 _Btn5_ | Btn2  Bt