romainl · September 23, 2022 08:14 · Sep 23, 2022 · Sep 21, 2022 · Aug 28, 2022
diff --git a/remaps.md b/remaps.md
@@ -1 +1,31 @@
-# Remaps
+# Remaps
+
+Yeah I know, when you see all those `vnoremap`s and `nnoremap`s in other people's `vimrc` or in plugin `README`s and you don't know how to read them, it is very tempting to attribute meaning to the part that looks like a normal english word:
+
+    nnoremap
+       ^^^^^ remap
+    ^^^      ?!?
+
+and go on and call those things "remaps".
+
+But "remap" is incorrect for two reasons:
+
+- you didn't parse the command name correctly so you see a word where there is none,
+- it implies that there is a map that you remap, which is more often than not wrong.
+
+The name of a mapping command is made of three parts: a mandatory radical and two optional modifiers:
+
+    [n][nore][map] ...
+              ^^^ radical
+        ^^^^      non-recursive modifier
+     ^            mode modifier
+
+- `:map` is the base command. Used on its own, as in `:map <F5> w`, it creates a recursive mapping for normal, visual, and operator-pending modes.
+- `nore` is short for "non-recursive". It means that, if you create a mapping that uses keys that may have a mapping attached to them, that mapping will be ignored. Without `nore`, your mapping is recursive so further mappings will be honored.
+- `n` is a single letter that tells Vim in which mode that mapping should be enabled. `n` is for normal mode, `i` is for insert mode, etc.
+
+So there is no `remap`, here.
+
+Once you have erroneously internalized that "remap" idea, it is not much of a stretch to understand it as a "remapping" of a mapping. While that could be true-ish for a well crafted recursive mapping, that is patently false for your run-off-the-mill non-recursive mapping because the stuff you put in your mappings are not mappings to begin with. `w` is not a mapping so thinking of the example above as a "remap" is just wrong.
+
+They are *mappings*, not "remaps".
diff --git a/Words-have-a-meaning.md b/Words-have-a-meaning.md
@@ -1,7 +0,0 @@
-In GUI applications, most functionalities are provided via menus: you open the "Edit" menu and you choose the "Paste" entry to paste the content of the clipboard. This is great for discovery but not optimal in the long run, especially for often used functionalities.
-
-That is why *shortcuts* exist. A given key combination is assigned to a given menu entry, making it unnecessary to open menus and submenus. Keyboard shortcuts are quite literally that, "shortcuts".
-
-In Vim, functionalities like "move the cursor to the beginning of next word" or "enter command-line mode" are not provided by menus, like in GUI applications, or by user-accessible low-level functions, like in Emacs: "move the cursor to the beginning of next word" **is** `w` and "enter command-line mode" **is** `:`. Those are not "shortcuts". Vim doesn't have "shortcuts".
-
-Interestingly enough, GVim and the MacVim GUI, being GUI applications, actually *have* menus and some menu entries even show a "shortcut". But don't be fooled, Vim menus are in fact implemented as mappings

diff --git a/command-mode.md b/command-mode.md
@@ -0,0 +1 @@
+# Command mode
diff --git a/macros.md b/macros.md
@@ -0,0 +1 @@
+# Macros
diff --git a/remaps.md b/remaps.md
@@ -0,0 +1 @@
+# Remaps
diff --git a/shortcuts.md b/shortcuts.md
@@ -0,0 +1,11 @@
+# Shortcuts
+
+In GUI applications, most functionalities are primarily provided via menus: you open the "Edit" menu and you choose the "Paste" entry to paste the content of the clipboard. This is great for discovery but it might not be optimal in the long run, because it makes it harder than necessary for the user to perform common tasks and for the developer to expose advanced or highly contextual functionalities.
+
+That is why *shortcuts* exist. A given key combination is assigned to a given menu entry, making it unnecessary to drill down menus and submenus. Keyboard shortcuts are quite literally that, "shortcuts".
+
+In Vim, functionalities like "move the cursor to the beginning of next word" or "enter command-line mode" are not provided by menus, like in GUI applications, or by user-accessible low-level functions, like in Emacs. "Move the cursor to the beginning of next word" **is** `w` and "enter command-line mode" **is** `:`. Those are not "shortcuts". Vim doesn't have "shortcuts" because there simply is no shorter way to "move the cursor to the beginning of next word" than pressing a single `w`.
+
+Interestingly enough, GVim and the MacVim GUI, being GUI applications, actually *have* menus and some menu entries even show something that could be confused with a "shortcut". But don't be fooled, Vim menus are in fact implemented as mappings, effectively turning the whole concept on its head. Where regular GUI applications have menus and shortcuts to those menus, Vim implements its menus as mappings to built-in commands and displays those original commands where one would expect shortcuts. This is all a bit confusing, to be honest.
+
+The takeaway is this: when talking about Vim, don't use the word "shortcut" because there are no shortcuts.
diff --git a/tabs.md b/tabs.md
@@ -0,0 +1 @@
+# Tabs
diff --git a/Words-have-a-meaning.md b/Words-have-a-meaning.md
@@ -0,0 +1,7 @@
+In GUI applications, most functionalities are provided via menus: you open the "Edit" menu and you choose the "Paste" entry to paste the content of the clipboard. This is great for discovery but not optimal in the long run, especially for often used functionalities.
+
+That is why *shortcuts* exist. A given key combination is assigned to a given menu entry, making it unnecessary to open menus and submenus. Keyboard shortcuts are quite literally that, "shortcuts".
+
+In Vim, functionalities like "move the cursor to the beginning of next word" or "enter command-line mode" are not provided by menus, like in GUI applications, or by user-accessible low-level functions, like in Emacs: "move the cursor to the beginning of next word" **is** `w` and "enter command-line mode" **is** `:`. Those are not "shortcuts". Vim doesn't have "shortcuts".
+
+Interestingly enough, GVim and the MacVim GUI, being GUI applications, actually *have* menus and some menu entries even show a "shortcut". But don't be fooled, Vim menus are in fact implemented as mappings