feat(README): update

abgox · Aug 7, 2024 · 761e2eb · 761e2eb
1 parent 01101fd
commit 761e2eb
Show file tree

Hide file tree

Showing 2 changed files with 131 additions and 34 deletions.
diff --git a/README-CN.md b/README-CN.md
@@ -10,6 +10,9 @@
 </p>
 
 <p align="center">
+    <a href="https://github.com/abgox/PSCompletions">
+        <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fabgox%2Fabgo_bucket%2Fmain%2Fbucket%2FPSCompletions.json&query=%24.version&label=version" alt="module version" />
+    </a>
     <a href="https://github.com/abgox/PSCompletions/blob/main/LICENSE">
         <img src="https://img.shields.io/github/license/abgox/PSCompletions" alt="license" />
     </a>
@@ -28,26 +31,29 @@
 
 ## 介绍
 
-- `PowerShell`: 跨平台的 PowerShell。命令行中运行 `pwsh` 启动
+- [`PowerShell`](https://github.com/PowerShell/PowerShell): 跨平台的 PowerShell。命令行中运行 `pwsh` 启动
 
-- `Windows PowerShell`: Windows 系统内置的 PowerShell。命令行中运行 `powershell` 启动
+- [`Windows PowerShell`](https://learn.microsoft.com/powershell/scripting/what-is-windows-powershell): Windows 系统内置的 PowerShell。命令行中运行 `powershell` 启动
 
 ---
 
 - 一个 `PowerShell` 补全管理模块，更好、更简单、更方便的使用和管理补全
-  > `Windows PowerShell` 也可以使用此模块，但不建议
+  > `Windows PowerShell` 也可以使用此模块，但更推荐使用 `PowerShell`
 - [集中管理补全](#补全列表 "点击查看可添加补全列表！")
 - `en-US`,`zh-CN`,... 多语言切换
 - 动态排序补全候选(根据使用频次)
+- [提供了一个更好用的补全菜单](#关于补全菜单)
 
 **如果 PSCompletions 对你有所帮助，请在右上角点个 Star ⭐**
 
 ## 安装
 
 1. 打开 `PowerShell`
 2. `Install-Module PSCompletions -Scope CurrentUser`
+   > - 除非你确定始终会使用管理员权限打开 `PowerShell`，否则不要省略 `-Scope CurrentUser`
 3. `Import-Module PSCompletions`
-   - 如果不想每次启动 `PowerShell` 都导入一次，就执行 `echo "Import-Module PSCompletions" >> $PROFILE`
+   - 如果不想每次启动 `PowerShell` 都需要导入 `PSCompletions` 模块，你可以将导入语句写入 `$PROFILE` 中
+   - `echo "Import-Module PSCompletions" >> $PROFILE`
 
 ## 卸载
 
@@ -61,8 +67,8 @@
 - 如果补全列表里没有你想要的补全，你可以 [提交 issues](https://github.com/abgox/PSCompletions/issues "点击提交 issues")
 
 1. `psc add git`
-2. 然后你就可以输入 `git`,按下 `Space`(空格键) `Tab` 键来获得命令补全
-3. 关于 `psc` 的更多命令，你可以输入 `psc` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过命令提示信息来了解
+2. 然后你就可以输入 `git`, 按下 `Space`(空格键) `Tab` 键来获得命令补全
+3. 关于 `psc` 的更多命令用法，你只需要输入 `psc` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解
 
 ## Demo
 
@@ -77,16 +83,20 @@
 
 ### 关于补全更新
 
-- 当打开 `PowerShell` 并导入 `PSCompletions` 后，`PSCompletions` 会开启一个后台作业去检查远程仓库中补全的状态
+- 当打开 `PowerShell` 并导入 `PSCompletions` 模块后，`PSCompletions` 会开启一个后台作业去检查远程仓库中补全的状态
 - 获取到更新后，会在下一次打开 `PowerShell` 并导入 `PSCompletions` 后显示补全更新提示
 
 ### 关于补全菜单
 
+- 除了语言内置的补全菜单，`PSCompletions` 模块还提供了一个好用的补全菜单。
 - 模块提供的补全菜单基于 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) 的实现思路，感谢 [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) !
-- 模块提供的补全菜单只能在 Windows 系统下使用 PowerShell(pwsh) 运行, 其他环境只能使用 PowerShell 自带的补全菜单
+- 模块提供的补全菜单可用的 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" />
+    - 由于 `Windows PowerShell` 渲染问题，补全菜单的边框样式无法自定义
 - 模块提供的补全菜单中的按键
 
-  1. 应用选中的补全项: `Enter`(回车键)
+  1. 选用当前选中的补全项: `Enter`(回车键)
   2. 删除过滤字符: `Backspace`(退格键)
   3. 退出补全菜单: `ESC` / `Ctrl + c`
      - 当过滤区域没有字符时，也可以使用 `Backspace`(退格键) 退出补全菜单
@@ -101,31 +111,69 @@
      |   `Ctrl + u`    | `Ctrl + d` |
      |   `Ctrl + p`    | `Ctrl + n` |
 
-- 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过命令提示信息来了解
+- 补全菜单的所有配置, 你可以输入 `psc menu` 然后按下 `Space`(空格键) `Tab` 键触发补全，通过[补全提示信息](#关于补全提示信息)来了解
   - 对于配置的值，`1` 表示 `true`，`0` 表示 `false` (这适用于 `PSCompletions` 的所有配置)
 
 ### 关于特殊符号
 
-- 😄🤔😎 : 如果出现多个, 表示符合多个条件, 可以选择其中一个的效果
+- 补全项后面的特殊符号用于在按下 `Tab` 键之前提前感知是否有可用的补全候选项
+
+  - 如果你不需要也不想看到这些符号, 可以将它们替换成空字符串以隐藏它们
+    - `psc menu symbol SpaceTab ""`
+    - `psc menu symbol OptionTab ""`
+    - `psc menu symbol WriteSpaceTab ""`
+
+- 😄🤔😎 : 如果出现多个, 表示符合多个条件, 可以选择其中一个效果
 
   - 😄 : 表示选用当前选中的补全后, 可以按下 `Space`(空格键) 和 `Tab` 键继续获取补全(普通补全或选项类补全)
     - 可通过 `psc menu symbol SpaceTab <symbol>` 自定义此符号
-    - 如: `psc menu symbol SpaceTab ""` 设置为空字符串
   - 🤔 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全(如 --verbose)
+    - 通用选项类补全共用此符号，它可以在任何位置触发，不会影响它们
     - 可通过 `psc menu symbol OptionTab <symbol>` 自定义此符号
   - 😎 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键), 再输入一个字符串, 然后按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全
 
-    - 如果字符串有空格, 请使用 "" 或 '' 包裹，如 "test content"
+    - 如果字符串有空格, 请使用 `"`(引号) 或 `'`(单引号) 包裹，如 "test content"
     - 如果同时还有 😄, 表示有几个预设的字符串可以补全, 你可以不输入字符串, 直接按下 `Space`(空格键) 和 `Tab` 键继续获取补全
     - 可通过 `psc menu symbol WriteSpaceTab <symbol>` 自定义此符号
 
-  - 如果存在通用选项类补全, 也可以触发通用选项的补全
-  - 所有补全都可以在输入部分后按下 `Tab` 键触发补全
-  - 如果你不需要也不想看到这些符号, 可以将它们替换成空字符串。如: `psc menu symbol SpaceTab ""`
+  - 所有补全都可以在输入部分字符后按下 `Tab` 键触发补全
+    - 在 `Windows PowerShell` 中，输入 `-` 或 `--` 后按下 `Tab`键是无法获取补全的
+    - 你应该先按下 `Tab` 键触发补全菜单，然后输入 `-` 或 `--` 进行筛选
+    - 这个问题在 `PowerShell` 中不存在
 
 - 使用 PowerShell 语言自带的补全菜单时, 如果 `...` 是最后一个补全, 则表示可显示区域过小, 无法显示所有候选项
 - 使用模块提供的补全菜单时, 如果补全提示信息末尾出现 `...`, 则表示当前显示区域宽度不够, 提示信息显示不完整
 
+### 关于补全提示信息
+
+- 补全提示信息只是辅助, 你也可以使用 `psc menu config menu_show_tip 0` 来禁用补全提示信息
+
+  - 启用补全提示信息: `psc menu config menu_show_tip 1`
+  - 也可以禁用特定补全的提示信息，如 `psc`
+    - `psc completion psc menu_show_tip 0`
+
+- 补全提示信息一般由三部分组成: 用法(Usage) + 描述(Description) + 举例(Example)
+  ```txt
+  U: install|add [-g|-u] [options] <app>
+  这里是命令的描述说明
+  在 U: 和 E: 之间的内容都是命令描述
+  E: install xxx
+     add -g xxx
+  ```
+- 示例解析:
+
+  1.  用法: 以 `U:` 开头(Usage)
+
+      - 命令名称: `install`
+      - 命令别名: `add`
+      - 必填参数: `<app>`
+        - `app` 是对必填参数的简要概括
+      - 可选参数: `-g` `-u`
+      - `[options]` 表示泛指一些选项类参数
+
+  2.  描述: 在 `U:` 和 `E:` 之间的内容
+  3.  举例: 以 `E:` 开头(Example)
+
 ### 关于语言
 
 - `Global language`: 默认为当前的系统语言
@@ -147,12 +195,13 @@
 
 - 以 `git` 为例，当输入 `git add`，此时按下 `Space` 和 `Tab` 键，不会触发路径补全，只会触发模块提供的命令补全
 - 如果你希望触发路径补全，你需要输入内容
-- 只要输入的内容符合这个正则 `^\.*[\\/].*`，都会去获取路径补全，这是 PowerShell 的补全，与模块无关
+- 只要输入的内容符合这个正则 `^\.*[\\/]*`，都会触发 `PowerShell` 的路径补全
 - 比如:
 
   - 输入 `./` 或 `.\` 后按下 `Tab` 以获取 **子目录** 或 **文件** 的路径补全
   - 输入 `../` 或 `..\` 后按下 `Tab` 以获取 **父级目录** 或 **文件** 的路径补全
   - 输入 `/` 或 `\` 后按下 `Tab` 以获取 **同级目录** 的路径补全
+  - 更多的: `.` / `~/` / `../../` ...
 
 - 因此，你应该输入 `git add ./` 这样的命令再按下 `Tab` 键来获取路径补全
 

diff --git a/README.md b/README.md
@@ -3,13 +3,16 @@
 </p>
 
 <p align="center">
-    <a href="README.md">English</a> |
     <a href="README-CN.md">简体中文</a> |
+    <a href="README.md">English</a> |
     <a href="https://github.com/abgox/PSCompletions">Github</a> |
     <a href="https://gitee.com/abgox/PSCompletions">Gitee</a>
 </p>
 
 <p align="center">
+    <a href="https://github.com/abgox/PSCompletions">
+        <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fabgox%2Fabgo_bucket%2Fmain%2Fbucket%2FPSCompletions.json&query=%24.version&label=version" alt="module version" />
+    </a>
     <a href="https://github.com/abgox/PSCompletions/blob/main/LICENSE">
         <img src="https://img.shields.io/github/license/abgox/PSCompletions" alt="license" />
     </a>
@@ -28,27 +31,29 @@
 
 ## Introduce
 
-- `PowerShell`: A Cross-platform PowerShell. Start it in command line by running `pwsh`.
+- [`PowerShell`](https://github.com/PowerShell/PowerShell): A Cross-platform PowerShell. Start it in command line by running `pwsh`.
 
-- `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 systems. 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`.(Not Recommend)
+  > 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)
 
 **If this project is helpful to you, please consider giving it a star ⭐.**
 
 ## How to install
 
 1. Start `PowerShell`
 2. `Install-Module PSCompletions -Scope CurrentUser`
+   > - Don't omit `-Scope CurrentUser` unless you're sure you'll always open `PowerShell` with administrator permissions.
 3. `Import-Module PSCompletions`
+   - If you don't want to import the `PSCompletions` module every time you start `PowerShell`, you can write it to `$PROFILE`.
    - `echo "Import-Module PSCompletions" >> $PROFILE`
-   - So you don't have to import the module every time you open PowerShell.
 
 ## How to uninstall
 
@@ -62,8 +67,8 @@
 - If it doesn't include the completion you want, you can [submit an issue](https://github.com/abgox/PSCompletions/issues "Click to submit an issue").
 
 1. `psc add git`
-2. Then you can enter `git` and press `Space` `Tab` to get command completion.
-3. For more commands on `psc`, you can learn by entering `psc` and then pressing `Space` `Tab`.
+2. Then you can enter `git`, press `Space` and `Tab` key to get command completion.
+3. For more usages on `psc`, you just need to enter `psc`, press `Space` and `Tab` key, and you will get all usages of `psc` by reading [the completion tip](#about-completion-tip).
 
 ## Demo
 
@@ -73,18 +78,24 @@
 
 ### About the completion trigger key
 
-- The module uses the `Tab` key by default.
+- `PSCompletions` uses the `Tab` key by default.
 - You can set it by running `Set-PSReadLineKeyHandler <key> MenuComplete`.
 
 ### About completion update
 
-- When the module is imported after opening `PowerShell`, `PSCompletions` will start a background job to check for the completion status of the remote repository.
+- When `PSCompletions` module is imported after starting `PowerShell`, it will start a background job to check for the completion status of the remote repository.
 - After getting the update, `PSCompletions` will show the latest status of the completions in the next time.
 
 ### About completion menu
 
+- In addition to the language's built-in completion menu, `PSCompletions` module also provides a useful completion menu.
+
 - The module's completion menu provided by the module is based on [PS-GuiCompletion](https://github.com/nightroman/PS-GuiCompletion) realization idea, thanks!
-- It can only be used in PowerShell(pwsh) under Windows.
+
+- 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" />
+    - Due to rendering problems of `Windows PowerShell`, the border style of the completion menu cannot be customized.
 - Some keys in the completion menu provided by the module.
 
   1. Apply the selected completion item: `Enter`
@@ -102,24 +113,60 @@
      |      `Ctrl + u`      |    `Ctrl + d`    |
      |      `Ctrl + p`      |    `Ctrl + n`    |
 
-- All configurations of it, you can trigger completion by running `psc menu`, then learn about them by completion tip.
+- 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 special symbols
 
+- Special symbols after the completion item are used to let you know in advance if completions are available before you press the `Tab` key.
+
+  - If you don't need or want to see these symbols, you can hide them by replacing them with the empty string.
+    - `psc menu symbol SpaceTab ""`
+    - `psc menu symbol OptionTab ""`
+    - `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)
     - 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 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 "" or '' to wrap it. e.g. 'test content'
+    - 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 can be customized by running `psc menu symbol WriteSpaceTab <symbol>`
-  - Completion of generic options can also be triggered if there is one or more generic option completion.
-  - All complements can be triggered by pressing the `Tab` key after entering a part.
-  - If you don't need or want to see these symbols, you can hide them by replacing them with the empty string.
-    - e.g. `psc menu symbol SpaceTab ""`
+  - All completions can be triggered by pressing the `Tab` key after entering a part.
+    - In `Windows PowerShell`, if you press the `Tab` key after entering `-` or `--`, you won't get the completions.
+    - You should press the `Tab` key to trigger the completion menu, and then type `-` or `--` to filter.
+    - This problem isn't in `PowerShell`.
+
+### About completion tip
+
+- The completion tip is only a helper, you can also disable the tip by running `psc menu config menu_show_tip 0`
+
+  - To enable the completion tip, run `psc menu config menu_show_tip 1`.
+  - You can also disable the tip for a specific completion, such as `psc`.
+    - `psc completion psc menu_show_tip 0`
+
+- General structure of the completion tip: `Usage` + `Description` + `Example`
+
+  ```txt
+  U: install|add [-g|-u] [options] <app>
+  This is a description of the command.
+  E: install xxx
+     add -g xxx
+  ```
+
+- Example Analysis:
+  1. Usage: Begin with `U:`
+     - command name: `install`
+     - command alias: `add`
+     - required parameters: `<app>`
+       - `app` is a simple summary of the parameters.
+     - optional parameters: `-g` `-u`
+       - `[options]`: Some options.
+  2. Description: The description of the command.
+  3. Example: Begin with `E:`
 
 ### About language
 
@@ -144,11 +191,12 @@
 
 - Take `git` for example, when entering `git add`, pressing the `Space` and `Tab` keys, path completion will not be triggered, only completion provided by the module will be triggered.
 - If you want to trigger path completion, you need to enter a content.
-- If the content matches this regex rule `^\.*[\\/].*`, it will get the path completion, which is PowerShell completion.
+- If the content matches this regex rule `^\.*[\\/]*`, it will trigger `PowerShell` path completion.
 - e.g.
   - Please enter `./` or `.\` and press `Tab` key to get path completion for the **subdirectory** or **file**.
   - Please enter `../` or `..\` and press `Tab` key to get path completion for the **parent directory** or **file**.
   - Please enter `/` or `\` and press `Tab` key to get path completion for the **sibling directory**.
+  - More examples: `.` / `~/` / `../../` ...
 - So you can enter `git add ./` and then press `Tab` key to get the path completion.
 
 ## Available Completions List