Add overview section to DESIGN.md

DESIGN.md

@@ -1,5 +1,13 @@
 # Design
 
+## Overview
+
+The aim of this extension is to make keyboard macro recording possible on VS Code.
+
+For years no one seemed to have achieved this in a suitable way for practical use. Through this challenge, I have found a couple of difficulties that justify the absence of this kind of extension.
+
+This document covers some of the difficulties and my solutions.
+
 ## Recording keystrokes vs. recording commands
 
 First of all, we don't have any VS Code API that allows us to capture command executions at this moment. But, we could imagine that we have an event API for that. Let's name it `onDidExecuteCommand`.
@@ -41,35 +49,36 @@ We use the wrapper command only when the macro recording is ongoing. So we add t
 
 Why don't we use the wrapper keybindings always to simplify things? Because we want to keep the original behavior of each command for the keybindings as much as possible. It is not clear but the indirect execution may not be perfectly transparent.
 
-## Default wrapper keybindings
+## Default keybindings wrappers
 
 This extension defines a large set of keybindings to capture all the default keyboard shortcuts of VS Code.
 
-The list of default wrapper keybindings is defined in the [`package.json` of this extension](package.json). The list is automatically generated by a script [`generator/gen_wrapper.js`](generator/gen_wrapper.js). The script takes JSON files where each one contains the default keybindings of VS Code for Windows, Linux, and macOS respectively, and combines all the keybindings in them with additional context such as `isWindows`, `isLinux`, or `isMac` as needed, and convert them to wrappers and write them into `keybindings` section of the `package.json`.
-
-The script also performs some optimization work to reduce the amount of wrapper keybinding rules.
+The list of default keybindings wrappers is defined in the [`package.json` of this extension](package.json). The list is automatically generated by a script [`generator/gen_wrapper.js`](generator/gen_wrapper.js). The script takes JSON files where each one contains the default keybindings of VS Code for Windows, Linux, and macOS respectively, and combines all the keybindings in them with additional context such as `isWindows`, `isLinux`, or `isMac` as needed, and convert them to wrappers and write them into `keybindings` section of the `package.json`.
 
 | Related files |     |
 | ------------- | --- |
 | `generator/default-keybindings-win.json` | the default keybindings of VS Code for Windows |
 | `generator/default-keybindings-linux.json` | the default keybindings of VS Code for Linux |
 | `generator/default-keybindings-mac.json` | the default keybindings of VS Code for macOS |
-| `generator/gen_wrapper.js` | a script to generate default wrapper keybindings and write them in `package.json` |
+| `generator/gen_wrapper.js` | a script to generate default keybindings wrappers and write them in `package.json` |
 | `generator/verify_wrapper.js` | a script to verify the output of `gen_wrapper.js` |
 
 The `default-keybindings-*.json` files are retrieved by running the `Open Default Keyboard Shortcuts (JSON)` command on VS Code on each OS. In order to mitigate manual work to retrieve these three files, [an automated workflow on GitHub Actions](https://github.com/tshino/vscode-kb-macro/actions/workflows/get-default-keybindings.yml) is used.
 
-The following command updates the default wrapper keybindings in the `package.json` based on the default keybindings files.
+The following command updates the default keybindings wrappers in the `package.json` based on the default keybindings files.
 
 ```
 npm run gen-wrapper
 ```
 
+This script also performs some optimization work to reduce the amount of wrapper keybinding rules.
+
+
 ## Capturing typed characters
 
 On VS Code, typed characters in text editors are treated differently than other keystrokes. We don't put every possible character in the keybindings. When you type characters in a text editor, for each character, the `type` built-in command is invoked internally. The `type` command performs inserting each character into the document.
 
-As far as I know, an extension is allowed to override the `type` built-in command using `vscode.commands.registerCommand` API. Actually, the VSCodeVim extension seems to do that to customize the behavior for typed characters.
+As far as I know, an extension is allowed to override the `type` built-in command using `vscode.commands.registerCommand` API. Actually, the [VSCodeVim](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) extension seems to do that to customize the behavior for typed characters.
 
 It was not clear whether overriding the `type` command to capture typed characters is a good way for this extension. Especially if you use this extension combined with another extension that is overriding the `type` command too, there would be a conflict, and likely they will not work correctly. See [vscode#13441](https://github.com/Microsoft/vscode/issues/13441).