docs(README): update

abgox · Aug 20, 2024 · f55536f · f55536f
1 parent 5b6a91c
commit f55536f
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 63 deletions.
diff --git a/README-CN.md b/README-CN.md
@@ -44,13 +44,14 @@
   > `Windows PowerShell` 也可以使用此模块，但更推荐使用 `PowerShell`
 - [集中管理补全](#补全列表 "点击查看可添加补全列表！")
 - `en-US`,`zh-CN`,... 多语言切换
-- 动态排序补全候选(根据使用频次)
+- 动态排序补全项(根据使用频次)
 - [提供了一个更好用的补全菜单](#关于补全菜单)
 
-**如果 PSCompletions 对你有所帮助，请在右上角点个 Star ⭐**
+**如果 PSCompletions 对你有所帮助，请在此项目点个 Star ⭐**
 
-## 新功能
-请查阅[更新日志](./module/CHANGELOG-CN.md)
+## 新的变化
+
+请查阅 [更新日志](./module/CHANGELOG-CN.md)
 
 ## 安装
 
@@ -74,12 +75,16 @@
 
 1. `psc add git`
 2. 然后你就可以输入 `git`, 按下 `Space`(空格键) `Tab` 键来获得命令补全
-3. 关于 `psc` 的更多命令用法，你只需要输入 `psc` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解
+3. 关于 `psc` 的更多命令用法，你只需要输入 `psc` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过 [补全提示信息](#关于补全提示信息) 来了解
 
 ## Demo
 
 ![demo](https://pscompletions.pages.dev/demo-CN.gif)
 
+## 贡献
+
+- 请查阅 [CONTRIBUTING.md](./.github/contributing.md)
+
 ## Tips
 
 ### 关于补全触发按键
@@ -94,17 +99,18 @@
 
 ### 关于补全菜单
 
-- 除了语言内置的补全菜单，`PSCompletions` 模块还提供了一个好用的补全菜单。
+- 除了语言内置的补全菜单，`PSCompletions` 模块还提供了一个更好用的补全菜单。
   - 配置: `psc menu config menu_enable 1` (默认开启)
 - 模块提供的补全菜单基于 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) 的实现思路，感谢 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) !
 - 模块提供的补全菜单可用的 Windows 环境：
-  - `PowerShell` <img src="https://img.shields.io/badge/v4.0.0+-4CAF50" alt="v4.0.0+ support" />
-  - `Windows PowerShell` <img src="https://img.shields.io/badge/v4.1.0+-4CAF50" alt="v4.1.0+ support" />
+  - `PowerShell` <img src="https://img.shields.io/badge/module%20version-v4.0.0+-4CAF50" alt="v4.0.0+ support" />
+  - `Windows PowerShell` <img src="https://img.shields.io/badge/module%20version-v4.1.0+-4CAF50" alt="v4.1.0+ support" />
     - 由于 `Windows PowerShell` 渲染问题，补全菜单的边框样式无法自定义
+    - 如果需要自定义，请使用 `PowerShell`
 - 模块提供的补全菜单中的按键
 
   1. 选用当前选中的补全项: `Enter`(回车键)
-     - 当只有一个可选项时，也可以使用 `Tab` 或 `Space` 键
+     - 当只有一个补全项时，也可以使用 `Tab` 或 `Space`(空格) 键
   2. 删除过滤字符: `Backspace`(退格键)
   3. 退出补全菜单: `ESC` / `Ctrl + c`
      - 当过滤区域没有字符时，也可以使用 `Backspace`(退格键) 退出补全菜单
@@ -119,32 +125,35 @@
      |   `Ctrl + u`    | `Ctrl + d` |
      |   `Ctrl + p`    | `Ctrl + n` |
 
-- 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解
+- 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过 [补全提示信息](#关于补全提示信息) 来了解
   - 对于配置的值，`1` 表示 `true`，`0` 表示 `false` (这适用于 `PSCompletions` 的所有配置)
 
-#### 关于菜单增强
-
-- <img src="https://img.shields.io/badge/v4.2.0+-4CAF50" alt="v4.2.0+ support" />
+#### 关于菜单增强 <img src="https://img.shields.io/badge/module%20version-v4.2.0+-4CAF50" alt="v4.2.0+ support" />
 
 - 配置: `psc menu config menu_enhance 1` 默认开启
 - 现在，`PSCompletions` 对于补全有两种实现
 
-  1. `Register-ArgumentCompleter`
+  1. [`Register-ArgumentCompleter`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter)
 
-     - <img src="https://img.shields.io/badge/v4.1.0-4CAF50" alt="v4.1.0 support" /> 及之前版本都使用此实现
-     - <img src="https://img.shields.io/badge/v4.2.0+-4CAF50" alt="v4.2.0+ support" />: 此实现变为可选
-       - 你可以通过设置 `menu_enhance` 为 `0` 来继续使用它
+     - <img src="https://img.shields.io/badge/module%20version-v4.1.0-4CAF50" alt="v4.1.0 support" /> 及之前版本都使用此实现
+     - <img src="https://img.shields.io/badge/module%20version-v4.2.0+-4CAF50" alt="v4.2.0+ support" />: 此实现变为可选
+       - 你可以运行 `psc menu config menu_enhance 0` 来继续使用它
        - 但并不推荐，它只能用于 `psc add` 添加的补全
 
-  2. `Set-PSReadLineKeyHandler`
-     - <img src="https://img.shields.io/badge/v4.2.0+-4CAF50" alt="v4.2.0+ support" />: 默认使用此实现
+  2. [`Set-PSReadLineKeyHandler`](https://learn.microsoft.com/powershell/module/psreadline/set-psreadlinekeyhandler)
+     - <img src="https://img.shields.io/badge/module%20version-v4.2.0+-4CAF50" alt="v4.2.0+ support" />: 默认使用此实现
        - 需要 `menu_enable` 和 `menu_enhance` 同时为 `1`
      - 它不再需要循环为所有补全命令注册 `Register-ArgumentCompleter`，理论上加载速度会更快
      - 同时使用 [`TabExpansion2`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2) 全局管理补全，不局限于 `psc add` 添加的补全
+       - 例如:
+         - `cd`/`.\`/`..\`/`~\`/... 这样的路径补全
+         - `Get-*`/`Set-*`/`New-*`/... 这样的内置命令补全
+         - 由 cli 或模块注册的补全
+         - ...
 
 ### 关于特殊符号
 
-- 补全项后面的特殊符号用于在按下 `Tab` 键之前提前感知是否有可用的补全候选项
+- 补全项后面的特殊符号用于在按下 `Tab` 键之前提前感知是否有可用的补全项
 
   - 如果你不需要也不想看到这些符号, 可以将它们替换成空字符串以隐藏它们
     - `psc menu symbol SpaceTab ""`
@@ -153,15 +162,20 @@
 
 - 😄🤔😎 : 如果出现多个, 表示符合多个条件, 可以选择其中一个效果
 
-  - 😄 : 表示选用当前选中的补全后, 可以按下 `Space`(空格键) 和 `Tab` 键继续获取补全(普通补全或选项类补全)
+  - 定义:
+    - `Normal Completion`: 子命令，例如在 `git` 中的 `add`/`pull`/`push`/`commit`/...
+    - `Optional Completion`: 可选参数，例如在 `git add` 中的 `-g`/`-u`/...
+    - `General Optional Completion`: 可以用在任何地方的通用可选参数，例如在 `git` 中的 `--help`/...
+  - 😄 : 表示选用当前选中的补全后, 可以按下 `Space`(空格键) 和 `Tab` 键继续获取 `Normal Completion` 或者 `Optional Completion`
+    - 仅在有 `Normal Completion` 或 `Optional Completion` 时才会显示此符号
     - 可通过 `psc menu symbol SpaceTab <symbol>` 自定义此符号
-  - 🤔 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全(如 --verbose)
-    - 通用选项类补全共用此符号，它可以在任何位置触发，不会影响它们
+  - 🤔 : 表示选用当前选中的补全(`Optional Completion`)后, 你可以按下 `Space`(空格键) 和 `Tab` 键继续获取其他的 `Optional Completion`
+    - `General Optional Completion` 也使用此符号
     - 可通过 `psc menu symbol OptionTab <symbol>` 自定义此符号
-  - 😎 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键), 再输入一个字符串, 然后按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全
+  - 😎 : 表示选用当前选中的补全(`Optional Completion` 或者 `General Optional Completion`)后, 你可以按下 `Space`(空格键), 再输入一个字符串, 然后按下 `Space`(空格键) 和 `Tab` 键继续获取其他的 `Optional Completion` 或者 `General Optional Completion`
 
-    - 如果字符串有空格, 请使用 `"`(引号) 或 `'`(单引号) 包裹，如 "test content"
-    - 如果同时还有 😄, 表示有几个预设的字符串可以补全, 你可以不输入字符串, 直接按下 `Space`(空格键) 和 `Tab` 键继续获取补全
+    - 如果字符串有空格, 请使用 `"`(引号) 或 `'`(单引号) 包裹，如 `"test content"`
+    - 如果同时还有 😄, 表示有几个预设的字符串(`Normal Completion`)可以补全, 你可以不输入字符串, 直接按下 `Space`(空格键) 和 `Tab` 键继续获取它们
     - 可通过 `psc menu symbol WriteSpaceTab <symbol>` 自定义此符号
 
   - 所有补全都可以在输入部分字符后按下 `Tab` 键触发补全
@@ -202,7 +216,7 @@
   - `psc config language` 可以查看全局的语言配置
   - `psc config language zh-CN` 可以更改全局的语言配置
 - `Completion language`: 为指定的补全设置的语言
-  - e.g. `psc completion git language en-US`
+  - 例如: `psc completion git language en-US`
 - `Available language`: 每一个补全的 `config.json` 文件中有一个 `language` 属性，它的值是一个可用的语言列表
 
 #### 确定语言

diff --git a/README.md b/README.md
@@ -36,21 +36,22 @@
 
 - [`PowerShell`](https://github.com/PowerShell/PowerShell): A Cross-platform PowerShell. Start it in command line by running `pwsh`.
 
-- [`Windows PowerShell`](https://learn.microsoft.com/powershell/scripting/what-is-windows-powershell): A PowerShell which is built-in on Windows systems. Start it in command line by running `powershell`.
+- [`Windows PowerShell`](https://learn.microsoft.com/powershell/scripting/what-is-windows-powershell): A PowerShell which is built-in on Windows system. Start it in command line by running `powershell`.
 
 ---
 
 - A completion manager in `PowerShell` for better and simpler use completions.
   > It can also be used in `Windows PowerShell`, but it's a better choice to use `PowerShell`.
 - [Manage completions together.](#available-completions-list "Click it to view the completion list that can be added !")
 - Switch between languages(`en-US`,`zh-CN`,...) freely.
-- Sort completion tab dynamically by frequency of use.
-- [It provides a useful completion menu.](#about-completion-menu)
+- Sort completion items dynamically by frequency of use.
+- [It provides a better completion menu.](#about-completion-menu)
 
 **If this project is helpful to you, please consider giving it a star ⭐.**
 
-## what's new
-please refer to [changelog](./module/CHANGELOG.md)
+## What's new
+
+Please read the [CHANGELOG](./module/CHANGELOG.md).
 
 ## How to install
 
@@ -80,6 +81,10 @@ please refer to [changelog](./module/CHANGELOG.md)
 
 ![demo](https://pscompletions.pages.dev/demo.gif)
 
+## Contribution
+
+Please read [CONTRIBUTING.md](./.github/contributing.md).
+
 ## Tips
 
 ### About the completion trigger key
@@ -94,20 +99,24 @@ please refer to [changelog](./module/CHANGELOG.md)
 
 ### About completion menu
 
-- In addition to the language's built-in completion menu, `PSCompletions` module also provides a useful completion menu.
+- In addition to the language's built-in completion menu, `PSCompletions` module also provides a better completion menu.
+
+  - Setting: `psc menu config menu_enable 1` (Default: `1`)
 
 - The module's completion menu provided by the module is based on [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) realization idea, thanks!
 
 - Available Windows environment:
-  - `PowerShell` <img src="https://img.shields.io/badge/v4.0.0+-4CAF50" alt="v4.0.0+ support" />
-  - `Windows PowerShell` <img src="https://img.shields.io/badge/v4.1.0+-4CAF50" alt="v4.1.0+ support" />
+  - `PowerShell` <img src="https://img.shields.io/badge/module%20version-v4.0.0+-4CAF50" alt="v4.0.0+ support" />
+  - `Windows PowerShell` <img src="https://img.shields.io/badge/module%20version-v4.1.0+-4CAF50" alt="v4.1.0+ support" />
     - Due to rendering problems of `Windows PowerShell`, the border style of the completion menu cannot be customized.
+      - If you need to customize it, use `PowerShell`.
 - Some keys in the completion menu provided by the module.
 
   1. Apply the selected completion item: `Enter`
+     - You can also use `Tab` or `Space` when there's only one completion.
   2. Delete filter characters: `Backspace`
-  3. Exit the completion menu: `ESC` / `Ctrl + c`
-     - When there are no characters in the filter area, you can also use `Backspace` key to exit the completion menu.
+  3. Exit the completion menu: `Esc` / `Ctrl + c`
+     - You can also use `Backspace` when there're no characters in the filter area.
   4. Select completion item:
 
      | Select previous item | Select next item |
@@ -122,27 +131,26 @@ please refer to [changelog](./module/CHANGELOG.md)
 - All configurations of it, you can trigger completion by running `psc menu`, then learn about them by [the completion tip](#about-completion-tip).
   - For configured values, `1` means `true` and `0` means `false`. (It applies to all configurations of `PSCompletions`)
 
-#### About menu enhance
-
-- <img src="https://img.shields.io/badge/v4.2.0+-4CAF50" alt="v4.2.0+ support" />
-
-- config: `psc menu config menu_enhance 1` (Default: `1`)
-- Now, `PSCompletions` has two completion implementations
-
-  1. `Register-ArgumentCompleter`
-
-     - <img src="https://img.shields.io/badge/v4.1.0-4CAF50" alt="v4.1.0 support" /> : It's used.
-     - <img src="https://img.shields.io/badge/v4.2.0+-4CAF50" alt="v4.2.0+ support" />: It's optional.
+#### About menu enhance <img src="https://img.shields.io/badge/module%20version-v4.2.0+-4CAF50" alt="v4.2.0+ support" />
 
-       - You can use it by running `psc menu config menu_enable 0`.
-       - It' Not recommended. It only works for completions added by `psc add`.
+- Setting: `psc menu config menu_enhance 1` (Default: `1`)
+- Now, `PSCompletions` has two completion implementations.
 
-  2. `Set-PSReadLineKeyHandler`
-     - <img src="https://img.shields.io/badge/v4.2.0+-4CAF50" alt="v4.2.0+ support" />: It's used by default.
-       - Requires: `menu_enable`and `menu_enhance` both set to `1`.
+  1. [`Register-ArgumentCompleter`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter)
+     - <img src="https://img.shields.io/badge/module%20version-v4.1.0-4CAF50" alt="v4.1.0 support" /> : It's used.
+     - <img src="https://img.shields.io/badge/module%20version-v4.2.0+-4CAF50" alt="v4.2.0+ support" />: It's optional.
+       - You can use it by running `psc menu config menu_enhance 0`.
+       - It's not recommended. It only works for completions added by `psc add`.
+  2. [`Set-PSReadLineKeyHandler`](https://learn.microsoft.com/powershell/module/psreadline/set-psreadlinekeyhandler)
+     - <img src="https://img.shields.io/badge/module%20version-v4.2.0+-4CAF50" alt="v4.2.0+ support" />: It's used by default.
+       - Requires: `menu_enable` and `menu_enhance` both set to `1`.
      - It no longer needs to loop through registering `Register-ArgumentCompleter` for all completions, which theoretically makes loading faster.
      - It use [`TabExpansion2`](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/tabexpansion2) to manage completions globally, not limited to those added by `psc add`.
-       - For example, commands such as `Get-*`/`Set-*`/... in `PowerShell` will use the completion menu provided by `PSCompletions` to render the completion.
+       - For example:
+         - Path completion such as `cd`/`.\`/`..\`/`~\`/... in `PowerShell`.
+         - Build-in commands such as `Get-*`/`Set-*`/`New-*`/... in `PowerShell`.
+         - Completion registered by cli or module.
+         - ...
 
 ### About special symbols
 
@@ -154,14 +162,19 @@ please refer to [changelog](./module/CHANGELOG.md)
     - `psc menu symbol WriteSpaceTab ""`
 
 - 😄🤔😎 : If there are multiple, you can choose the effect of one of them.
-  - 😄 : It means that after you apply it, you can press `Space` and `Tab` key to continue to get command completions.(Normal or optional completions)
+  - Define them:
+    - `Normal Completion`: Sub-commands. Such as `add`/`pull`/`push`/`commit`/... in `git`.
+    - `Optional Completion`: Optional parameters. Such as `-g`/`-u`/... in `git add`.
+    - `General Optional Completion`: General optional parameters that can be used with any command. Such as `--help`/... in `git`.
+  - 😄 : It means that after you apply it, you can press `Space` and `Tab` key to continue to get `Normal Completion` or `Optional Completion`.
+    - It will appear only when there's `Normal Completion` or `Optional Completion`.
     - It can be customized by running `psc menu symbol SpaceTab <symbol>`
-  - 🤔 : It means that after you apply it (option completion), you can press `Space` and `Tab` key to continue to get option completions. (e.g. `--verbose`)
-    - Generic optional completions shares this symbol, but it does not affect them.
+  - 🤔 : It means that after you apply it (`Optional Completion`), you can press `Space` and `Tab` key to continue to get other `Optional Completion`.
+    - `General Optional Completion` use also this symbol.
     - It can be customized by running `psc menu symbol OptionTab <symbol>`
-  - 😎 : It means that after you apply it (option completion), you can press `Space` and enter a string, then press `Space` and `Tab` key to continue to get the rest of option completions.
-    - If the string has Spaces, Please use `"`(quote) or `'`(single quote) to wrap it. e.g. "test content"
-    - If there is also 😄, it means that there are some strings to complete, you can press `Space` and `Tab` key to continue to get command completions without entering a string.
+  - 😎 : It means that after you apply it (`Optional Completion` or `General Optional Completion`), you can press `Space` and enter a string, then press `Space` and `Tab` key to continue to get other `Optional Completion` or `General Optional Completion`.
+    - If the string has Spaces, Please use `"`(quote) or `'`(single quote) to wrap it. e.g. `"test content"`
+    - If there's also 😄, it means that there's `Normal Completion`, you can press `Space` and `Tab` key to continue to get them without entering a string.
     - It can be customized by running `psc menu symbol WriteSpaceTab <symbol>`
   - All completions can be triggered by pressing the `Tab` key after entering a part.
 
@@ -196,8 +209,8 @@ please refer to [changelog](./module/CHANGELOG.md)
 ### About language
 
 - `Global language`: Default to the language of current system.
-  - You can show it by running `psc config language`
-  - You can change it by running `psc config language zh-CN`
+  - You can show it by running `psc config language`.
+  - You can change it by running `psc config language zh-CN`.
 - `Completion language`: The language set for the specified completion.
   - e.g. `psc completion git language en-US`.
 - `Available language`: In the completion `config.json` file, there is a `language` attribute whose value is a list of available languages.
@@ -229,7 +242,7 @@ please refer to [changelog](./module/CHANGELOG.md)
   - **`Completion`** ：Click to view to the official website of the command. Sort by first letter(0-9,a-z).
     - Special case: `abc(a)`, it means that you need to download it by `psc add abc`, but by default `a` is used instead of `abc` to trigger the completion.
   - **`Language`**: Supported Languages, and Translation Progress.
-    - The translation progress is compared to `en-US`
+    - The translation progress is compared to `en-US`.
   - **`Description`**: Command Description.
 
 <!-- prettier-ignore-start -->