From f55536f57a189cb7471f65bba80363ba42312215 Mon Sep 17 00:00:00 2001 From: abgox Date: Tue, 20 Aug 2024 20:57:03 +0800 Subject: [PATCH] docs(README): update --- README-CN.md | 68 ++++++++++++++++++++++++----------------- README.md | 85 ++++++++++++++++++++++++++++++---------------------- 2 files changed, 90 insertions(+), 63 deletions(-) diff --git a/README-CN.md b/README-CN.md index 0d47530..83d6df5 100644 --- 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` v4.0.0+ support - - `Windows PowerShell` v4.1.0+ support + - `PowerShell` v4.0.0+ support + - `Windows PowerShell` 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` 的所有配置) -#### 关于菜单增强 - -- v4.2.0+ support +#### 关于菜单增强 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) - - v4.1.0 support 及之前版本都使用此实现 - - v4.2.0+ support: 此实现变为可选 - - 你可以通过设置 `menu_enhance` 为 `0` 来继续使用它 + - v4.1.0 support 及之前版本都使用此实现 + - v4.2.0+ support: 此实现变为可选 + - 你可以运行 `psc menu config menu_enhance 0` 来继续使用它 - 但并不推荐，它只能用于 `psc add` 添加的补全 - 2. `Set-PSReadLineKeyHandler` - - v4.2.0+ support: 默认使用此实现 + 2. [`Set-PSReadLineKeyHandler`](https://learn.microsoft.com/powershell/module/psreadline/set-psreadlinekeyhandler) + - 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 ` 自定义此符号 - - 🤔 : 表示选用当前选中的选项类补全后, 你可以按下 `Space`(空格键) 和 `Tab` 键继续获取剩余选项类补全(如 --verbose) - - 通用选项类补全共用此符号，它可以在任何位置触发，不会影响它们 + - 🤔 : 表示选用当前选中的补全(`Optional Completion`)后, 你可以按下 `Space`(空格键) 和 `Tab` 键继续获取其他的 `Optional Completion` + - `General Optional Completion` 也使用此符号 - 可通过 `psc menu symbol OptionTab ` 自定义此符号 - - 😎 : 表示选用当前选中的选项类补全后, 你可以按下 `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 ` 自定义此符号 - 所有补全都可以在输入部分字符后按下 `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 index 1211fb7..ebb67ea 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ - [`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`. --- @@ -44,13 +44,14 @@ > 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` v4.0.0+ support - - `Windows PowerShell` v4.1.0+ support + - `PowerShell` v4.0.0+ support + - `Windows PowerShell` 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 - -- v4.2.0+ support - -- config: `psc menu config menu_enhance 1` (Default: `1`) -- Now, `PSCompletions` has two completion implementations - - 1. `Register-ArgumentCompleter` - - - v4.1.0 support : It's used. - - v4.2.0+ support: It's optional. +#### About menu enhance 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` - - 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) + - v4.1.0 support : It's used. + - 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) + - 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 ` - - 🤔 : 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 ` - - 😎 : 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 ` - 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.