1 files changed, 17 insertions, 41 deletions
diff --git a/docs/basic_how_keyboards_work.md b/docs/basic_how_keyboards_work.md
index 73c3f5c5f..3969c5680 100644
--- a/docs/basic_how_keyboards_work.md
+++ b/docs/basic_how_keyboards_work.md
@@ -23,20 +23,14 @@ in the next sections.
 Whenever you press a key, the firmware of your keyboard can register this event.
 It can register when the key is pressed, held and released.
-This usually happens with a [periodic scan of key presses with a frequency around 100 hz](https://github.com/benblazak/ergodox-firmware/blob/master/references.md#typical-keyboard-information).
+This usually happens with a periodic scan of key presses. This speed often is limited by the mechanical key response time, the protocol to transfer those key presses (here USB HID), and by the software it is used in.
-This speed often is limited by the mechanical key response time, the protocol
-to transfer those key presses (here USB HID), and by the software it is used in.
 ## 2. What the Firmware Sends
-The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf)
+The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
-tells what a keyboard can actually send through USB to have a chance to be
-properly recognised. This includes a pre-defined list of keycodes which are
-simple numbers from `0x00` to `0xE7`. The firmware assigns a keycode to each
-key of the keyboard.
-The firmware does not send actually letters or characters, but only keycodes.
+The firmware does not send actually letters or characters, but only scancodes.
-Thus, by modifying the firmware, you only can modify what keycode is sent over
+Thus, by modifying the firmware, you only can modify what scancode is sent over
 USB for a given key.
 ## 3. What the Operating System Does
@@ -45,49 +39,31 @@ Once the keycode reaches the operating system, a piece of software has to have
 it match an actual character thanks to a keyboard layout. For example, if your
 layout is set to QWERTY, a sample of the matching table is as follow:
-``` text
 | keycode | character |
-|---------+-----------|
+|---------|-----------|
-|    0x04 | a/A       |
+| 0x04 | a/A |
-|    0x05 | b/B       |
+| 0x05 | b/B |
-|    0x06 | c/C       |
+| 0x06 | c/C |
-|     ... | ...       |
+| ... | ... |
-|    0x1C | y/Y       |
+| 0x1C | y/Y |
-|    0x1D | z/Z       |
+| 0x1D | z/Z |
-|     ... | ...       |
+| ... | ... |
-|---------+-----------|
-```
 ## Back to the firmware
-As the layout is generally fixed (unless you create your own), the firmware can
+As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in `keycode.txt`.
-actually call a keycode by its layout name directly to ease things for you.
-This is exactly what is done here with `KC_A` actually representing `0x04` in
-QWERTY. The full list can be found in `keycode.txt`.
 ## List of Characters You Can Send
-Putting aside shortcuts, having a limited set of keycodes mapped to a limited
+Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
-layout means that **the list of characters you can assign to a given key only
-is the ones present in the layout**.
-For example, this means that if you have a QWERTY US layout, and you want to
+For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
-assign 1 key to produce `€` (euro currency symbol), you are unable to do so,
-because the QWERTY US layout does not have such mapping. You could fix that by
-using a QWERTY UK layout, or a QWERTY US International.
-You may wonder why a keyboard layout containing all of Unicode is not devised
+You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
-then? The limited number of keycode available through USB simply disallow such
-a thing.
 ## How to (Maybe) Enter Unicode Characters
