diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..600d2d33badf45cc068e01d2e3c837e11c417bc4 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode \ No newline at end of file diff --git a/README.md b/README.md index 3c535cffbb2597b7fc72c7009f04e27278f634c5..088331252588f88eeea5e3646b8a672d69ed71fb 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# clitheme Wiki文档 +# clitheme Wiki文档（`v2.0-dev`） + +[**项目简介和样例展示**](./简介.md) clitheme项目的Wiki文档可以在这里查看：https://gitee.com/swiftycode/clitheme/wikis/pages @@ -8,7 +10,7 @@ GitHub镜像仓库：https://github.com/swiftycode256/clitheme-wiki-repo 这些仓库包含最新的更改以及开发中的内容。如需提交Issues和Pull Requests，请通过上方的任意一个仓库提交。 -# clitheme Wiki pages +# clitheme Wiki pages (`v2.0-dev`) The Wiki pages for the clitheme project can be viewed here: https://gitee.com/swiftycode/clitheme/wikis/pages diff --git "a/\344\275\277\347\224\250\345\221\275\344\273\244\350\241\214\347\225\214\351\235\242/\345\221\275\344\273\244\350\241\214\347\225\214\351\235\242\345\237\272\346\234\254\347\224\250\346\263\225.md" "b/\344\275\277\347\224\250clitheme\345\221\275\344\273\244\350\241\214\345\267\245\345\205\267.md" similarity index 70% rename from "\344\275\277\347\224\250\345\221\275\344\273\244\350\241\214\347\225\214\351\235\242/\345\221\275\344\273\244\350\241\214\347\225\214\351\235\242\345\237\272\346\234\254\347\224\250\346\263\225.md" rename to "\344\275\277\347\224\250clitheme\345\221\275\344\273\244\350\241\214\345\267\245\345\205\267.md" index 93406e3f040a248f397a4bbea3c94c1f48ee1e43..60191e731c89855335e6dc9913b0bd0c1cabfbb9 100644 --- "a/\344\275\277\347\224\250\345\221\275\344\273\244\350\241\214\347\225\214\351\235\242/\345\221\275\344\273\244\350\241\214\347\225\214\351\235\242\345\237\272\346\234\254\347\224\250\346\263\225.md" +++ "b/\344\275\277\347\224\250clitheme\345\221\275\344\273\244\350\241\214\345\267\245\345\205\267.md" @@ -1,59 +1,64 @@ -# 使用命令行界面 +# 使用`clitheme`命令行工具 `clitheme`的命令行界面包含了大部分面向用户的功能，比如设置和修改主题、获取当前主题信息等。 ## 程序位置和名称 -如果你是通过软件包安装的，一般情况下直接在命令行上执行`clitheme`就可以了。 +如果你是通过软件包安装的，一般情况下直接在命令行上执行`clitheme`就可以了。你也可以执行`python3 -m clitheme`，如果`clitheme`不可用。 -``` +```plaintext $ clitheme -Usage: /usr/bin/clitheme apply-theme [themedef-file] [--overlay] [--preserve-temp] - /usr/bin/clitheme get-current-theme-info - /usr/bin/clitheme unset-current-theme - /usr/bin/clitheme generate-data [themedef-file] [--overlay] - /usr/bin/clitheme --help - /usr/bin/clitheme --version -Error: no command or option specified +Usage: + clitheme apply-theme [themedef-file] [--overlay] [--preserve-temp] + clitheme get-current-theme-info + clitheme unset-current-theme + clitheme update-theme + clitheme generate-data [themedef-file] [--overlay] + clitheme --version + clitheme --help ``` -如果你使用的是最新的开发版本，则需要直接执行仓库中的`cli.py`文件。 +如果你使用的是最新的开发版本，则需要直接调用仓库中的模块文件。 - $ src/clitheme/cli.py - <...> +```plaintext +# 在仓库根目录执行： +$ python3 -m src.clitheme +<...> +``` ## `apply-theme` - 应用主题 如需应用主题定义文件，请使用`apply-theme`指令，并且提供文件名称。比如： -``` +```plaintext $ clitheme apply-theme example-theme.clithemedef.txt ==> Generating data... Successfully generated data ==> Applying theme... Theme applied successfully ``` -执行这个指令后，支持的应用程序会使用文件中定义的字符串。 + +**提示：** 你可以同时指定多个文件名称，以同时应用这些文件的定义。指定的文件会以从左到右的顺序应用，比如`clitheme apply-theme file1 file2`会先应用`file1`然后再应用`file2`，相当于先应用`file1`然后把`file2`中的定义叠加到当前数据上。 ### 主题数据叠加 默认情况下，这个指令会覆盖之前的主题数据。你可以通过`--overlay`选项以叠加定义和数据。新的字符串会被添加到当前的数据中，并且已存在的字符串会被覆盖。 - $ clitheme apply-theme --overlay example-theme.clithemedef.txt +```plaintext +$ clitheme apply-theme --overlay example-theme.clithemedef.txt +``` **注意：** 使用此选项时需要确保之前已经设定过主题。 **提示：** 你可以通过此方法叠加多个语言但字符串路径名称相同的的主题定义文件，因为该功能只会覆盖字符串对应的语言。 -**提示：** 你可以同时指定多个文件名称，以同时应用这些文件的定义。指定的文件会以从左到右的顺序应用，比如`clitheme apply-theme file1 file2`会先应用`file1`然后再应用`file2`，相当于先应用`file1`然后把`file2`中的定义叠加到当前数据上。 - ### 保留临时数据结构目录 `apply-theme`指令完成后默认会删除存储数据结构的临时目录。如果你想要保留这个临时目录，你可以指定`--preserve-temp`以保留临时目录。 在该模式下，该指令会输出临时目录的路径。你可以通过此路径查看被保留的临时目录。 -``` +```plaintext $ clitheme apply-theme --preserve-temp example-theme.clithemedef.txt ==> Generating data... Successfully generated data @@ -66,16 +71,30 @@ Theme applied successfully 如需取消应用或删除当前的主题数据，请使用`unset-current-theme`指令。删除数据后，支持的应用程序会停止使用自定义的字符串。 -``` +```plaintext $ clitheme unset-current-theme Successfully removed the current theme data ``` +## `update-theme` - 重新应用之前的主题定义文件 + +`update-theme`指令会重新应用在之前`apply-theme`操作中指定的主题定义文件，方便修改这些文件时重新应用更改（无需重新指定文件路径）。如果在之前的`apply-theme`操作中使用了`--overlay`选项，则会使用之前所有有关的`apply-theme`操作中指定的文件（当前主题定义中用到的）。 + +使用这个指令时，请确保之前使用的主题定义文件没有被删除或移动，否则操作会失败。 + +```plaintext +$ clitheme update-theme +==> Generating data... +Successfully generated data +==> Applying theme... +Theme applied successfully +``` + ## `get-current-theme-info` - 获取当前主题信息 如需获取当前的主题信息，请使用`get-current-theme-info`指令。该指令会输出主题的详细信息，包括名称，版本，支持的语言和应用程序等。 -``` +```plaintext $ clitheme get-current-theme-info Currently installed theme: [1]: Example theme @@ -91,7 +110,7 @@ Supported apps: 如果通过数据叠加选项同时应用了多个主题，该指令会显示叠加历史记录，从最新应用的主题往下排序。 -``` +```plaintext $ clitheme get-current-theme-info Overlay history (sorted by latest installed): [2]: 颜文字样例主题 @@ -114,13 +133,13 @@ Supported apps: ## `generate-data` - 生成数据结构 -使用`generate-data`指令会在临时目录中生成数据结构。该指令的功能和`apply-theme`指令相似，只是不会应用主题而已。该指令用于调试和开发用途。 +使用`generate-data`指令会在临时目录中生成数据结构。该指令的功能和`apply-theme`指令相似，只是不会应用主题而已。**该指令仅用于调试和开发用途。** 指定`--overlay`选项以生成把主题文件叠加在当前数据上的数据结构，用法和`apply-theme`相同。 你也可以同时指定多个文件，原理和`apply-theme`一样。 -``` +```plaintext $ clitheme generate-data example-theme.clithemedef.txt ==> Generating data... Successfully generated data @@ -131,9 +150,9 @@ View at /tmp/clitheme-temp-XXXXXXXX `--version`指令会输出版本信息，比如： -``` +```plaintext $ clitheme --version -clitheme version 1.1-r1 +clitheme version 2.0 ``` -详细请见[**关于版本的重要信息**](../关于版本的重要信息.md)。 +详细请见[**关于版本的重要信息**](关于版本的重要信息.md)。 diff --git "a/\345\205\263\344\272\216\347\211\210\346\234\254\347\232\204\351\207\215\350\246\201\344\277\241\346\201\257.md" "b/\345\205\263\344\272\216\347\211\210\346\234\254\347\232\204\351\207\215\350\246\201\344\277\241\346\201\257.md" index 7d1cd7a40aae45a7f6eee10be3c254d0ddb69279..ab81f8f4d8b8758bb800ac3cf1868d9c70cdfa25 100644 --- "a/\345\205\263\344\272\216\347\211\210\346\234\254\347\232\204\351\207\215\350\246\201\344\277\241\346\201\257.md" +++ "b/\345\205\263\344\272\216\347\211\210\346\234\254\347\232\204\351\207\215\350\246\201\344\277\241\346\201\257.md" @@ -3,18 +3,18 @@ ## 命名方式 `clitheme`采用了以下的版本命名方式： -`a.b-rX`或`a.b-devYYYYMMDD` +`a.b.X`或`a.b[.X]-devYYYYMMDD` -- `a.b`代表了主要版本号。当有新的功能加入`clitheme`时，该版本号的`b`值会变更。目前版本号的`a`值不会变更，会保持为`1`。比如说：`1.0`，`1.1` -- `rX`代表了该版本的发行版次。当小改进和问题修复被加入时，该版本号的`X`值会变更。比如说：`r1`，`r2` +- `a.b`代表了主要版本号。当有新的功能加入`clitheme`时，该版本号的`b`值会变更。比如说：`1.0`、`1.1`、`2.0` +- `.X`代表了该版本的发行版次。当小改进和问题修复被加入时，该版本号的`X`值会变更。比如说：`1.0.1`，`2.0.1` - `dev`代表了正在开发的下一个版本。当新的改动被同步到仓库时，我会把当天的日期添加在版本号的后面。比如说：`dev20231202` 这个版本信息会被储存在仓库中的`src/clitheme/_version.py`中，并且会在新的发行版中包括此版本号。 -**注意：** 因为pip软件包的版本命名限制，pip软件包的版本格式为`a.b.postX`。因为Arch Linux软件包的版本命名限制，版本号中的`-`会被`_`替代（如`a.b_rX`）。 +**注意：** 因为Arch Linux软件包的版本命名限制，版本号中的`-`会被`_`替代（如`a.b_devYYYYMMDD`）。 ## 代码仓库分支 -当`clitheme`的下一个版本处于开发状态时，我会新建一个分支用于同步下一个版本的开发进度。这样子，当前稳定版本的内容不会收到影响。这个分支的命名格式通常为`a.b_dev`或`a.b-rX_dev`。 +当`clitheme`的下一个版本处于开发状态时，我会新建一个分支用于同步下一个版本的开发进度。这样子，当前稳定版本的内容不会收到影响。这个分支的命名格式通常为`a.b_dev`或`a.b.X_dev`。 当下一个主要版本开发完成后，我会把这个分支融合到`latest-STABLE`分支上，并且创建一个新的发行版。`latest-STABLE`是这个仓库的主要分支，包含最新稳定版本的代码内容。 diff --git "a/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/1. \347\274\226\345\206\231\345\256\232\344\271\211\346\226\207\344\273\266.md" "b/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/1. \347\274\226\345\206\231\345\256\232\344\271\211\346\226\207\344\273\266.md" new file mode 100644 index 0000000000000000000000000000000000000000..caa5a3c31b9ca70957527326d301724e2e14e957 --- /dev/null +++ "b/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/1. \347\274\226\345\206\231\345\256\232\344\271\211\346\226\207\344\273\266.md" @@ -0,0 +1,226 @@ +# 编写定义文件（命令行输出替换） + +`clitheme`允许你通过替换规则和定义来自定义任何命令行应用程序的输出。本文章将介绍如何编写**主题定义文件**和这些替换规则。 + +## 编写`header`段落 + +你需要先定义该主题/文件的一些基本信息，包括名称、简介等。请见[header段落](../附录：主题定义文件通用语法/header段落.md) + +## `substrules`段落 + +在主题定义文件中，所有的输出替换规则和定义都是定义在文件中`substrules`段落的。请使用以下语法定义`substrules`段落。 + +```plaintext +{substrules_section} + <在这里定义规则> +{/substrules_section} +``` + +## 定义替换规则 + +替换规则分为两种：**字符串替换**和**正则表达式**替换。前者会匹配完全相同的输出文本和字符，后者会根据正则表达式中的规则匹配输出文本。 + +**请注意：**目前仅支持匹配单行的输出，不支持匹配多行输出（这意味着**不要在匹配正则表达式中使用`\n`等换行符号**）。不需要匹配一行中的所有内容；你可以仅匹配和替换一行中的部分内容。 + +### 字符串和正则表达式替换：`substitute_string`和`substitute_regex` + +定义字符串规则的语法如下： + +```plaintext +{substrules_section} + # 把"{{ESC}}"替换为ANSI Escape字符： + set_options substesc + [substitute_string] <匹配文本内容> + [locale] + <替换文本内容> + [/locale] + # 或者： + locale: <替换文本内容> + [/substitute_string] + + [substitute_regex] <匹配正则表达式> + [locale] + <替换内容（正则表达式替换语法）> + [/locale] + # 或者： + locale: <替换文本内容> + [/substitute_regex] +{/substrules_section} +``` + +- 在`[substitute_string]`之后输入要匹配/查找的文本内容；在`[substitute_regex]`之后输入要匹配的正则表达式。 + - `clitheme`用的是Python内置的的正则表达式引擎，所以你必须使用Python的正则表达式语法。有关更多信息，请见[本文章](https://docs.python.org/zh-cn/3/howto/regex.html)。 +- 使用以`[locale]`开头的内容段落输入要替换的内容 + - 在`[locale]`之后可以定义系统语言（locale）：当前的系统语言设定符合这个定义时才会执行替换；如不需要限制系统语言，请使用`default`。 + - 你可以同时指定多个系统语言；只需要用空格分开就可以了（如`[locale] en_US zh_CN`） + - 带有语言设定的定义会比带有`default`设定的定义有更高的优先级。`default`更像是一个fallback选项：如果没有任何匹配到的带有语言设定的内容定义时才会使用带有`default`的定义。 + - 更多信息请见[多语言支持](../附录：主题定义文件通用语法/多语言支持.md) + - 替换内容可以是多行的；详见[多行内容段落](../附录：主题定义文件通用语法/多行内容段落.md) +- 如果替换的内容只有一行，你可以使用`locale:<系统语言>`并且在后面加上替换的内容。这样子写起来会更便捷 + - 注意：不能同时指定多个系统语言，并且不支持在此语法中使用变量替换（`substvar`；详见[可以设定的选项](../附录：主题定义文件通用语法/可以设定的选项.md)），如`locale:{{some_var}}`将不会把`{{some_var}}`替换成对应变量的内容 +- 如果匹配的内容之间有任何终端控制字符，匹配内容中必须包括它。你可以使用`clitheme-exec --debug-showchars`在终端输出中以绿色颜色显示这些字符（详见[使用clitheme-exec](2.%20使用clitheme-exec.md)）。如需引用ANSI Escape字符（`{{ESC}}`），请在前面添加`set_options substesc`（详见[可以设定的选项](../附录：主题定义文件通用语法/可以设定的选项.md)）并且在内容中使用`{{ESC}}`。**如需引用其他字符（如`\x08`、`\x07`等），你必须使用正则表达式替换（`[substitute_regex]`）。** +- 以`#`开头的行是注释；它们必须定义在新的一行上 + +### 可以设定的选项 + +你可以为匹配规则设定一些选项。如需设定，请在`[/substitute_string]`或`[/substitute_regex]`之后添加选项设定，或使用`set_options`为之后定义的匹配规则应用这些选项设定。 + +- `endmatchhere`，`noendmatchhere`：当遇到带有该选项的匹配规则时，不再继续按顺序应用其他的匹配规则 + - 使用`noendmatchhere`以取消设定 +- `subststdoutonly`：仅匹配standard output的输出内容 +- `subststderronly`：仅匹配standard error的输出内容 +- `substall`：默认设定；用于重置之前设定；匹配所有内容 + +更多信息以及可以设定的选项请见[可以设定的选项](../附录：主题定义文件通用语法/可以设定的选项.md)。 + +### 同时指定多个匹配表达式 + +在替换内容基本相同的情况下，你可以为一个规则定义同时指定多个匹配表达式。该功能可以免去对替换内容和定义段落的重复复制粘贴，并且修改替换内容会简单很多。如需使用，请同时指定多个`[substitute_string]`或`[substitute_regex]`语句。 + +**注意：** 不能同时指定`[substitute_string]`或`[substitute_regex]`语句（两者不能在同一个规则定义中混用） + +样例： + +```plaintext +{substrules_section} + [substitute_string] Some text 1 + [substitute_string] Some another text + [substitute_string] Some text 2 + locale:default Some substitution text + [/substitute_string] + # 上方定义等于以下定义： + [substitute_string] Some text 1 + locale:default Some substitution text + [/substitute_string] + [substitute_string] Some text 2 + locale:default Some substitution text + [/substitute_string] + [substitute_string] Some another text + locale:default Some substitution text + [/substitute_string] + + # 错误语法（两者不能混用）： + [substitute_string] Some text 1 + [substitute_regex] Some regex 1 + locale:default Some substitution text + [/substitute_string] +{/substrules_section} +``` + +### 样例 + +```plaintext +{substrules_section} + # substesc和endmatchhere选项会对以下所有的匹配规则生效 + set_options endmatchhere substesc + [substitute_string] Some text + [locale] default + Some other text here + Good stuff {{ESC}} + [/locale] + [/substitute_string] subststderronly + [substitute_string] Some other text + [locale] default + Another good stuff + [/locale] + [/substitute_string] noendmatchhere subststdoutonly + # 上方定义的noendmatchhere会覆盖之前在set_options中定义的endmatchhere + [substitute_regex] Error at file number (?P\d+): item (?P.+) not found + # 如果系统语言为zh_CN，会使用以下定义： + locale:zh_CN (ToT)/~~~ 在文件\g发生错误：找不到项目"\g"！(>﹏<) + # 否则，会使用以下定义： + locale:default (ToT)/~~~ Error at file number \g! Could not find item "\g"! + [/substitute_regex] +{/substrules_section} +``` + +## 限制匹配规则适用的命令 + +为了防止一个匹配规则在另一个无关的命令样应用程序被应用，你可以为匹配规则限制适用的命令。如需添加命令限制，请在匹配规则前面添加`[filter_commands]`段落。 + +```plaintext +{substrules_section} + [filter_commands] + <命令或由多行分开的多个命令> + [/filter_commands] + # 你也可以使用以下语法： + filter_command <命令> + # 该限制会对以下的规则生效 + [substitute_regex] + <...> + [/substitute_regex] + # 使用以下语句对之后的规则取消设定限制 + unset_filter_command + # 以下的规则不会受到限制 + [substitute_regex] + <...> + [/substitute_regex] +{/substrules_section} +``` + +- 在`[filter_commands]`中输入命令以设定限制。定义后，之后定义的匹配规则仅会对这些命令生效。 + - 你可以同时指定多个命令；只需要通过换行分开就可以了 + - 你可以指定带有选项的命令（如`rm -r -f`和`example-app do-something -e`） +- 你也可以使用`filter_command <命令>`来指定单个命令；这样输入起来会更便捷 +- 使用`unset_filter_command`来取消设定限制。设定后，之后定义的匹配规则不会拥有命令限制。 + +### 命令匹配机制&选项 + +默认情况下，只要用户输入的命令的第一个语句与限制条件命令的相同，并且用户输入命令包含限制条件命令中所有语句，相应的匹配条件会生效。**这里的语句指的是用空格分开的词语。** + +比如说，用户输入的`rm something -rf`指令会匹配限制条件中的`rm -rf`规则，但不会匹配到`something -rf rm`（因为第一个语句不同）和`rm -f`（因为原命令中不包括`-f`）。 + +你可以选择其他的匹配机制；只需要在`[/filter_commands]`的后面加上它们就可以了（两者之间加个空格）。你也可以使用`set_options`（详见[可以设定的选项](../附录：主题定义文件通用语法/可以设定的选项.md)）加上它们，以把它应用到之后所有的命令限制规则定义。请注意，`filter_command <命令>`语法只能通过`set_options`设定这些选项。 + +- `strictcmdmatch`：用户输入的命令必须开始于限制条件命令，按语句计算。比如说，用户输入的`example-app something -e`会匹配到限制规则中的`example-app something`，但不会匹配到`example-app -e`（因为`example-app something -e`不以`example-app -e`开始）。 +- `exactcmdmatch`：用户输入的命令必须与限制条件命令完全相同 +- `smartcmdmatch`：和默认匹配机制相似，但是所有命令中单个横杠（`-`）开头的语句会被拆分成单个选项，如`ls -lih`将会被视为`ls -l -i -h`。带有多个横杠（`--`）的语句不受影响。 +- `normalcmdmatch`：默认匹配机制；**用于重置/取消设定之前的设置** +- `foregroundonly`：仅在进程为前台运行时应用这些替换规则。该选项适用于使用`clitheme-exec`执行shell等应用程序：通过大多数shell执行其他命令时，该shell会切换为后台运行（并且将执行的命令切换为前台）。这个选项可以防止输出误替换的问题，并且可以确保仅在shell的提示信息上应用有关的的替换规则。 + - 使用`noforegroundonly`以取消设定该选项 + - 你可以使用`clitheme-exec --debug-foreground`以在前台状态切换时获得提示信息 + - **注意：** 经测试，只有shell等应用程序会在执行其他命令时修改自己的前台状态；`sudo`等程序不会（除非通过`sudo`执行shell，如`sudo bash`）。 + - **注意：** 大多数shell程序（`bash`、`zsh`、`csh`、`fish`）的命令执行错误提示（如`command not found`、`permission denied`等）会通过创建的另一个进程输出，并且shell会在后台运行。这会导致带有该选项的命令限制规则和对应的替换规则在这些提示输出上不会被应用： + +```plaintext +$ clitheme-exec --debug-foreground bash +bash-3.2$ wef +! Foreground: False +bash: wef: command not found +! Foreground: True +bash-3.2$ +``` + +**注意：** 无论选择了哪个匹配选项，如果用户输入的命令中第一个词语包含路径（指定可执行文件），`clitheme`会永远检查并尝试匹配程序名称。比如说，如果用户输入了`/usr/bin/python3 test.py`，`python3 test.py`也会被尝试匹配。 + +#### 样例： + +```plaintext +[filter_commands] + example-app some-opt + another-app some-arg +[/filter_commands] strictcmdmatch +``` + +```plaintext +set_options strictcmdmatch +filter_command example-app some-opt +# 重置之前设定： +set_options normalcmdmatch +``` + +## 应用主题（`clitheme apply-theme`） + +主题定义文件写好后，你需要应用这个文件到系统中。请在终端执行`clitheme apply-theme <文件名>`以应用主题。应用好主题后，请使用`clitheme-exec`来使用这些匹配规则。详见[使用clitheme-exec](2.%20使用clitheme-exec.md)。 + +## 注意事项 + +- 主题定义文件中的匹配规则会通过以下顺序依次执行；**每一部分根据文件中的*定义顺序*执行**： + 1. 带有命令限制条件并且带有`exactcmdmatch`匹配机制设定的匹配规则 + 2. 带有命令限制条件的匹配规则 + - 命令语句最多的将会被优先执行（从多到少） + 3. 没有命令限制条件的匹配规则 + - **这意味着你可以通过多个替换规则来更改/替换一行的输出** +- 如果执行替换规则的时间超过**0.4秒**，则会视为超时，并且会输出未处理过的内容 +- 不需要匹配一行中的所有内容；你可以仅匹配和替换一行中的部分内容 +- 如果匹配规则的匹配文本/表达式、命令限制条件、和stdout/stderr限制设定于之前的规则相同，将被视为重复规则，并且新的定义会覆盖旧的 \ No newline at end of file diff --git "a/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/2. \344\275\277\347\224\250clitheme-exec.md" "b/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/2. \344\275\277\347\224\250clitheme-exec.md" new file mode 100644 index 0000000000000000000000000000000000000000..97becc9bf65f3bf7ccbb518c90b02d2d95bc08b9 --- /dev/null +++ "b/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/2. \344\275\277\347\224\250clitheme-exec.md" @@ -0,0 +1,76 @@ +# 使用`clitheme-exec`命令行工具 + +使用`clitheme-exec`执行命令行指令以应用主题定义文件中的输出匹配规则。你可以使用输出调试选项来获得所需的输出信息，更好的编写匹配规则。 + +你可以使用`clitheme-exec`或`python3 -m clitheme.exec`： + +```plaintext +$ clitheme-exec +使用方式： + clitheme-exec [--debug] [--debug-color] [--debug-newlines] [--debug-showchars] [command] +错误：未指定命令 +使用"clitheme-exec --help"以获取使用方式 +$ python3 -m clitheme.exec +<...> +``` + +注意：如需在代码仓库文件夹中调用`clitheme-exec`，请调用仓库中的模块文件： + +```plaintext +# 在仓库根目录中执行： +$ python3 -m src.clitheme.exec +<...> +``` + +## 执行命令 + +只需要在你想执行的命令的前面添加`clitheme-exec`就可以了，比如`clitheme-exec ls`或`clitheme-exec gcc test.c`。 + +```plaintext +$ clitheme-exec ls +<...> +$ clitheme-exec gcc test.c +<...> +``` + +### 使用sudo执行命令 + +如需使用`sudo`执行命令，请使用`sudo clitheme-exec`加上你想执行的命令，不要使用`clitheme-exec sudo`。 + +```plaintext +$ sudo clitheme-exec some-command +<...> +``` + +如果你已经应用了主题，但是依然受到“没有设定主题”的提示，那是因为使用`sudo`时没有保留你的用户文件夹信息。你可以在`/etc/sudoers`文件中添加`Defaults env_keep += "HOME"`，或找到这一行并删除注释符号，以修复这个问题。 + +## 可以设定的选项 + +`clitheme-exec`目前支持以下输出调试选项： + +- `--debug`：在每一行输出的前面加上标记。这个标记会包含输出是否为stdout或stderr、匹配规则有没有更改输出等信息。 + - 标记符号为`o`时，表示该输出为standard output（`stdout`） + - 标记符号为`e`时，表示该输出为standard error（`stderr`） + - 标记背景颜色为白色时，则表示该行输出执行替换规则后被改变 + - 标记背景颜色为红色时，则表示执行替换规则时超时，并且输出没有被替换 +- `--debug-color`：对每一行添加颜色标记：如果该行输出为stdout，则标记黄色；如果该行输出为stderr，则标记红色。 +- `--debug-showchars`：用明文显示以下终端控制字符： + - ASCII Escape（`{{ESC}}`） + - Carriage换行（`\r`） + - 换行符号（`\n`） + - ASCII Backspace符号（`\x08`） + - ASCII Bell符号（`\x07`） +- `--debug-newlines`：永远用新的一行显示所有输出（用于末尾没有换行的输出内容） +- `--debug-foreground`：当进程的前台状态（通过`tcgetpgrp`获取）变动时，显示提示输出。 + - `! Foreground: False ()`：进程退出前台状态 + - `! Foreground: True ()`：进程进入/重新进入前台状态 + - ``为当前前台进程的PID +- `--debug-nosubst`：不进行任何输出替换，即使已设定主题 + +如需设定这些选项，请在**指定命令之前**指定这些选项，比如说： + +```plaintext +$ clitheme-exec --debug --debug-showchars gcc something.c +# 不要这样子写： +$ clitheme-exec gcc something.c --debug --debug-showchars +``` \ No newline at end of file diff --git "a/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/3. \346\240\267\344\276\213\346\225\231\347\250\213.md" "b/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/3. \346\240\267\344\276\213\346\225\231\347\250\213.md" new file mode 100644 index 0000000000000000000000000000000000000000..fe458b8aaf8ba82dcffc22f71723576dd7c72927 --- /dev/null +++ "b/\345\221\275\344\273\244\350\241\214\350\276\223\345\207\272\346\233\277\346\215\242/3. \346\240\267\344\276\213\346\225\231\347\250\213.md" @@ -0,0 +1,127 @@ +# 一个简单的样例展示 + +本文章将展示命令行输出替换的一个样例，包含使用`clitheme-exec --debug-showchars`获取所需的输出和为输出编写替换规则。 + +浏览本文章前，请先阅读[编写定义文件](1.%20编写定义文件.md)和[使用clitheme-exec](2.%20使用clitheme-exec.md)。 + +本文章中的部分内容来自于`kawaii-gcc`项目。项目地址：https://github.com/Bill-Haku/kawaii-gcc + +## 1. 获取应用程序的输出 + +假如说我们想要自定义`clang`编译器中的一个错误提示。如果我们的测试文件时`test.c`，我们可以使用`clitheme-exec --debug-showchars clang test.c`来获取包含终端控制符号的输出。编写匹配规则时需要考虑到这些终端控制符号；这是为什么我们要获取**包含终端控制符号**的输出。你也可以使用`--debug-nosubst`来获取未替换过的输出，如果你已经设定了主题。 + +你可以使用`--debug`选项来在每一行输出前加上标记。这个标记会包含输出为stdout或stderr的信息（通过`o`和`e`表达）。 + +注意：`--debug-showchars`和任何debug选项必须放在`clang test.c`的前面，否则要执行的命令将会被认为`clang test.c --debug-showchars`。 + +```plaintext +$ clitheme-exec --debug --debug-showchars --debug-nosubst clang test.c +e> {{ESC}}[1mtest.c:1:1: {{ESC}}[0m{{ESC}}[0;1;31merror: {{ESC}}[0m{{ESC}}[1munknown type name 'bool'{{ESC}}[0m\r\n +e> bool *haku(int *a) {\r\n +e> {{ESC}}[0;1;32m^\r\n +e> {{ESC}}[0m{{ESC}}[1mtest.c:4:3: {{ESC}}[0m{{ESC}}[0;1;35mwarning: {{ESC}}[0m{{ESC}}[1mincompatible pointer types assigning to 'char *' from 'int *' [-Wincompatible-pointer-types]{{ESC}}[0m\r\n +e> b=a;\r\n +e> {{ESC}}[0;1;32m ^~\r\n +e> {{ESC}}[0m2 errors generated.\r\n +``` + +作为参考，这是`clang test.c`的正常输出： + +```plaintext +$ clang test.c +test.c:1:1: error: unknown type name 'bool' +bool *haku(int *a) { +^ +test.c:4:3: warning: incompatible pointer types assigning to 'char *' from 'int *' [-Wincompatible-pointer-types] + b=a; + ^~ +2 errors generated. +``` + +在这个样例中，我们将自定义`unknown type name`的错误提示`incompatible pointer types`的警告提示。 + +## 2. 编写定义文件和匹配规则 + +知道输出内容后，是时候编写定义文件和匹配规则了。 + +### 为输出编写正则表达式 + +我们可以为这些输出编写正则表达式定义。如需了解正则表达式和Python的正则表达式语法（因为`clitheme`用的是Python内置的正则表达式引擎），你可以参考[Python官方文档中的这篇文章](https://docs.python.org/zh-cn/3/howto/regex.html)。 + +为了防止不小心替换无关的内容输出，我们在这个样例中会从行的开头开始匹配内容（平时写匹配规则时不需要都这样子做），包括前面的文件和行数信息（如`test.c:1:1:`）。但是，我们不需要匹配行中的所有内容，所以我们不需要考虑行的结尾中的无关内容。 + +我们拿这行输出举例（**这篇文档中的`{{ESC}}`会在编写定义文件时被替换成ASCII Escape字符**）： + +```plaintext +{{ESC}}[0m{{ESC}}[1mtest.c:4:3: {{ESC}}[0m{{ESC}}[0;1;35mwarning: {{ESC}}[0m{{ESC}}[1mincompatible pointer types assigning to 'char *' from 'int *' [-Wincompatible-pointer-types]{{ESC}}[0m\r\n +# 原输出内容： +test.c:4:3: warning: incompatible pointer types assigning to 'char *' from 'int *' [-Wincompatible-pointer-types] +``` + +我们可以使用以下正则表达式来匹配从这行开头到"`[-Wincompatible-pointer-types]`"之前的内容： + +```plaintext +(?P^({{ESC}}.*?m)*(.+:\d+:\d+:) ({{ESC}}.*?m)*)warning: (?P({{ESC}}.*?m)*)incompatible pointer types assigning to '(?P.+)' from '(?P.+)' +``` + +这个表达式中包含了对Escape字符的匹配；这是必要的。否则，该表达式不会匹配到输出，从而无法替换内容。 + +这个正则表达式中使用了命名组来区分内容中的每一部分。这是一个推荐的写法，因为引用起来会更加容易和错误率更少。 + +写好匹配表达式后，我们可以继续写要替换成的内容了。这里要注意的是替换的内容也会根据正则表达式的相关语法处理一些特殊字符；你可以参考之前链接的那篇文章的内容。比如说，我们可以把上述提示输出替换成以下内容，实现对应用程序输出的自定义。 + +```plaintext +\g杂鱼～: \g'\g'从不兼容的指针类型赋值为'\g',纯爱战神很生气！ +``` + +这里的`\g<组名>`语法会将上方匹配表达式匹配到的分组内容放到替换内容中（Python正则表达式引擎语法）。这里使用`\g`是为了保留输出的前缀（`test.c:1:1:`），并且这里使用的`\g`和`\g`是为了保留名称类型（比如输出中的`char *`和`int *`）。 + +### 编写匹配规则和定义文件 + +我们现在可以把这些表达式放进一个定义文件和其中的匹配规则定义中了。根据上述讲的内容编写匹配规则和主题定义文件，包括另一行的输出（`unknown type name`那一行）： + +```plaintext +# 在header_section中定义一些关于该主题定义的基本信息；必须包括 +{header_section} + # 这里建议至少包括name和description信息 + name clang样例主题 + [description] + 一个为clang打造的的样例主题，为了演示作用 + [/description] +{/header_section} + +{substrules_section} + # 设定"substesc"选项：内容中的"{{ESC}}"字样会被替换成ASCII Escape终端控制符号 + set_options substesc + # 命令限制条件：以下的替换规则仅会在以下命令中被应用。建议设定这个条件，因为可以尽量防止不应该的输出替换。 + [filter_commands] + clang + clang++ + gcc + g++ + [/filter_commands] + [substitute_regex] (?P^({{ESC}}.*?m)*(.+:\d+:\d+:) ({{ESC}}.*?m)*)warning: (?P({{ESC}}.*?m)*)incompatible pointer types assigning to '(?P.+)' from '(?P.+)' + # 如果你想仅在系统语言设定为中文（zh_CN）时应用这个替换规则，你可以使用"locale:zh_CN" + # 使用"locale:default"时不会添加系统语言限制 + locale:default \g杂鱼～: \g'\g'从不兼容的指针类型赋值为'\g',纯爱战神很生气！ + [/substitute_regex] + [substitute_regex] (?P^({{ESC}}.*?m)*(.+:\d+:\d+:) ({{ESC}}.*?m)*)error: (?P({{ESC}}.*?m)*)unknown type name '(?P.+)' + locale:default \g笨蛋！: \g未知的类型名'\g',是忘了定义了吗喵？ + [/substitute_regex] +{/substrules_section} +``` + +## 3. 应用主题 + +在终端中执行`clitheme apply-theme <文件名>`以应用这些定义，并且运行`clitheme-exec clang test.c`以看到效果。你也可以使用`python3 -m clitheme`来执行`clitheme`、使用`python3 -m clitheme.exec`来执行`clitheme-exec`，如果之前的命令无法使用。 + +```plaintext +$ clitheme-exec clang test.c +test.c:1:1: 笨蛋！: 未知的类型名'bool',是忘了定义了吗喵？ +bool *haku(int *a) { +^ +test.c:4:3: 杂鱼～: 'char *'从不兼容的指针类型赋值为'int *',纯爱战神很生气！ [-Wincompatible-pointer-types] + b=a; + ^~ +2 errors generated. +``` \ No newline at end of file diff --git "a/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\345\221\275\344\273\244\350\241\214\346\214\207\344\273\244.md" "b/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\345\221\275\344\273\244\350\241\214\346\214\207\344\273\244.md" deleted file mode 100644 index 6d0dba19c8b2e37e458fed42a0c7a6bc124f91e3..0000000000000000000000000000000000000000 --- "a/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\345\221\275\344\273\244\350\241\214\346\214\207\344\273\244.md" +++ /dev/null @@ -1,436 +0,0 @@ -# clitheme命令行指令的字符串定义 - -本文章包含了`clitheme`的命令行指令用到的字符串定义，比如`apply-theme`，`get-current-theme-info`等。 - -本文章列出的所有字符串定义将会放在`cli`子路径里，意味着路径名称将会以`swiftycode clitheme cli`开头。 - -## 全局提示 - -### `no-command` - -完整路径名称：`swiftycode clitheme cli no-command` - -默认文本： - -> Error: no command or option specified - -本提示会在没有任何参数的情况下输出。 - -### `not-enough-arguments` - -完整路径名称：`swiftycode clitheme cli not-enough-arguments` - -默认文本： - -> Error: not enough arguments - -本提示会在参数不够的情况下输出（在指定指令的情况下）。 - -### `unknown-option` - -完整路径名称：`swiftycode clitheme cli unknown-option` - -默认文本： - -> Error: unknown option "{option}" - -本提示会在出现未知参数的情况下输出（在指定指令的情况下）。 - -### `unknown-command` - -完整路径名称：`swiftycode clitheme cli unknown-command` - -默认文本： - -> Error: unknown command "{cmd}" - -本提示会在出现未知指令的情况下输出。 - -### `too-many-arguments` - -完整路径名称：`swiftycode clitheme cli too-many-arguments` - -默认文本： - -> Error: too many arguments - -### `help-usage-prompt` - -完整路径名称：`swiftycode clitheme cli help-usage-prompt` - -默认文本： - -> Run {clitheme} --help for usage information - -### `version-str` - -完整路径名称：`swiftycode clitheme cli version-str` - -默认文本： - -> clitheme version {ver} - -本提示会在指定`--version`指令时输出。 - -## `apply-theme`和`generate-data`指令 - -下方列出的字符串定义将会存放在`cli apply-theme`子路径下，意味着路径名称将会以`swiftycode clitheme cli apply-theme`开头。 - -### 样例输出 - `apply-theme` - -``` -$ clitheme apply-theme [...] -The following defintion files will be applied in the following order: -{...} -The existing data will be overwritten if you continue. -Do you want to continue? [y/n] -==> Generating data... - > Processing file 1... - > Processing file 2... - > All finished -Successfully generated data -View at /tmp/clitheme-temp-XXXXXXXX -==> Applying theme... -Theme applied successfully -``` - -对应着以下字符串定义： - -``` -[apply-theme-msg] -{...} -[overwrite-notice] -[confirm-prompt] -[generating-data] -[processing-file] -[processing-file] -[all-finished] -[generate-data-success] -[view-temp-dir] -[applying-theme] -[apply-theme-success] -``` - -### 样例输出 - `generate-data` - -``` -$ clitheme generate-data [...] -The theme data will be generated from the following definition files in the following order: -{...} -==> Generating data... -Successfully generated data -View at /tmp/clitheme-temp-XXXXXXXX -``` - -对应着以下字符串定义： -``` -[generate-data-msg] -{...} -[generating-data] -[generate-data-success] -[view-temp-dir] -``` - -### `generate-data-msg` - -完整路径名称：`swiftycode clitheme cli apply-theme generate-data-msg` - -默认文本： - -> The theme data will be generated from the following definition files in the following order: - -### `apply-theme-msg` - -完整路径名称：`swiftycode clitheme cli apply-theme apply-theme-msg` - -默认文本： - -> The following definition files will be applied in the following order: - -### `overwrite-notice` - -完整路径名称：`swiftycode clitheme cli apply-theme overwrite-notice` - -默认文本： - -> The existing theme data will be overwritten if you continue. - -### `overlay-notice` - -完整路径名称：`swiftycode clitheme cli apply-theme overlay-notice` - -默认文本： - -> The definition files will be appended on top of the existing theme data. - -如果使用`apply-theme`指令时指定了`--overlay`选项，本字符串将会在对应位置输出（详见样例输出），而不是`overwrite-notice`字符串。 - -### `confirm-prompt` - -完整路径名称：`swiftycode clitheme cli apply-theme confirm-prompt` - -默认文本： - -> Do you want to continue? [y/n] - -### `overlay-msg` - -完整路径名称：`swiftycode clitheme cli apply-theme overlay-msg` - -默认文本： - -> Overlay specified - -如果指定了`--overlay`选项，该文本将会在`confirm-prompt`之后被输出。比如： - - {...} - Do you want to continue? [y/n] - Overlay specified - ==> Generating data... - {...} - -### `generating-data` - -完整路径名称：`swiftycode clitheme cli apply-theme generating-data` - -默认文本： - -> ==> Generating data... - -### `processing-file` - -完整路径名称：`swiftycode clitheme cli apply-theme processing-file` - -默认文本： - -> \> Processing file {filename} - -### `all-finished` - -完整路径名称：`swiftycode clitheme cli apply-theme all-finished` - -默认文本： - -> \> All finished - -### `generate-data-success` - -完整路径名称：`swiftycode clitheme cli apply-theme generate-data-success` - -默认文本： - -> Successfully generated data - -### `view-temp-dir` - -完整路径名称：`swiftycode clitheme cli apply-theme view-temp-dir` - -默认文本： - -> View at {path} - -### `applying-theme` - -完整路径名称：`swiftycode clitheme cli apply-theme applying-theme` - -默认文本： - -> ==> Applying theme... - -### `apply-theme-success` - -完整路径名称：`swiftycode clitheme cli apply-theme apply-theme-success` - -默认文本： - -> Theme applied successfully - -### `read-file-error` - -完整路径名称：`swiftycode clitheme cli apply-theme read-file-error` - -默认文本： - -> [File {index}] An error occurred while reading the file: -> -> {message} - -该文本会在文件无法读取时输出。 - -### `overlay-no-data` - -完整路径名称：`swiftycode clitheme cli apply-theme overlay-no-data` - -默认文本： - -> Error: no theme set or the current data is corrupt -> -> Try setting a theme first - -该错误提示仅会在使用`--overlay`选项下输出。 - -### `overlay-data-error` - -完整路径名称：`swiftycode clitheme cli apply-theme overlay-data-error` - -默认文本： - -> Error: the current data is corrupt -> -> Remove the current theme, set the theme, and try again - -### `generate-data-error` - -完整路径名称：`swiftycode clitheme cli apply-theme generate-data-error` - -默认文本： - -> [File {index}] An error occurred while generating the data: -> -> {message} - -### `apply-theme-error` - -完整路径名称：`swiftycode clitheme cli apply-theme apply-theme-error` - -默认文本： - -> An error occurred while applying the theme: -> -> {message} - -## `unset-current-theme` 指令 - -下方列出的字符串定义将会存放在`cli unset-current-theme`子路径下，意味着路径名称将会以`swiftycode clitheme cli unset-current-theme`开头。 - -### `no-data-found` - -完整路径名称：`swiftycode clitheme cli unset-current-theme no-data-found` - -默认文本： - -> Error: No theme data present (no theme was set) - -### `remove-data-error` - -完整路径名称：`swiftycode clitheme cli unset-current-theme remove-data-error` - -默认文本： - -> An error occurred while removing the data: -> -> {message} - -### `remove-data-success` - -完整路径名称：`swiftycode clitheme cli unset-current-theme remove-data-success` - -默认文本： - -> Successfully removed the current theme data - -## `get-current-theme-info` 指令 - -下方列出的字符串定义将会存放在`cli get-current-theme-info`子路径下，意味着路径名称将会以`swiftycode clitheme cli get-current-theme-info`开头。 - -### 样例输出 - -``` -Currently installed theme: -[1]: Example theme -Version: 1.0 -Description: -{...} -Supported locales: -• en_US -• zh_CN -Supported apps: -• App 1 -• App 2 -``` - -对应着以下字符串定义： - -``` -[current-theme-msg] -none -[version-str] -[description-str] -{...} -[locales-str] -[list-item] -[list-item] -[supported-apps-str] -[list-item] -[list-item] -``` - -### `no-theme` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info no-theme` - -默认文本： - -> No theme currently set - -该提示会在没有设定任何主题的情况下输出。 - -### `current-theme-msg` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info current-theme-msg` - -默认文本： - -> Currently installed theme: - -### `overlay-history-msg` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info overlay-history-msg` - -默认文本： - -> Overlay history (sorted by latest installed): - -如果之前通过`apply-theme --overlay`指令同时应用过多个主题，该文本将会替换`current-theme-msg`的文本，在相同位置显示（详见样例输出）。 - -### `version-str` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info version-str` - -默认文本： - -> Version: {ver} - -### `description-str` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info description-str` - -默认文本： - -> Description: - -### `locales-str` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info locales-str` - -默认文本： - -> Supported locales: - -### `supported-apps-str` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info supported-apps-str` - -默认文本： - -> Supported apps: - -### `list-item` - -完整路径名称：`swiftycode clitheme cli get-current-theme-info list-item` - -默认文本： - -> • {content} - -你可以通过此定义控制项目列表的样式，会在`Supported apps: `和`Supported locales:`下展示。（详见输出样例） diff --git "a/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\346\225\260\346\215\256\347\224\237\346\210\220\345\231\250\346\217\220\347\244\272\344\277\241\346\201\257.md" "b/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\346\225\260\346\215\256\347\224\237\346\210\220\345\231\250\346\217\220\347\244\272\344\277\241\346\201\257.md" deleted file mode 100644 index 08f5faa8a39f35bf584b711defa541d474763565..0000000000000000000000000000000000000000 --- "a/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\346\225\260\346\215\256\347\224\237\346\210\220\345\231\250\346\217\220\347\244\272\344\277\241\346\201\257.md" +++ /dev/null @@ -1,181 +0,0 @@ -# clitheme数据生成器提示信息的字符串定义 - -本文章包含了`clitheme`数据生成器用到的字符串定义。该数据生成器用于`apply-theme`指令中的数据生成部分。 - -本文章列出的字符串都会放在`generator`子路径里，意味着所有的路径名称将会以`swiftycode clitheme generator`开头。 - -样例提示信息输出（`apply-theme`指令）： - -``` -{...} -==> Generating data... -[File 1] An error occurred while generating the data: -Syntax error: Unexpected "phrase" on line 4 -``` - -## 语法错误提示 - -### `error-str` - -完整路径名称：`swiftycode clitheme generator error-str` - -默认文本： - -> Syntax error: {msg} - -所有的语法错误信息将会通过这个文本输出（文本中的`{msg}`部分）。详见上方的样例输出。 - -### `subsection-conflict-err` - -完整路径名称：`swiftycode clitheme generator subsection-conflict-err` - -默认文本： - -> Line {num}: cannot create subsection "{name}" because an entry with the same name already exists - - -### `entry-conflict-err` - -完整路径名称：`swiftycode clitheme generator entry-conflict-err` - -默认文本： - -> Line {num}: cannot create entry "{name}" because a subsection with the same name already exists - -### `internal-error-blockinput` - -完整路径名称：`swiftycode clitheme generator internal-error-blockinput` - -默认文本： - -> Line {num}: internal error while handling block input; please file a bug report - -### `extra-arguments-err` - -完整路径名称：`swiftycode clitheme generator extra-arguments-err` - -默认文本： - -> Extra arguments after "{phrase}" on line {num} - -### `repeated-header-err` - -完整路径名称：`swiftycode clitheme generator repeated-header-err` - -默认文本： - -> Repeated header block at line {num} - -### `repeated-main-err` - -完整路径名称：`swiftycode clitheme generator repeated-main-err` - -默认文本： - -> Repeated main block at line {num} - -### `invalid-phrase-err` - -完整路径名称：`swiftycode clitheme generator invalid-phrase-err` - -默认文本： - -> Unexpected "{phrase}" on line {num} - -### `not-enough-args-err` - -完整路径名称：`swiftycode clitheme generator not-enough-args-err` - -默认文本： - -> Not enough arguments for "{phrase}" at line {num} - -### `subsection-before-domainapp-err` - -完整路径名称：`swiftycode clitheme generator subsection-before-domainapp-err` - -默认文本： - -> Line {num}: in_subsection used before in_domainapp - -### `incomplete-block-err` - -完整路径名称：`swiftycode clitheme generator subsection-before-domainapp-err` - -默认文本： - -> Missing or incomplete header or main block - -## 语法警告提示 - -### `warning-str` - -完整路径名称：`swiftycode clitheme generator warning-str` - -默认文本： - -> Warning: {msg} - -和`error-str`类似，所有的语法警告信息将会通过这个文本输出（文本中的`{msg}`部分）。 - -### `repeated-entry-warn` - -完整路径名称：`swiftycode clitheme generator repeated-entry-warn` - -默认文本： - -> Line {num}: repeated entry "{name}", overwriting - -### `repeated-header-warn` - -完整路径名称：`swiftycode clitheme generator repeated-header-warn` - -默认文本： - -> Line {num}: repeated header info "{name}", overwriting - -## 名称不合规提示 - -数据生成器会对文件内的路径名称进行检查，以确保文件中没有不合规的名称。详见[应用程序适配/路径名称和数据结构.md](../应用程序适配/路径名称和数据结构.md)中的**注意事项**。 - -所有相关的提示信息都会通过`sanity-check-entry-err`，`sanity-check-domainapp-err`，或`sanity-check-subsection-err`中的`{sanitycheck_msg}`显示。 - -### `sanity-check-entry-err` - -完整路径名称：`swiftycode clitheme generator sanity-check-entry-err` - -默认文本： - -> Line {num}: entry subsections/names {sanitycheck_msg} - -### `sanity-check-domainapp-err` - -完整路径名称：`swiftycode clitheme generator sanity-check-domainapp-err` - -默认文本： - -> Line {num}: entry subsections/names {sanitycheck_msg} - -### `sanity-check-subsection-err` - -完整路径名称：`swiftycode clitheme generator sanity-check-subsection-err` - -默认文本： - -> Line {num}: subsection names {sanitycheck_msg} - -### `sanity-check-msg-banphrase-err` - -完整路径名称：`swiftycode clitheme generator sanity-check-msg-banphrase-err` - -默认文本： - -> cannot contain '{char}' - -### `sanity-check-msg-startswith-err` - -完整路径名称：`swiftycode clitheme generator sanity-check-msg-startswith-err` - -默认文本： - -> cannot start with '{char}' \ No newline at end of file diff --git "a/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\350\207\252\345\256\232\344\271\211clitheme\347\232\204\350\276\223\345\207\272.md" "b/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\350\207\252\345\256\232\344\271\211clitheme\347\232\204\350\276\223\345\207\272.md" deleted file mode 100644 index 0fcb2c9692bc692a013d6e1ccb2ca4dab29a2149..0000000000000000000000000000000000000000 --- "a/\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/\350\207\252\345\256\232\344\271\211clitheme\347\232\204\350\276\223\345\207\272.md" +++ /dev/null @@ -1,16 +0,0 @@ -# 自定义clitheme命令行界面的输出 - -你可以通过编写主题定义文件对clitheme的命令行界面输出进行修改和自定义。本文件夹内的文章提供了所有所需的信息，包含所有支持的字符串定义和对应的路径名称和其他信息。 - -请保留字符串中带有花括号的词汇，比如`{content}`，否则自定义文本将不会生效。 - -有关编写主题定义文件的信息，请参考[编写主题定义文件/基本用法.md](../编写主题定义文件/基本用法.md)。 - -## 开发者和应用名称 - -clitheme所有字符串定义的路径名称将采用以下开发者和应用名称，并且永远会以这些名称开头。详见[应用程序适配/路径名称和数据结构.md](../应用程序适配/路径名称和数据结构.md)。 - -- 开发者名称：`swiftycode` -- 应用程序名称：`clitheme` - -所有的路径名称将会以`swiftycode clitheme`开头。比如说：`swiftycode clitheme example-definition` diff --git "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\350\267\257\345\276\204\345\220\215\347\247\260\345\222\214\346\225\260\346\215\256\347\273\223\346\236\204.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/1. \350\267\257\345\276\204\345\220\215\347\247\260\345\222\214\346\225\260\346\215\256\347\273\223\346\236\204.md" similarity index 100% rename from "\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\350\267\257\345\276\204\345\220\215\347\247\260\345\222\214\346\225\260\346\215\256\347\273\223\346\236\204.md" rename to "\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/1. \350\267\257\345\276\204\345\220\215\347\247\260\345\222\214\346\225\260\346\215\256\347\273\223\346\236\204.md" diff --git "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\347\273\231\347\224\250\346\210\267\346\217\220\344\276\233\346\211\200\351\234\200\347\232\204\344\277\241\346\201\257.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/2. \347\273\231\347\224\250\346\210\267\346\217\220\344\276\233\346\211\200\351\234\200\347\232\204\344\277\241\346\201\257.md" similarity index 99% rename from "\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\347\273\231\347\224\250\346\210\267\346\217\220\344\276\233\346\211\200\351\234\200\347\232\204\344\277\241\346\201\257.md" rename to "\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/2. \347\273\231\347\224\250\346\210\267\346\217\220\344\276\233\346\211\200\351\234\200\347\232\204\344\277\241\346\201\257.md" index 7febbb5dbaabd960ab0efda199cc8a9fb4489524..c0b46a8381f94a6e5a7d3f408db19d2ac1a0188f 100644 --- "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\347\273\231\347\224\250\346\210\267\346\217\220\344\276\233\346\211\200\351\234\200\347\232\204\344\277\241\346\201\257.md" +++ "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/2. \347\273\231\347\224\250\346\210\267\346\217\220\344\276\233\346\211\200\351\234\200\347\232\204\344\277\241\346\201\257.md" @@ -15,7 +15,7 @@ 比如说，应用程序可以允许用户通过`--clitheme-output-defs`等类似参数来输出所有的字符串定义： -```txt +```plaintext $ example-app --clitheme-output-defs com.example example-app found-file zh_CN: diff --git "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\344\275\277\347\224\250frontend\346\250\241\345\235\227.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/3. \344\275\277\347\224\250frontend\346\250\241\345\235\227.md" similarity index 90% rename from "\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\344\275\277\347\224\250frontend\346\250\241\345\235\227.md" rename to "\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/3. \344\275\277\347\224\250frontend\346\250\241\345\235\227.md" index a3d98eb1c2e3f6d67935bd260afa024276a34285..1f822d63181d149626e471b4a8910b2e02b12af0 100644 --- "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\344\275\277\347\224\250frontend\346\250\241\345\235\227.md" +++ "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/3. \344\275\277\347\224\250frontend\346\250\241\345\235\227.md" @@ -1,8 +1,8 @@ # 使用clitheme的frontend模块 -为了帮助开发者更方便的添加`clitheme`的适配，本项目提供了一个frontend模块。这个模块包含了抓取当前主题中字符串的功能；只需要调用一个函数就可以了。除此之外，frontend还包括了其他的功能，比如检查当前的主题有没有适配请求的字符串。我打算将在后续版本中添加更多的功能，敬请期待。 +为了帮助开发者更方便的添加`clitheme`的适配，本项目提供了一个frontend模块。这个模块包含了抓取当前主题中字符串的功能；只需要调用一个函数就可以了。除此之外，frontend还包括了其他的功能，比如检查当前的主题有没有适配请求的字符串。 -**注意：** 目前frontend模块只支持使用Python 3编写的应用程序；其他语言编写的程序需要自行访问数据结构。如需更多信息，请见[**路径名称和数据结构**](路径名称和数据结构.md)。 +**注意：** 目前frontend模块只支持使用Python 3编写的应用程序；其他语言编写的程序需要自行访问数据结构。如需更多信息，请见[**路径名称和数据结构**](1.%20路径名称和数据结构.md)。 ## 新建`FetchDescriptor`类 @@ -25,7 +25,7 @@ f = frontend.FetchDescriptor( \ `FetchDescriptor`支持以下参数： - `domain_name`，`app_name`，`subsections`：指定开发者名称，应用名称，和子路径；调用功能时会自动添加到路径中 -- `lang`：指定并且覆盖`clitheme`检测到的系统语言信息（详见[**多语言支持**](../多语言支持.md)），并且使用该参数定义的语言信息（如`zh_CN`，`en_US`，`en_US.UTF-8`等） +- `lang`：指定并且覆盖`clitheme`检测到的系统语言信息（详见[**多语言支持**](../../附录：主题定义文件通用语法/多语言支持.md)），并且使用该参数定义的语言信息（如`zh_CN`，`en_US`，`en_US.UTF-8`等） - 你可以指定多个语言；只要用空格分开即可（如`en_US zh_CN`）。获取字符串时会按照顺序依次尝试获取对应语言的字符串定义。 - `debug_mode`：如果设置为`True`，调用功能时会输出更多信息，用于调试作用 - `disable_lang`：如果设置为`True`，将会禁用自动语言检测，并且调用功能时将会永远使用当前主题定义中的`default`条目。 @@ -43,7 +43,7 @@ f.disable_lang=True 如需获取当前主题定义的某个字符串，请使用`FetchDescriptor`中的`retrieve_entry_or_fallback`函数。调用时需要提供路径名称和默认字符串。如果当前主题设定没有适配该字符串，则该函数会返回提供的默认字符串。你可以将这个函数调用包括在一个`print`语句中，以输出返回的结果。 -该函数会读取系统上的语言设置（详见[**多语言支持**](../多语言支持.md)），并且会优先返回主题定义中对应语言的字符串。该行为可以在创建`FetchDescriptor`时禁用（详见上面）。 +该函数会读取系统上的语言设置（详见[**多语言支持**](../../附录：主题定义文件通用语法/多语言支持.md)），并且会优先返回主题定义中对应语言的字符串。该行为可以在创建`FetchDescriptor`时禁用（详见上面）。 你也可以使用更简短的`reof`函数定义以减少代码量。 @@ -124,16 +124,16 @@ f3=frontend.FetchDescriptor(debug_mode=True) 你可以在你的项目中内置本项目提供的fallback模块，以便更好的处理`clitheme`模块不存在时的情况。该fallback模块包括了frontend模块中的所有定义和功能，并且会永远返回失败时的默认值（fallback）。 -如需使用，请在你的项目文件中导入仓库中的`clitheme_fallback.py`文件，并且在你的程序中包括以下代码： +如需使用，请在你的项目文件中导入仓库中的`frontend_fallback.py`文件，并且在你的程序中包括以下代码： ```py try: from clitheme import frontend except (ModuleNotFoundError, ImportError): - import clitheme_fallback as frontend + import frontend_fallback as frontend ``` 本项目提供的fallback文件会随版本更新而更改，所以请定期往你的项目里导入最新的fallback文件以获得最新的功能。 ## 样例 -如需关于使用frontend模块的样例，请参考本仓库中的`clitheme_demo.py`文件。 \ No newline at end of file +如需关于使用frontend模块的样例，请参考本仓库中的`frontend_demo.py`文件。 \ No newline at end of file diff --git "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/frontend\346\250\241\345\235\227\345\256\214\346\225\264\346\226\207\346\241\243.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/frontend\346\250\241\345\235\227\345\256\214\346\225\264\346\226\207\346\241\243.md" similarity index 97% rename from "\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/frontend\346\250\241\345\235\227\345\256\214\346\225\264\346\226\207\346\241\243.md" rename to "\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/frontend\346\250\241\345\235\227\345\256\214\346\225\264\346\226\207\346\241\243.md" index 81dbccdb7d848bbf643d0f494d8d54f2354a5cff..6b2d841840fd3dedf9dbff10fa1a9c9d8ae8d175 100644 --- "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/frontend\346\250\241\345\235\227\345\256\214\346\225\264\346\226\207\346\241\243.md" +++ "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/frontend\346\250\241\345\235\227\345\256\214\346\225\264\346\226\207\346\241\243.md" @@ -1,6 +1,6 @@ # frontend模块完整文档 -本文章包括了`frontend`模块的完整文档。如需样例和更多信息，请参考[**使用frontend模块**](使用frontend模块.md)。 +本文章包括了`frontend`模块的完整文档。如需样例和更多信息，请参考[**使用frontend模块**](3.%20使用frontend模块.md)。 ## `FetchDescriptor` 类 diff --git "a/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\350\260\203\347\224\250\346\234\254\345\234\260\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\350\260\203\347\224\250\346\234\254\345\234\260\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266.md" similarity index 100% rename from "\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\350\260\203\347\224\250\346\234\254\345\234\260\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266.md" rename to "\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\345\272\224\347\224\250\347\250\213\345\272\217\351\200\202\351\205\215/\350\260\203\347\224\250\346\234\254\345\234\260\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266.md" diff --git "a/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\237\272\346\234\254\347\224\250\346\263\225.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\237\272\346\234\254\347\224\250\346\263\225.md" similarity index 57% rename from "\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\237\272\346\234\254\347\224\250\346\263\225.md" rename to "\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\237\272\346\234\254\347\224\250\346\263\225.md" index 34be4724b318303bdd95932280b8a66f26d48323..1c6395d25f87e6a31686438467c4e63030da0ead 100644 --- "a/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\237\272\346\234\254\347\224\250\346\263\225.md" +++ "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\237\272\346\234\254\347\224\250\346\263\225.md" @@ -12,22 +12,28 @@ 你可以使用`#`来标记注释。注释不会被处理或读取。比如： - # this is a comment +```plaintext +# this is a comment +``` **注意：** 注释只能在新的一行上定义。请不要在行的末尾定义注释。 - # 错误用法： - begin_header # Some comments here +```plaintext +# 错误用法： +{header_section} # Some comments here +``` ## 定义基本信息 为了确保使用命令行工具输出当前主题信息时能清晰的辨识到主题，请在文件中包括并定义一些基本信息。 -这些基本信息需要在`header`段落内被定义。如需创建`header`段落，请使用`begin_header`开始段落和`end_header`结束段落。 +这些基本信息需要在`header`段落内被定义。如需创建`header`段落，请使用`{header_section}`开始段落和`{/header_section}`结束段落。 - begin_header - <...> - end_header +```plaintext +{header_section} + <...> +{/header_section} +``` 在`header`段落内可以定义以下信息。你不需要定义所有的信息，但是建议定义以下所有的信息。 @@ -41,54 +47,56 @@ 下面将展示一个`header`段落样例： -``` -begin_header +```plaintext +{header_section} name example-app颜文字主题 description 为example-app制作的一个可爱的颜文字主题 version 1.0 locales zh_CN en_US supported_apps example-app example-app-2 -end_header +{/header_section} ``` ## 编写字符串定义 -### 使用`main`段落 +### 使用`entries`段落 -所有的字符串定义会被包括在`main`段落中。请使用和`header`段落相同的格式定义`main`段落： +所有的字符串定义会被包括在`entries`段落中。请使用和`header`段落相同的格式定义`entries`段落： - begin_main + {entries_section} <...> - end_main + {/entries_section} -### 使用`entry`段落 +### 使用`entry`定义 -要定义一个字符串，请使用`entry`段落，并且包括该字符串的路径名称，如`entry com.example example-app text-one`。如需获取路径名称，请参考相关应用程序的帮助信息或文档。 +要定义一个字符串，请使用`entry`定义，并且包括该字符串的路径名称，如`[entry] com.example example-app text-one`。如需获取路径名称，请参考相关应用程序的帮助信息或文档。 -`clitheme`的核心设计理念之一是多语言支持，所以字符串本体需要在`locale`行中定义。`locale`行的格式为：`locale <字符串>`。当前的系统语言会被自动获取，并且会使用对应的定义。 +`clitheme`的核心设计理念之一是多语言支持，所以字符串本体需要在`locale`行中定义。`locale`行的格式为：`locale: <字符串>`。当前的系统语言会被自动获取，并且会使用对应的定义。 -`locale`中的语言必须是系统语言格式，如`zh_CN`和`en_US`。你可以在命令行中使用`locale`命令查看当前系统语言。（详见文章**多语言支持**） +`locale`中的语言必须是系统语言格式，如`zh_CN`和`en_US`。你可以在命令行中使用`locale`命令查看当前系统语言。（详见文章[多语言支持](../../附录：主题定义文件通用语法/多语言支持.md)） -定义字符串时建议添加`default`语言（`locale default <字符串>`）。如果该字符串不支持当前的系统语言，会使用`default`语言定义。如果`default`语言没有被定义，只会在字符串支持当前系统语言的情况下调用该字符串。 +定义字符串时建议添加`default`语言（`locale:default <字符串>`）。如果该字符串不支持当前的系统语言，会使用`default`语言定义。如果`default`语言没有被定义，只会在字符串支持当前系统语言的情况下调用该字符串。 如果你不需要为应用程序添加多语言支持，只定义`default`语言就可以了。 下面将展示一个样例： -``` -# 在main段落中（begin_main） -entry com.example example-app text-one - locale default Some text - locale en_US Some text - locale zh_CN 一些文本 -end_entry +```plaintext +{entries_section} + # ... + [entry] com.example example-app text-one + locale:default Some text + locale:en_US Some text + locale:zh_CN 一些文本 + [/entry] +{/entries_section} ``` ### 使用`in_domainapp`和`in_subsection` 你可以使用`in_domainapp`和`in_subsection`以节省文件中的代码量。被定义时，这个信息会自动被添加在所有的`entry`定义前，以` `的格式处理。 -如需了解关于子路径的更多信息，请参考[**应用程序适配/路径名称和数据结构**](../应用程序适配/路径名称和数据结构.md)。 +如需了解关于子路径的更多信息，请参考[**应用程序和字符串定义API/应用程序适配/路径名称和数据结构**](../../应用程序和字符串定义API/应用程序适配/1.%20路径名称和数据结构.md)。 `in_domainapp`的格式为`in_domainapp `，并且不能有多余的空格。`in_subsection`的格式为`in_subsection `，并且可以有多个subsection和空格。 @@ -96,27 +104,52 @@ end_entry **注意：** 使用`in_domainapp`和`unset_domainapp`时会同时取消定义之前设定的`in_subsection`信息。 +```plaintext +{entries_section} + in_domainapp com.example example-app + # 和 com.example example-app entry-one 相同 + [entry] entry-one + locale:default Some text + [/entry] + + in_subsection subsection-one subsection-two + # 和 com.example example-app subsection-one subsection-two entry-two 相同 + [entry] entry-two + locale:default Some text + [/entry] + + in_subsection subsection-three + # 和 com.example example-app subsection-three entry-three 相同 + [entry] entry-three + locale:default Some text + [/entry] + # 会同时取消定义subsection + unset_domainapp +{/entries_section} ``` -# 在main段落中（begin_main） -in_domainapp com.example example-app - # 和 com.example example-app entry-one 相同 - entry entry-one - locale default Some text - end_entry - - in_subsection subsection-one subsection-two - # 和 com.example example-app subsection-one subsection-two entry-two 相同 - entry entry-two - locale default Some text - end_entry - - in_subsection subsection-three - # 和 com.example example-app subsection-three entry-three 相同 - entry entry-three - locale default Some text - end_entry -# 会同时取消定义subsection -unset_domainapp + +### 同时指定多个路径名称 + +在字符串定义内容相同的情况下，你可以为一个字符串定义添加多个路径名称。该功能可以免去对替换内容和定义段落的重复复制粘贴，并且修改替换内容会简单很多。如需使用，请同时指定多个`[entry]`语句，比如： + +```plaintext +{entries_section} + [entry] entry-one + [entry] another-entry + [entry] entry-three + locale:default Some string definition content + [/entry] + # 上方定义等于以下定义： + [entry] entry-one + locale:default Some string definition content + [/entry] + [entry] another-entry + locale:default Some string definition content + [/entry] + [entry] entry-three + locale:default Some string definition content + [/entry] +{/entries_section} ``` ### 样例 diff --git "a/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\244\232\350\241\214\345\206\205\345\256\271\346\256\265\350\220\275.md" "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\244\232\350\241\214\345\206\205\345\256\271\346\256\265\350\220\275.md" new file mode 100644 index 0000000000000000000000000000000000000000..f1178d11f170b71b5461641df368c7413ad182e3 --- /dev/null +++ "b/\345\272\224\347\224\250\347\250\213\345\272\217\345\222\214\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211API/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\244\232\350\241\214\345\206\205\345\256\271\346\256\265\350\220\275.md" @@ -0,0 +1,42 @@ +# 多行内容段落 + +主题定义文件中的部分定义支持多行内容段落。它允许你在一个定义中包括拥有多个行数的字符串，或允许你定义带有空格的名称和项目。 + +如需定义多行内容段落段落，请在支持的定义名称中添加`[`和`]`（比如：`[locales]`, `[description]`），并且使用`[/]`结束段落（如`[/locales]`，`[/description]`。 + +## header段落 + +请见[附录：主题定义文件通用语法/header段落](../../附录：主题定义文件通用语法/header段落.md)。 + +## entries段落 + +在`entries`段落中，`entry`中的字符串定义（`locale`）支持多行内容段落，并且通过`[locale]`定义。 + +**提示：** 你可以定义多个语言，省去重复复制粘贴的过程。多个语言由空格分开。 + +```plaintext +{entries_section} + <...> + [entry] example-entry + # 你可以定义多个语言 + [locale] en_US C zh_CN + This is an entry + Another line like that + A new line + [/locale] + [/entry] + <...> +{/entries_section} +``` + +应用程序调用`example-entry`时会显示： + +```plaintext +This is an entry +Another line like that +A new line +``` + +## 更多信息 + +更多信息请见[附录：主题定义文件通用语法/多行内容段落](../../附录：主题定义文件通用语法/多行内容段落.md)。 \ No newline at end of file diff --git "a/\347\256\200\344\273\213.md" "b/\347\256\200\344\273\213.md" index b851bb642e395155c207cd9810490ea96887a5d0..e5ce4a4e5d73483de767165c8dd0d34b734506f1 100644 --- "a/\347\256\200\344\273\213.md" +++ "b/\347\256\200\344\273\213.md" @@ -1,73 +1,92 @@ # clitheme简介 -`clitheme`是一个主要面向命令行应用程序的文本主题/自定义框架。它允许你修改和自定义命令行应用程序的提示和输出；只要应用程序适配了这个框架就可以。通过编写**主题定义文件**，你可以给你最喜爱的应用程序添加你想要的风格和个性。无论是把它们变得活泼可爱，模拟二次元角色的语句，甚至只是添加多语言支持，`clitheme`允许你自由发挥你的想象，把你的命令行环境变成你想要的样子。 +`clitheme`允许你通过输出替换规则来自定义任何命令行应用程序的终端输出。通过编写**主题定义文件**，你可以给你最喜爱的应用程序添加你想要的风格和个性。无论是把它们变得活泼可爱，模拟二次元角色的语句，甚至只是添加多语言支持，`clitheme`允许你自由发挥你的想象，把你的命令行环境变成你想要的样子。 -**这些文档适配`clitheme`的`v1.1`版本。** +## 主要功能 -## 样例 +`clitheme`包含以下主要功能： -比如说，这是一个帮你安装文件的一个小工具，它的输出是长这样子的： +- 对任何命令行应用程序的输出通过定义替换规则进行修改和自定义 +- 自定义Unix/Linux文档手册（manpage） +- 包含类似于本地化套件（如GNU gettext）的应用程序API，帮助用户更好的自定义提示信息的内容 -```txt -$ example-app install-files -在当前目录找到了2个文件 --> 正在安装 "example-file"... --> 正在安装 "example-file-2"... -已成功安装2个文件 -$ example-app install-file foo-nonexist -错误：找不到文件 "foo-nonexist" +有关这些功能的更多信息，请见文档中的对应文件夹。 + +## 使用样例 + +该使用样例会展示`clitheme`的主要功能之一：命令行输出替换功能。 + +比如说，你在使用`clang`编译器，它的错误提示输出是长这样的： + +```plaintext +$ clang test.c +test.c:1:1: error: unknown type name 'bool' +bool *haku(int *a) { +^ +test.c:4:3: warning: incompatible pointer types assigning to 'char *' from 'int *' [-Wincompatible-pointer-types] + b=a; + ^~ +2 errors generated. ``` -是不是觉得有一点太平淡无趣了？没关系，我们可以把它的输出变得活泼可爱一点。只需要参考这个工具的相关文档，编写一个主题定义文件，里面加上你想要的语句输出就可以了： - -```txt -begin_header - name 样例主题 - version 1.0 - locales zh_CN -end_header - -begin_main - in_domainapp com.example example-app - entry found-file - locale default o(≧v≦)o 太好了，在当前目录找到了{}个文件！ - locale zh_CN o(≧v≦)o 太好了，在当前目录找到了{}个文件！ - end_entry - entry installing-file - locale default (>^ω^<) 正在安装 "{}"... - locale zh_CN (>^ω^<) 正在安装 "{}"... - end_entry - entry install-success - locale default o(≧v≦)o 已成功安装{}个文件！ - locale zh_CN o(≧v≦)o 已成功安装{}个文件！ - end_entry - entry file-not-found - locale default ಥ_ಥ 糟糕，出错啦！找不到文件 "{}" - locale zh_CN ಥ_ಥ 糟糕，出错啦！找不到文件 "{}" - end_entry -end_main +是不是觉得有一点太平淡无趣了？没关系，我们可以把它的输出变得活泼可爱一点。只需要根据输出内容编写一个主题定义文件，里面加上你想要的语句输出就可以了： + +```plaintext +{header_section} + name clang样例主题 + [description] + 一个为clang打造的的样例主题，为了演示作用 + [/description] +{/header_section} + +{substrules_section} + # 设定"substesc"选项：内容中的"{{ESC}}"字样会被替换成ASCII Escape终端控制符号 + set_options substesc + [filter_commands] + clang + clang++ + gcc + g++ + [/filter_commands] + # clang的输出包含用于设定字体颜色的终端控制字符：请使用"clitheme-exec --debug-showchars clang test.c"以显示它们 + [substitute_regex] (?P^({{ESC}}.*?m)*(.+:\d+:\d+:) ({{ESC}}.*?m)*)warning: (?P({{ESC}}.*?m)*)incompatible pointer types assigning to '(?P.+)' from '(?P.+)' + locale:default \g杂鱼～: \g'\g'从不兼容的指针类型赋值为'\g',纯爱战神很生气！ + [/substitute_regex] + [substitute_regex] (?P^({{ESC}}.*?m)*(.+:\d+:\d+:) ({{ESC}}.*?m)*)error: (?P({{ESC}}.*?m)*)unknown type name '(?P.+)' + locale:default \g笨蛋！: \g未知的类型名'\g',是忘了定义了吗喵？ + [/substitute_regex] +{/substrules_section} ``` 相比之前是不是变可爱了很多？接下来，我们通过`clitheme`的命令行工具来应用一下这个主题： -```txt -$ clitheme apply-theme example-app-theme_clithemedef.txt +```plaintext +$ clitheme apply-theme clang-theme_clithemedef.txt ==> Generating data... Successfully generated data ==> Applying theme...Success Theme applied successfully ``` -现在，这个主题已经应用在你的电脑中了。对应的应用程序可以访问并且显示你写的自定义字符串，从而达到自定义输出的效果。我们再运行一下这个小工具： +现在，这个主题已经应用在你的电脑中了。你可以通过`clitheme-exec`运行命令来对输出实施这些替换规则，从而达到自定义输出的效果： -```txt -$ example-app install-files -o(≧v≦)o 太好了，在当前目录找到了2个文件！ -(>^ω^<) 正在安装 "example-file"... -(>^ω^<) 正在安装 "example-file-2:"... -o(≧v≦)o 已成功安装2个文件！ -$ example-app install-file foo-nonexist -ಥ_ಥ 糟糕，出错啦！找不到文件 "foo-nonexist" +```plaintext +$ clitheme-exec clang test.c +test.c:1:1: 杂鱼～: 未知的类型名'bool',是忘了定义了吗喵？ +bool *haku(int *a) { +^ +test.c:4:3: 笨蛋！: 'char *'从不兼容的指针类型赋值为'int *',纯爱战神很生气！ [-Wincompatible-pointer-types] + b=a; + ^~ +2 errors generated. ``` -我们可以看到这个工具输出了你自定义的字符串，变成了你想要的样子。关于编写主题定义文件的更多信息，请参考Wiki文章[**编写主题定义文件/基本用法**](编写主题定义文件/基本用法.md)。 \ No newline at end of file +我们可以看到该程序的输出变成了你想要的样子，根据定义的替换规则被修改。 + +关于编写主题定义文件的更多信息，请参考[命令行输出替换/编写定义文件](命令行输出替换/1.%20编写定义文件.md)。 + +（本样例中的部分内容来自于`kawaii-gcc`项目。项目地址：https://github.com/Bill-Haku/kawaii-gcc） + +## 更多信息 + +更多样例、安装与构建软件包、和更多信息请见本项目主仓库中的README文档。 \ No newline at end of file diff --git "a/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\244\232\350\241\214\350\276\223\345\205\245.md" "b/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\244\232\350\241\214\350\276\223\345\205\245.md" deleted file mode 100644 index f971baa9cce8bfd691bf73903bcec760bdda5ae0..0000000000000000000000000000000000000000 --- "a/\347\274\226\345\206\231\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266/\345\244\232\350\241\214\350\276\223\345\205\245.md" +++ /dev/null @@ -1,117 +0,0 @@ -# 多行输入功能 - -主题定义文件中的部分定义支持段落输入/多行输入。它允许你在一个定义中包括拥有多个行数的字符串，或允许你定义带有空格的名称和项目。 - -如需定义多行输入段落，请在支持的定义名称后添加`_block`字样（比如：`locales_block`, `description_block`），并且使用`end_block`结束段落。 - -## header段落 - -在`header`段落中，以下定义支持多行输入： -- `description`（`description_block`） -- `supported_apps`（`supported_apps_block`） -- `locales`（`locales_block`） - -在`supported_apps_block`和`locales_block`中，多个项目标注将以换行分开，而不是空格分开。这允许你在项目名称内插入空格。比如： - -``` -begin_header - # <...> - description_block - Some description here - Another description here - end_block - locales_block - Simplified Chinese (zh_CN) - English (en_US) - end_block - supported_apps_block - App one - App two - App three - end_block -end_header -``` - -使用`clitheme get-current-theme-info`列出信息时会这样展示： - -``` -<...> -Description: -Some description here -Another description here - -Supported locales: -• Simplified Chinese (zh_CN) -• English (en_US) -Supported apps: -• App one -• App two -• App three -``` - -## main段落 - -在`main`段落中，`entry`中的字符串定义（`locale`）支持多行输入，并且通过`locale_block`定义。 - -**提示：** 你可以定义多个语言，省去重复复制粘贴的过程。多个语言由空格分开。 - -``` -begin_header - <...> - entry example-entry - # 你可以定义多个语言 - locale_block en_US C zh_CN - This is an entry - Another line like that - A new line - end_block - end_entry -``` - -应用程序调用`example-entry`时会显示： - -``` -This is an entry -Another line like that -A new line -``` - - -## 关于缩进/边缘空格的处理 - -**注意：** 多行输入内容中的结尾空格及whitespace将会被忽略。 - -但是，起始空格和whitespace会被减去多行输入内容内的共同whitespace大小（tab符号将会被视为8个空格）。这意味着行数之间的缩进差距将会被保留，但是暂不支持在仅有一行的内容中保留缩进和空格。 - -这意味着： - -``` -entry entry1 - locale_block default - Text 1 - Text 2 - Text 3 - Text 4 - end_block -end_entry -entry entry2 - locale_block default - Text 1 - end_block -end_entry - -``` - -被读取时会返回以下内容： - -`entry1`： -``` -Text 1 - Text 2 - Text 3 -Text 4 -``` - -`entry2`： - - Text 1 \ No newline at end of file diff --git "a/\350\207\252\345\256\232\344\271\211manpage\346\226\207\346\241\243/1. \347\274\226\345\206\231\345\256\232\344\271\211\346\226\207\344\273\266.md" "b/\350\207\252\345\256\232\344\271\211manpage\346\226\207\346\241\243/1. \347\274\226\345\206\231\345\256\232\344\271\211\346\226\207\344\273\266.md" new file mode 100644 index 0000000000000000000000000000000000000000..7b50e15661fd010ccaa78e99d8db5de66858191d --- /dev/null +++ "b/\350\207\252\345\256\232\344\271\211manpage\346\226\207\346\241\243/1. \347\274\226\345\206\231\345\256\232\344\271\211\346\226\207\344\273\266.md" @@ -0,0 +1,79 @@ +# 主题定义文件中`manpage_section` + +本文章将介绍主题定义文件中的`manpage`段落语法。这个段落允许你添加自定义的Unix文档手册（`manpage`） +文档，达到文档自定义的目的。使用`clitheme`命令行工具应用主题定义文件后，你可以使用`clitheme-man`来查看这些手册文档。 + +有关Unix/Linux文档手册的更多信息，请见[本文章](https://www.man7.org/linux/man-pages/man1/man.1.html)。 + +## 编写`header`段落 + +你需要先定义该主题/文件的一些基本信息，包括名称、简介等。请见[header段落](../附录：主题定义文件通用语法/header段落.md) + +## 关于文件路径的重要信息 + +在本文档中会提到**目标文件路径**。它指的是该文档手册定义应该放在manpath中（如`/usr/share/man`中的路径结构）的什么地方，用的是相对路径。比如说，如果该文档手册在章节1中，文件路径应该是`man1/.1`；如果在章节3中，应该是`man3/.3`。如果你想包括特定语言的文档手册，请在文件路径之前加上系统语言（locale）名称，比如`zh_CN/man1/.1`。有关章节的更多信息，请见上述提到的文章。 + +在定义文件中，文件路径中的子路径是由空格分开的，不是以划线分开的，并且不能包含任何划线（`/`、`\`）。所以说，`man1/.1`应该在定义文件中写成`man1 .1`。 + +## `manpage`段落 + +在定义文件中，所有的Unix文档手册都是在`manpage`段落中实现的。请使用以下语法定义`manpage`段落： + +```plaintext +{manpage_section} + <在这里定义manpage文档> +{/manpage_section} +``` + +### 文件内容：`[file_content]` + +你可以使用`[file_content]`语法通过输入文件内容来定义文档手册。在`[file_content]`语句后面需要添加目标文件路径，比如`[file_content] man1 example-app.1`。 + +在`[file_content]`中的文件内容会根据多行内容段落的机制处理。详见[多行内容段落](../附录：主题定义文件通用语法/多行内容段落.md) + +你可以同时指定多个`[file_content]`语句，以在同一文件内容下覆盖多个文档文件。它们必须指定与相邻的`[file_content]`语句之后，**并且中间可以有空行或注释**。在其他内容后插入`[file_content]`语句会被视为文件内容，而不是语法定义。 + +```plaintext +{manpage_section} + [file_content] man1 clitheme-man.1 + [file_content] man8 clitheme-man.8 + .TH clitheme-man 1 2024-05-07 + .SH NAME + clitheme\-man \- access manual pages in the current theme + .SH SYNOPSIS + .B clitheme-man [OPTIONS] + .SH DESCRIPTION + \fIclitheme-man\fR is a wrapper for \fIman(1)\fR that accesses the manual pages defined in a theme definition file. The current theme definition on the system is controlled through \fIclitheme(1)\fR. + .P + \fIclitheme-man\fR is designed to be used the same way as \fIman(1)\fR; the same arguments and options will work on \fIclitheme-man\fR. + .SH OPTIONS + For a list of options you can use, please see \fIman(1)\fR. + .SH SEE ALSO + \fIclitheme(1)\fR, \fIman(1)\fR + [/file_content] +{/manpage_section} +``` + +### 引用文件：`include_file`和`[include_file]` + +你可以使用`include_file`语法来使用定义文件所在文件夹中的一个文件来作为文档手册的文件内容，并且在下一行中使用`as`语法来定义目标文件路径。你需要在两者后面加上文件路径：在`include_file`后根据**目标文件路径**语法添加引用文件的相对文件路径（根据**定义文件所在的文件夹/路径**计算，不是终端的PWD/当前路径位置），并且在`as`后添加目标文件路径。 + +你也可以使用`[include_file]`段落来指定多个目标文件，以使用同一个源文件来覆盖多个文档。 + +```plaintext +{manpage_section} + # 如果主题定义文件的路径是"Documents/example-doc.clithemedef.txt"，那引用的文件会从"Documents/doc_manpages/example-app.1"读取 + include_file doc_manpages example-app.1 + as man1 example-app.1 + # 你也可以使用以下语法来覆盖多个目标文档文件 + [include_file] doc_manpages example-app.1 + as man1 example-app.1 + as man1 app-example.1 + as man1 example.1 + [/include_file] +{/manpage_section} +``` + +## 应用主题（`clitheme apply-theme`） + +主题定义文件写好后，你需要应用这个文件到系统中。请在终端执行`clitheme apply-theme <文件名>`以应用主题。应用好主题后，请使用`clitheme-man`来使用这些文档手册。详见[使用clitheme-man](2.%20使用clitheme-man.md)。 \ No newline at end of file diff --git "a/\350\207\252\345\256\232\344\271\211manpage\346\226\207\346\241\243/2. \344\275\277\347\224\250clitheme-man.md" "b/\350\207\252\345\256\232\344\271\211manpage\346\226\207\346\241\243/2. \344\275\277\347\224\250clitheme-man.md" new file mode 100644 index 0000000000000000000000000000000000000000..e17f0a3a2e65eb9cf86686879d0e952821554fe1 --- /dev/null +++ "b/\350\207\252\345\256\232\344\271\211manpage\346\226\207\346\241\243/2. \344\275\277\347\224\250clitheme-man.md" @@ -0,0 +1,22 @@ +# 使用`clitheme-man`命令行工具 + +使用`clitheme-man`命令行工具以查看并使用自定义的Unix文档手册。这些自定义的文档手册通过主题定义文件中的`manpage`段落定义。`clitheme-man`会修改`MANPATH`环境变量以包括这些自定义文档手册，并且直接执行系统中的`man`命令行工具。所以，`clitheme-man`的选项和参数与`man`完全一样；你可以把`clitheme-man`当成`man`使用。 + +你可以使用`clitheme-man`或`python3 -m clitheme.man`： + +```plaintext +$ clitheme-man +What manual page do you want? +``` + +注意：如需在代码仓库文件夹中调用`clitheme-man`，请调用仓库中的模块文件： + +```plaintext +# 在仓库根目录中执行： +$ python3 -m src.clitheme.man +<...> +``` + +## 使用方法 + +直接把`clitheme-man`当成`man`使用就可以了。如需对应的使用方法，请参考[本文章](https://manpages.debian.org/bookworm/man-db/man.1.zh_CN.html)或系统中对应的文档手册（`man(1)`）。 \ No newline at end of file diff --git "a/\351\231\204\345\275\225\357\274\232clitheme\345\221\275\344\273\244\350\241\214\345\267\245\345\205\267\347\232\204\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/README.md" "b/\351\231\204\345\275\225\357\274\232clitheme\345\221\275\344\273\244\350\241\214\345\267\245\345\205\267\347\232\204\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/README.md" new file mode 100644 index 0000000000000000000000000000000000000000..2462d06b034c0e754077c3a22f6ec2530a467ae1 --- /dev/null +++ "b/\351\231\204\345\275\225\357\274\232clitheme\345\221\275\344\273\244\350\241\214\345\267\245\345\205\267\347\232\204\345\255\227\347\254\246\344\270\262\345\256\232\344\271\211/README.md" @@ -0,0 +1,29 @@ +# 自定义clitheme命令行界面的输出 + +你可以通过编写主题定义文件对clitheme的命令行界面输出进行修改和自定义。 + +有关编写主题定义文件的信息，请参考[应用程序和字符串定义API/编写主题定义文件/基本用法](../应用程序和字符串定义API/编写主题定义文件/基本用法.md)。 + +## 使用源代码内的本地化文件 + +为了让`clitheme`的命令行工具的提示信息适配中文，本项目使用了主题定义文件来实现这个功能。请在仓库源代码中找到这些文件，并且作为模版使用。如需自定义这些提示信息，请复制这些文件，并且添加你想要的修改。之后，请使用`clitheme apply-theme`应用主题。应用后，更改会立即生效。 + +请保留字符串中带有花括号的词汇，比如`{content}`，否则自定义文本将不会生效。 + +这些文件可以在以下地址中找到： + +- https://gitee.com/swiftycode/clitheme/tree/latest-STABLE/src/clitheme/strings +- https://github.com/swiftycode256/clitheme/tree/latest-STABLE/src/clitheme/strings + +## 开发者和应用名称 + +clitheme所有字符串定义的路径名称将采用以下开发者和应用名称，并且永远会以这些名称开头。详见[应用程序和字符串定义API/应用程序适配/路径名称和数据结构](../应用程序和字符串定义API/应用程序适配/1.%20路径名称和数据结构.md)。 + +- 开发者名称：`swiftycode` +- 应用程序名称：`clitheme` + +所有的路径名称将会以`swiftycode clitheme`开头。比如说：`swiftycode clitheme example-definition` + +## 为什么不在文档中提供字符串定义的信息？ + +自`v2.0`的文档开始，每个字符串定义的详细信息将不再提供。这是因为一个版本中可能会添加很多的提示信息和对应的字符串定义；维护文档中的信息会过于麻烦和耗时。并且，所有需要的信息都可以在源代码中的主题定义文件找到，没必要在文档中重复这些多余的信息。 \ No newline at end of file diff --git "a/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/header\346\256\265\350\220\275.md" "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/header\346\256\265\350\220\275.md" new file mode 100644 index 0000000000000000000000000000000000000000..f39af4e396dc6647ea0722fd86a2af2ccea55b4a --- /dev/null +++ "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/header\346\256\265\350\220\275.md" @@ -0,0 +1,82 @@ +# 主题定义文件中的`header`段落 + +为了确保使用命令行工具输出当前主题信息时能清晰的辨识到主题，请在文件中包括并定义一些基本信息。 + +## 基本语法 + +这些基本信息需要在`header`段落内被定义。如需创建`header`段落，请使用`{header_section}`开始段落和`{/header_section}`结束段落。**在所有的定义文件中，这个段落是需要的。** + +```plaintext +{header_section} + <...> +{/header_section} +``` + +在`header`段落内可以定义以下信息。你不需要定义所有的信息，但是建议定义以下所有的信息。 + +- `name`：定义该主题的名称，如**example-app颜文字主题**。 +- `description`: 定义该主题的更多详细信息。 +- `version`：定义该主题的版本。比如说，如果你添加或修改了其中的内容，你可以通过这个信息来跟踪修改版本，如`1.0`。 +- `locales`：定义主题支持哪些语言。如果支持多个语言，请使用空格分开。比如：`en_US zh_CN`或`English Chinese` +- `supported_apps`：定义主题支持的应用程序。如果支持多个应用程序，请使用空格分开。比如：`example-app example-app-2 another-example-app` + +**注意：** 除了`description`定义以外，定义内容中的任何终端控制符号和不可见字符使用`clitheme get-current-theme-info`时将会以明文输出（比如`<\x1b>`）。所以，请不要在这些地方使用终端控制符号；它们不会生效。 + +下面将展示一个`header`段落样例： + +```plaintext +{header_section} + name example-app颜文字主题 + description 为example-app制作的一个可爱的颜文字主题 + version 1.0 + locales zh_CN en_US + supported_apps example-app example-app-2 +{/header_section} +``` + +## 多行内容段落 + +多行内容段落允许你通过多行定义和输入内容。更多信息请见[多行内容段落](多行内容段落.md)。 + +你可以在以下定义使用多行内容段落： + +- `description`（使用`[description]`和`[/description]`） +- `supported_apps`（使用`[supported_apps]`和`[/supported_apps]`） +- `locales`（使用`[locales]`和`[/locales]`） + +在`[supported_apps]`和`[locales]`中，多个项目标注将以换行分开，而不是空格分开。这允许你在项目名称内插入空格。比如： + +```plaintext +{header_section} + # <...> + [description] + Some description here + Another description here + [/description] + [locales] + Simplified Chinese (zh_CN) + English (en_US) + [/locales] + [supported_apps] + App one + App two + App three + [/supported_apps] +{/header_section} +``` + +使用`clitheme get-current-theme-info`列出信息时会这样展示： + +```plaintext +<...> +Description: +Some description here +Another description here +Supported locales: +• Simplified Chinese (zh_CN) +• English (en_US) +Supported apps: +• App one +• App two +• App three +``` \ No newline at end of file diff --git "a/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\206\205\345\256\271\345\217\230\351\207\217.md" "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\206\205\345\256\271\345\217\230\351\207\217.md" new file mode 100644 index 0000000000000000000000000000000000000000..62bf9e6e22f8a49339a7ff44b7f5efd4db54b8a8 --- /dev/null +++ "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\206\205\345\256\271\345\217\230\351\207\217.md" @@ -0,0 +1,73 @@ +# 内容变量的定义和使用 + +你可以在主题定义文件中定义和使用**内容变量**，可以帮助你面去重复复制粘贴内容段落中重复的内容，并且可以更轻松的批量更改内容。 + +## 定义变量 + +你可以在段落之外或在段落内定义变量。如需定义变量，请使用`setvar:<变量名称> <内容>`语法。请注意，变量名称不能包含`(){}[]`中的任一字符，并且不能为`ESC`（因为会和`substesc`功能选项冲突）。 + +```plaintext +{substrules_section} + setvar:example_var This is some example content + setvar:var2 Another example variable + # <...> +{/substrules_section} +# 你也可以在段落之外定义变量（全局定义） +setvar:another_var Some variable content +setvar:var3 Third variable! +``` + +### 全局定义和段落内定义的区别 + +在全局定义是指在段落外定义的变量。段落内定义的变量只会在该段落内有效。结束该段落后，当前的变量定义将会复原成现有的全局定义。该规则也同样适用于给现有的变量改变/重新赋值内容的操作。 + +## 使用变量 + +如需使用变量，请先设定`substvar`选项（使用`set_options substvar`），然后在内容中使用`{{<变量名称>}}`语法，比如`{{example_var}}`。样例： + +```plaintext +setvar:name Vim +set_options substvar +{header_section} + name {{name}} theme + version 9.1 + description A simple theme for {{name}} + supported_apps {{name}} +{/header_section} +``` + +需要注意的是，变量不能替代语法定义。这意味着你不能使用以下语法： + +```plaintext +set_options substvar +setvar:place1 name +setvar:place2 version +{header_section} + # 错误用法： + {{place1}} Vim theme + {{place2}} 9.1 +{/header_section} +``` + +这意味着内容变量可以在任何**不是语法词语**的地方使用。 + +**注意：** 变量名称中不能包含任何空格，否则将不会被处理。比如：`{{var }}`和`{{this and}}`将不会被处理 + +**注意：** 如果变量内容中带有`{{ESC}}`字样，且`substesc`选项是设定的，变量内容中的`{{ESC}}`在定义时不会被处理；只会在相应地方和定义使用中才会被处理。 + +如需禁用变量替换，请取消设定`substvar`选项（使用`set_options nosubstvar`）。更多信息请见[可以设定的选项](./可以设定的选项.md)。 + +## 在变量定义中引用另一个变量的内容 + +你可以在变量的定义内容中通过上述方法引用另一个变量的内容。前提是：在定义变量之前设定`substvar`选项。样例： + +```plaintext +setvar:example_one Some text here +# 启用substvar之前，将不会替换变量名称 +# 内容：{{example_one}} with another text +setvar:example_two {{example_one}} with another text +set_options substvar +# 启用substvar之后将会替换变量名称 +# 内容：Some text here with another text +setvar:example_three {{example_one}} with another text +``` \ No newline at end of file diff --git "a/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\217\257\344\273\245\350\256\276\345\256\232\347\232\204\351\200\211\351\241\271.md" "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\217\257\344\273\245\350\256\276\345\256\232\347\232\204\351\200\211\351\241\271.md" new file mode 100644 index 0000000000000000000000000000000000000000..ed4ad85af3056d4f102978cb3facffd245da3c51 --- /dev/null +++ "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\217\257\344\273\245\350\256\276\345\256\232\347\232\204\351\200\211\351\241\271.md" @@ -0,0 +1,100 @@ +# 定义文件中的选项 + +本文章将介绍主题定义文件中可以设定的选项，以及如何使用并设定它们。 + +## 如何设定选项 + +你可以使用`set_options <选项>`语法来设定选项。你可以同时指定多个选项设定；只需要使用空格分开即可。设定后，这些选项将会被应用在该语句之后的相关定义。比如：`set_options substesc substvar leadtabs:1` + +你也可以对单个定义设定这些选项；只需要在它们的结束语句之后添加这些选项设定就可以了。这些设定会覆盖之前通过`set_options`设定的选项设置。比如说：`[/substitute_regex] subststdoutonly endmatchhere`或`[/locale] substesc substvar leadtabs:1` + +```plaintext +{substrules_section} + # substesc和endmatchhere选项会对以下所有的匹配规则生效 + set_options endmatchhere substesc + [substitute_string] Some text + [locale] default + Some other text here + Good stuff {{ESC}} + [/locale] + [/substitute_string] subststderronly + [substitute_string] Some other text + [locale] default + Another good stuff + [/locale] + [/substitute_string] noendmatchhere subststdoutonly + # 上方定义的noendmatchhere会覆盖之前在set_options中定义的endmatchhere + [substitute_regex] Error at file number (?P\d+): item (?P.+) not found + # 如果想对以下内容设定选项，需要使用多行内容段落 + locale:zh_CN (ToT)/~~~ 在文件\g发生错误：找不到项目"\g"！(>﹏<) + locale:default (ToT)/~~~ Error at file number \g! Could not find item "\g"! + [/substitute_regex] +{/substrules_section} +``` + +### 全局定义和段落内定义的区别 + +全局定义是指在段落外定义的选项设定；段落内定义的选项设定只会在该段落内有效。结束该段落后，当前的选项设定将会复原成现有的全局定义。 + +## 选项定义 + +### 多行内容段落缩进/空格设定 + +以下几个设定仅适用于多行内容段落（`header`段落仅支持`[description]`段落）： + +以下设定中的``应该输入一个整数数字，并且选项名称与数值之间不能有空格。比如：`leadspaces:4` + +- `leadtabindents:`：多行内容段落中为每一行的开始添加``个tab缩进 +- `leadspaces:`：多行内容段落中为每一行的开始添加``个空格 + +#### 样例： + +```plaintext +[entry] entry2 + [locale] default + Text 1 + Text 2 + Text 3 + [/locale] leadtabs:1 +[/entry] +``` + +数值： + +```plaintext + Text 1 + Text 2 + Text 3 +``` + +### 内容替换 + +以下选项中可以使用`no<选项名称>`禁用该选项设定，比如`nosubstesc`。 + +- `substesc`：将内容中的`{{ESC}}`替换为终端ESC（ASCII Escape）字符（`\x1b`） + - **该选项仅适用于这些地方：**`header`段落中的`description`定义；`substrules`段落中的匹配和替换内容；`entries`中的字符串定义内容 + - 当该选项在`[/substitute_string]`或`[/substitute_regex]`语句后指定，会应用在匹配内容上 +- `substvar`：将内容中的变量名称引用替换成变量内容（详见[内容变量](./内容变量.md)） + - 当该选项在`[/substitute_string]`或`[/substitute_regex]`语句后指定，会应用在匹配内容上 + - 当该选项在`[/entry]`语句后指定，会应用在路径名称上 + +### 命令行输出替换 + +以下几个选项仅适用于`filter_command`或`[filter_commands]`语法： +- `strictcmdmatch`：用户输入的命令内容必须匹配命令匹配条件的开始（和默认的匹配参数不同）；比如说用户输入的`command --get-operation thing`在这个模式下会匹配到`command --get-operation thing --another`，但是不会匹配到`command --another thing --get-operation` +- `exactcmdmatch`：用户输入的命令必须与匹配条件完全相同；比如说用户输入的`command --get-operations --strict`会匹配到`command --get-operations --strict`，但是不会匹配到`command --get-operations` + - 带有此选项的命令匹配条件拥有最高的匹配规则执行优先级 +- `smartcmdmatch`：处理命令匹配条件时，把一个`-`开头的命令选项拆分成单个选项（e.g. `-rfc`处理时会被视为`-r -f -c`）；比如说用户输入的`rm -rf folder`会匹配到`rm -r`和`rm -f`，并且用户输入的`rm -r -f folder`会匹配到`rm -rf`。 + - 单个`-`之后的字符（无论字母和数字）都会被这样处理 + - 起始与多个横杠的语句（`--`）将不会被这样处理 +- `normalcmdmatch`：**默认设定；用于重置之前设定**；用户输入的命令中的语句需要包含匹配条件中的语句（e.g. `example-app --this --that`会匹配`example-app --that`匹配条件） +- `foregroundonly`：仅在进程为前台运行时应用这些替换规则。该选项适用于使用`clitheme-exec`执行shell等应用程序：通过大多数shell执行其他命令时，该shell会切换为后台运行（并且将执行的命令切换为前台）。这个选项可以防止输出误替换的问题，并且可以确保仅在shell的提示信息上应用有关的的替换规则。 + - 使用`noforegroundonly`以取消设定该选项 + - 你可以使用`clitheme-exec --debug-foreground`以在前台状态切换时获得提示信息 +--- +以下几个选项仅适用于`[substitute_string]`和`[substitute_regex]`语法： +- `subststdoutonly`：仅匹配standard output的输出内容 +- `subststderronly`：仅匹配standard error的输出内容 +- `substall`：**默认设定；用于重置之前设定**；匹配所有内容 +- `endmatchhere`，`noendmatchhere`：当遇到带有该选项的匹配规则时，不再继续应用其他的匹配规则 + - 使用`noendmatchhere`以取消设定 diff --git "a/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\244\232\350\241\214\345\206\205\345\256\271\346\256\265\350\220\275.md" "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\244\232\350\241\214\345\206\205\345\256\271\346\256\265\350\220\275.md" new file mode 100644 index 0000000000000000000000000000000000000000..9577518bfe8d1948cf536604edb22957f12e4190 --- /dev/null +++ "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\244\232\350\241\214\345\206\205\345\256\271\346\256\265\350\220\275.md" @@ -0,0 +1,87 @@ +# 多行内容段落 + +主题定义文件中的部分定义支持多行内容段落。它允许你在一个定义中包括拥有多个行数的字符串，或允许你定义带有空格的名称和项目。 + +如需定义多行内容段落段落，请在支持的定义名称中添加`[`和`]`（比如：`[locales]`, `[description]`），并且使用`[/]`结束段落（如`[/locales]`，`[/description]`。 + +## 各个段落中可用的多行内容段落 + +你可以在以下文章中找到对于每一个定义段落中，可以在哪些定义使用多行内容段落的信息： + +- `header`：[header段落](header段落.md) +- `substrules`：[命令行输出替换/编写定义文件](../命令行输出替换/1.%20编写定义文件.md) +- `entries`：[应用程序和字符串定义API/编写主题定义文件/多行内容段落](../应用程序和字符串定义API/编写主题定义文件/多行内容段落.md) +- `manpages`： [自定义manpage文档/编写定义文件](../自定义manpage文档/1.%20编写定义文件.md) + +## 在内容中输入结束语句 + +如果你想在多行内容段落中输入结束语句（如`[/locale]`等），请在语句前加上`\`符号，如`\[/locale]`等。该语句必须放在一行中的最前面才会被识别并处理，否则前面的`\`符号将不会在最终内容中移除。 + +```plaintext +[locale] default + Use + \[/locale] + To end the block + Using [/locale] + will also work +[/locale] +``` + +## 关于缩进/边缘空格的处理 + +**注意：** 多行内容段落中的结尾空格将会被忽略。 + +但是，起始空格和whitespace会被减去多行内容段落内容内的共同空格大小（tab符号将会被视为8个空格）。这意味着行数之间的缩进差距将会被保留。如果你想要在所有的行之前都加上一定大小的空格，你可以在结束语句之后添加`leadtabs:`或`leadspaces:`；前者会添加``个缩进（Tab）符号，后者会添加``个空格。 + +你也可以使用`set_options`来对之后定义的所有段落应用这些选项，如`set_options leadtabs:1`或`set_options leadspaces:4`。详细请见[可以设定的选项](./可以设定的选项.md)。 + +这意味着： + +```plaintext +[entry] entry1 + [locale] default + Text 1 + Text 2 + Text 3 + Text 4 + [/locale] +[/entry] +[entry] entry2 + [locale] default + Text 1 + Text 2 + Text 3 + [/locale] leadtabs:1 +[/entry] +[entry] entry3 + [locale] default +Text1 +Text2 + [/locale] +[/entry] +``` + +被读取时会返回以下内容： + +`entry1`： +```plaintext +Text 1 + Text 2 + Text 3 +Text 4 +``` + +`entry2`： + +```plaintext + Text 1 + Text 2 + Text 3 +``` + +`entry3`： + +```plaintext +Text1 +Text2 +``` \ No newline at end of file diff --git "a/\345\244\232\350\257\255\350\250\200\346\224\257\346\214\201.md" "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\244\232\350\257\255\350\250\200\346\224\257\346\214\201.md" similarity index 62% rename from "\345\244\232\350\257\255\350\250\200\346\224\257\346\214\201.md" rename to "\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\244\232\350\257\255\350\250\200\346\224\257\346\214\201.md" index 07e955cac10d41521e513690af58ce79b6cd9402..67218f06246e8d66e0e6c739d42db27b5d73b827 100644 --- "a/\345\244\232\350\257\255\350\250\200\346\224\257\346\214\201.md" +++ "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\345\244\232\350\257\255\350\250\200\346\224\257\346\214\201.md" @@ -8,7 +8,7 @@ clitheme的核心设计理念之一是对多语言的支持。它可以自动检 你可以在命令行中使用`locale`命令查看当前系统语言（Windows系统除外）。你可以参考输出中的`LANG`和`LANGUAGE`信息作为语言名称。 -``` +```plaintext $ locale LANG="en_US.UTF-8" LC_COLLATE="en_US.UTF-8" @@ -22,30 +22,43 @@ LC_ALL= ## 主题定义文件：为字符串定义添加多个语言版本 -你可以为一个字符串定于添加多个语言版本。`clitheme`会根据系统语言或者应用程序的语言设定自动选择相应的定义。 +你可以为一个字符串定义和命令行输出替换规则添加多个语言版本。`clitheme`会根据系统语言或者应用程序的语言设定自动选择相应的定义。 -关于更多信息，请参考[**编写主题定义文件/基本用法**](编写主题定义文件/基本用法.md)中的**使用`entry`段落**。 +关于更多信息，请参考[**应用程序和字符串定义API/编写主题定义文件/基本用法**](../应用程序和字符串定义API/编写主题定义文件/基本用法.md)中的**使用`entry`段落**。 -定义字符串时建议添加`default`语言。如果该字符串不支持当前的系统语言，会使用`default`语言定义。如果`default`语言没有被定义，只会在字符串支持当前系统语言的情况下调用该字符串。 +定义时建议添加`default`语言。如果该定义不支持当前的系统语言，会使用`default`语言定义。如果`default`语言没有被定义，只会在该定义支持当前系统语言的情况下才会被调用。 -在多行输入段落下，你可以同时定义多个语言，省去重复复制粘贴内容的过程。 +在多行内容段落段落下，你可以同时定义多个语言，省去重复复制粘贴内容的过程。 **注意：** 目前`clitheme`的自动语言检测不完全支持Windows系统，所以请务必定义`default`语言条目以确保主题定义在Windows系统下生效。 -``` -# ... -entry com.example example-app example-entry - locale default Your entry text here - locale en_US Your entry text here - locale zh_CN 你的定义文本 - # 或者使用多行输入（可以同时定义多个语言） - locale_block default en_US - Your entry text here - end_block - locale_block zh_CN - 你的定义文本 - end_block -end_entry +```plaintext +{entries_section} + # ... + [entry] com.example example-app example-entry + locale:default Your entry text here + locale:en_US Your entry text here + locale:zh_CN 你的定义文本 + # 或者使用多行内容段落（可以同时定义多个语言） + [locale] default en_US + Your entry text here + [/locale] + [locale] zh_CN + 你的定义文本 + [/locale] + [/entry] +{/entries_section} +{substrules_section} + # ... + [substitute_string] Some example output message + locale:default Output message! :) + locale:zh_CN 输出提示！o(≧v≦)o + # 同时定义default、C、和en_US语言 + [locale] default C en_US + Output message! :) + [/locale] + [/substitute_string] +{/substrules_section} ``` ## frontend模块：设定语言和禁用语言检测 @@ -80,6 +93,8 @@ f4=frontend.FetchDescriptor(disable_lang=True) - `$LANGUAGE`（多个语言将会被顺序读取，按照该顺序进行字符串定义获取操作） - `en_US`和`en`将会被忽略（详细请见[本文章](https://wiki.archlinuxcn.org/wiki/Locale#LANGUAGE：后备区域设置)） + - 如果变量中包含的`C`或`C.<编码>`，`clitheme`也会同时处理`en_US`、`en_US.<编码>`、`en`、`en.<编码>`等语言 + - `$LANG`设定为`C`时，**该变量将不会被读取** - `$LC_ALL` - `$LANG` diff --git "a/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\346\226\207\344\273\266\346\240\274\345\274\217\345\222\214\350\257\255\346\263\225.md" "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\346\226\207\344\273\266\346\240\274\345\274\217\345\222\214\350\257\255\346\263\225.md" new file mode 100644 index 0000000000000000000000000000000000000000..e2331c49bc5d8cf2b3c8a67005b238cf14ea9910 --- /dev/null +++ "b/\351\231\204\345\275\225\357\274\232\344\270\273\351\242\230\345\256\232\344\271\211\346\226\207\344\273\266\351\200\232\347\224\250\350\257\255\346\263\225/\346\226\207\344\273\266\346\240\274\345\274\217\345\222\214\350\257\255\346\263\225.md" @@ -0,0 +1,43 @@ +# 整体文件格式和语法 + +本文章介绍主题定义文件的整体文件格式和段落布局。 + +## 段落和内容 + +主题定义文件是按照段落来区分所对应的内容的。每一个段落对应着不同的功能，并且包含着不同的内容定义。每一个段落用`{<段落名称>_section}`和`{/<段落名称>_section}`来标记开始和结束。 + +每一个主题定义文件中都会包含`header`段落（`{header_section}`）。这个段落中包含了这个主题定义的一些基本信息，比如名称，详细介绍，版本，支持的应用程序等。它的作用是给用户提供更多有用的信息。详细请见[header段落](header段落.md)。 + +大概语法如下： + +```plaintext +{<名称>_section} + <内容定义> +{/<名称>_section} +# 更多像这样的定义 +``` + +**注意：** 文档中的文件语法示例会包含缩进。这只是为了提升定义的可读性而已；你不需要像这样子包含缩进。但是，为了可读性建议拥有包含缩进的好习惯。 + +## 注释 + +注释允许你在文件中添加附加的信息，让文件中的定义更加易懂。你可以使用`#`来标记它们；注释不会被处理或读取。比如： + +```plaintext +# this is a comment +``` + +**注意：** 注释只能在新的一行上定义。请不要在行的末尾定义注释。 + +```plaintext +# 错误用法： +{header_section} # Some comments here +``` + +## 文件扩展名 + +虽然`clitheme`在文件扩展名上没有要求，但是最好将文件的扩展名定义为`.clithemedef.txt`。这样子你可以更好的辨识文件，并且使用`.txt`会确保该文件会被系统使用正确的应用程序（如文本编辑器）打开。 + +## 文件内容编码 + +所有定义文件的内容必须使用 **`UTF-8`** 编码。这一点尤其在Windows系统上非常重要，因为有一些文本编辑器会使用系统默认的 **`GBK`** 编码保存文件。如果遇到内容乱码等情况，请尝试使用文本转换工具把文件转换成 **`UTF-8`** 编码。 \ No newline at end of file