-You can have the firmware send *sequences of keys* to use the [software Unicode
+You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
-Input
-Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of
-the target operating system, thus effectively entering characters independently
-of the layout defined in the OS.
 Yet, it does come with multiple disadvantages:

diff --git a/docs/basic_how_keyboards_work.md b/docs/basic_how_keyboards_work.md index 73c3f5c5f..3969c5680 100644 --- a/docs/basic_how_keyboards_work.md +++ b/docs/basic_how_keyboards_work.md
@@ -23,20 +23,14 @@ in the next sections.
23	Whenever you press a key, the firmware of your keyboard can register this event.	23	Whenever you press a key, the firmware of your keyboard can register this event.
24	It can register when the key is pressed, held and released.	24	It can register when the key is pressed, held and released.
25		25
26	This usually happens with a [periodic scan of key presses with a frequency around 100 hz](https://github.com/benblazak/ergodox-firmware/blob/master/references.md#typical-keyboard-information).	26	This usually happens with a periodic scan of key presses. This speed often is limited by the mechanical key response time, the protocol to transfer those key presses (here USB HID), and by the software it is used in.
27	This speed often is limited by the mechanical key response time, the protocol
28	to transfer those key presses (here USB HID), and by the software it is used in.
29		27
30	## 2. What the Firmware Sends	28	## 2. What the Firmware Sends
31		29
32	The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf)	30	The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
33	tells what a keyboard can actually send through USB to have a chance to be
34	properly recognised. This includes a pre-defined list of keycodes which are
35	simple numbers from `0x00` to `0xE7`. The firmware assigns a keycode to each
36	key of the keyboard.
37		31
38	The firmware does not send actually letters or characters, but only keycodes.	32	The firmware does not send actually letters or characters, but only scancodes.
39	Thus, by modifying the firmware, you only can modify what keycode is sent over	33	Thus, by modifying the firmware, you only can modify what scancode is sent over
40	USB for a given key.	34	USB for a given key.
41		35
42	## 3. What the Operating System Does	36	## 3. What the Operating System Does
@@ -45,49 +39,31 @@ Once the keycode reaches the operating system, a piece of software has to have
45	it match an actual character thanks to a keyboard layout. For example, if your	39	it match an actual character thanks to a keyboard layout. For example, if your
46	layout is set to QWERTY, a sample of the matching table is as follow:	40	layout is set to QWERTY, a sample of the matching table is as follow:
47		41
48	``` text
49	\| keycode \| character \|	42	\| keycode \| character \|
50	\|---------+-----------\|	43	\|---------\|-----------\|
51	\| 0x04 \| a/A \|	44	\| 0x04 \| a/A \|
52	\| 0x05 \| b/B \|	45	\| 0x05 \| b/B \|
53	\| 0x06 \| c/C \|	46	\| 0x06 \| c/C \|
54	\| ... \| ... \|	47	\| ... \| ... \|
55	\| 0x1C \| y/Y \|	48	\| 0x1C \| y/Y \|
56	\| 0x1D \| z/Z \|	49	\| 0x1D \| z/Z \|
57	\| ... \| ... \|	50	\| ... \| ... \|
58	\|---------+-----------\|
59	```
60		51
61	## Back to the firmware	52	## Back to the firmware
62		53
63	As the layout is generally fixed (unless you create your own), the firmware can	54	As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in `keycode.txt`.
64	actually call a keycode by its layout name directly to ease things for you.
65
66	This is exactly what is done here with `KC_A` actually representing `0x04` in
67	QWERTY. The full list can be found in `keycode.txt`.
68		55
69	## List of Characters You Can Send	56	## List of Characters You Can Send
70		57
71	Putting aside shortcuts, having a limited set of keycodes mapped to a limited	58	Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that the list of characters you can assign to a given key only is the ones present in the layout.
72	layout means that **the list of characters you can assign to a given key only
73	is the ones present in the layout**.
74		59
75	For example, this means that if you have a QWERTY US layout, and you want to	60	For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
76	assign 1 key to produce `€` (euro currency symbol), you are unable to do so,
77	because the QWERTY US layout does not have such mapping. You could fix that by
78	using a QWERTY UK layout, or a QWERTY US International.
79		61
80	You may wonder why a keyboard layout containing all of Unicode is not devised	62	You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
81	then? The limited number of keycode available through USB simply disallow such
82	a thing.
83		63
84	## How to (Maybe) Enter Unicode Characters	64	## How to (Maybe) Enter Unicode Characters
85		65
86	You can have the firmware send sequences of keys to use the [software Unicode	66	You can have the firmware send sequences of keys to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
87	Input
88	Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of
89	the target operating system, thus effectively entering characters independently
90	of the layout defined in the OS.
91		67
92	Yet, it does come with multiple disadvantages:	68	Yet, it does come with multiple disadvantages:
93		69