helphelp

helphelp.txt 适用于 Vim 9.0 版本。 最近更新: 2022年7月 VIM 参考手册 by Bram Moolenaar 译者: Willis 帮助文件之帮助 helphelp 1. 帮助命令 online-help 2. 翻译帮助文件 help-translated 3. 编写帮助文件 help-writing

1. 帮助命令 online-help

help <Help> :h :help <F1> i_<F1> i_<Help> <Help> 或 :h[elp] 打开一个窗口并以只读方式显示帮助文件。如果已经打开了一 个帮助窗口,就继续使用那个窗口。不然,如果当前窗口占据 了屏幕的完整宽度或者至少有 80 个字符宽,帮助窗口会出现 在当前窗口的正上方。再不然,新窗口就开在最上方。 如果主帮助文件有多个语言版本,'helplang' 选项选择使用 的语言。 {subject} E149 E661 :h[elp] {subject} 类似于 ":help",但附加跳转到 {subject} 标签上。 例如: :help options {subject} 可以包含 "*"、"?" 和 "[a-z]" 这样的通配符: :help z? 跳到任何包含 "z" 的命令的帮助 :help z. 跳到关于 "z." 的帮助 但如果标签存在,按本义接受: :help :? jump to help for ":?" 如果不能完全匹配该模式,或者有多个匹配,那就使用 "最 好" 的匹配。这里,有一个相当复杂的算法来排定匹配的优先 顺序。它的计算涉及到以下诸方面: - 大小写完全相同的优先于大小写不完全相同的。 - 开始于非字母数字之后的优先于从单词中间开始的。 - 位于或接近标签开始处的优先于离此距离较远的。 - 匹配的字母数字字符越多越优先。 - 匹配越短的越优先。 如果该 {subject} 有多个语言的帮助,'helplang' 选项用来 选择所用的语言。要找到某个标签某个特定的语言版本,附加 上 "@ab",其中 "ab" 是双字母的语言代码。参见 help-translated注意 给出越长的 {subect},找到的匹配就越少。通过使用命 令行补全功能 (在 ":help subject" 之后输入 CTRL-D c_CTRL-D ) 可以帮助你了解这是如何工作的。 如果有多个匹配,你可以通过敲击 CTRL-D 得到匹配的列表。 例如: :help cont<Ctrl-D> 要找寻 CTRL-V 的帮助不需要打 ":help CTRL-V",可用: :help ^V 这也适用于和其它字符混用的情况。例如寻找 CTRL-V 在插入 模式的帮助: :help i^V 也可以先 ":help",然后在帮助窗口里 ":tag {pattern}"。 此时可用 ":tnext" 命令跳转到后一个匹配,"tselect" 列出 所有的匹配并让你选择一个。 :help index :tselect /.*mode 如果没有参数,你会看到 "help" 的匹配而不是列出所有可能 的匹配 (那会非常慢)。 显示的匹配个数限于 300 个。 :help 命令可以后跟 '|' 并紧跟另外一个命令。不过,你 不需要在 help 命令里转义 '|'。所以下面这些都没问题: :help | :help k| only 注意 '|' 之前的空格视为 ":help" 参数的一部分。 (译者注: 前者查找 | 的帮助,后者查找 k 的帮助并执行 only 命令使帮助窗口成为唯一窗口) 也可用 <NL><CR> 来分隔 help 命令和其后的命令。你需 要先输入 CTRL-V,再输入 <NL><CR>。例如: :help so<C-V><CR>only :h[elp]! [subject] 类似于 ":help",但在非英语帮助文件里,优先查找和当前文 件相同语言的文件中的标签。参见 help-translated :helpc :helpclose :helpc[lose] 如果有的话,关闭一个帮助窗口。 Vim 会试图恢复打开帮助窗口之前原先的窗口布局 (包括光标 位置)。这可能会触发若干自动命令。 :helpg :helpgrep :helpg[rep] {pattern}[@xx] 搜索所有的帮助文本并给出匹配 {pattern} 行的列表。跳转 到第一个匹配。 可选的 [@xx] 指定只寻找 "xx" 语言里的匹配。 你可以用 quickfix 命令来浏览其它的匹配。例如, :cnext 会跳到下一个匹配。从快速修复窗口里也可用 :cwindow 得到所有匹配的列表。 {pattern} 为 Vim 正则表达式 pattern 。 不使用 'ignorecase',你可以加上 "\c" 来忽略大小写。 大小写敏感的搜索示例: :helpgrep Uganda 大小写不敏感的搜索示例: :helpgrep uganda\c 寻找中文帮助的搜索: :helpgrep backspace@cn 模式不支持换行符,必须在一行内匹配。否则可用 :grep 代替,但要得到帮助文件的列表就比较复杂了。 后面不能跟其他的命令。其余部分都被当作模式的一部分。如 果需要,可以用 :execute 。 不会在压缩的帮助文件里搜索 (Fedora 会压缩帮助文件)。 :lh :lhelpgrep :lh[elpgrep] {pattern}[@xx] 类似于 ":helpgrep",但使用位置列表代替快速修复列表。如 果帮助窗口已经打开,使用该窗口的位置列表。不然,打开新 帮助窗口,并设置该窗口的位置列表。此时不改变当前窗口的 位置列表。 :exu :exusage :exu[sage] 显示 Ex 命令的帮助。目的是为了模拟对应的 Nvi 命令。 :viu :viusage :viu[sage] 显示普通命令的帮助。目的是为了模拟对应的 Nvi 命令。 没有给出参数时, :help 会打开 'helpfile' 选项指定的文件。否则,在所有 'runtimepath' 选项指定目录中的 "doc/tags" 文件里查找所要求的标签。 要在当前窗口打开帮助,见以下技巧: help-curwin 。 可用 'helpheight' 选项来设置帮助窗口的起始高度 (缺省是 20)。 help-buffer-options 创建帮助缓冲区时,设置若干局部选项以确保帮助文本以期待的方式显示: 'iskeyword' 几乎所有 ASCII 字符,除了 ' '、'*'、'"' 和 '|' 'foldmethod' "manual" 'tabstop' 8 'arabic' 关闭 'binary' 关闭 'buflisted' 关闭 'cursorbind' 关闭 'diff' 关闭 'foldenable' 关闭 'list' 关闭 'modifiable' 关闭 'number' 关闭 'relativenumber' 关闭 'rightleft' 关闭 'scrollbind' 关闭 'spell' 关闭 标签用来跳转到指定的主题。有两种方法: - 在命令或选项之上用 "CTRL-]" 命令。只有标签是关键字 (见 'iskeyword') 时才行。 "<C-Leftmouse>" 和 "g<LeftMouse>" 等价于 "CTRL-]"。 - 用 ":ta {subject}" 命令。也适用于包含非关键字字符的标签。 用 CTRL-T 或者 CTRL-O 跳回来。 用 ":q" 关闭帮助窗口。 如果查找的项目有多个可能匹配,可以这样依次跳转到每个匹配: 1. 先打开帮助窗口。 2. 用 ":tag" 命令,在标签前加上斜杠。例如: :tag /min 3. 用 ":tnext" 跳转到下一个匹配的标签。 可以为插件或其他项目增加帮助文件。为此不需要修改发布的帮助文件。见 add-local-help 。 关于如何写本地的帮助文件,见 write-local-help注意: 本地帮助文件的标题行会自动列在帮助文件 "help.txt" 的 "LOCAL ADDITIONS" 一节 local-additions 。只有在 Vim 里实际察看该文件才会这么做,该文件本身并没 有被修改。这是通过动态地遍历所有帮助文件并提取每个文件的首行来完成的。其中,跳 过 $VIMRUNTINE/doc 里的文件。 (译者注: 目前,即使使用经过翻译的帮助,本地帮助文件只能在英文的 help.txt 里看 到。用 :help@en 访问。) help-xterm-window 如果你想在另外一个 xterm 窗口里察看帮助,可以用如下的命令: :!xterm -e vim +help & :helpfind :helpf :helpf[ind] 和 :help 类似,但用一个对话框来提示输入参数。 这只是为了向后兼容的需要。它现在执行 ToolBar.FindHelp 菜单项而不是内建的对话框。 {仅当编译时加入 +GUI_GTK 特性才有效} :helpt :helptags E150 E151 E152 E153 E154 E670 :helpt[ags] [++t] {dir} 为目录 {dir} 生成帮助标签文件 tags。{dir} 为 ALL 时, 使用 'runtimepath' 的所有 "doc" 目录。 扫描该目录及其子目录中所有的 "*.txt" 和 "*.??x" 文件中 帮助标签定义。标签定义出现在星号之间。"*.??x" 文件是经 过翻译的文件。它们相应产生 "tags-??" 文件,参见 help-translated 。所生成的标签文件经过排序。 如果其中有重复项,会给出错误信息。 直接覆盖已有的标签文件,不会有提示。 可选的 "++t" 参数强制加入 "help-tags" 标签。如果 {dir} 等于 $VIMRUNTIME/doc,也会这样做。 例如,要重建运行时目录的帮助标签 (需要有相应写权限): :helptags $VIMRUNTIME/doc

2. 翻 译 帮 助 文 件 help-translated

除了原始的英语帮助文件外,我们可以添加其他语言的翻译版本。Vim 会在所有 'runtimepath' 的目录的 "doc" 子目录里查找帮助文件。这只有在编译时加入 +multi_lang 特性才会有效。 目前,有以下的翻译可用: 中文 - 多位作者 法语 - David Blanchet 翻译 意大利语 - Antonio Colombo 翻译 日文 - 多位作者 波兰语 - Mikolaj Machowski 翻译 俄罗斯语 - Vassily Ragosin 翻译 在 Vim 网页上可以找到这些翻译: http://www.vim.org/translations.php 帮助文件的翻译版本包含如下文件: help.abx howto.abx ... tags-ab "ab" 是一个双字母的语言代码。这样,中文的文件名是: help.cnx howto.cnx ... tags-cn 'helplang' 选项设置若干语言偏好。 缺省值根据当前环境设置。Vim 会先在偏好的语言 里查找匹配的标签。如果没有,就使用英语版本。 要查找某一特定的语言的标签,在标签后面加上 "@ab",其中的 "ab" 是两字节的语言代 码。示例: :he user-manual@cn :he user-manual@en 前者查找中文的用户手册,即使 'helplang' 为空。后者查找英语用户手册,即使 'helplang' 设置为 "cn"。 ":help" 的命令行补全只会在有多个语言版本的标签时显示 "@en" 后缀。如果只有英语 版本,"@en" 就省略。如果首个候选有 "@ab" 后缀而该后缀匹配 'helplang' 的首选语 言,则 "@ab" 也被省略。 如果在一个非英语帮助文件里使用 CTRL-] 或者 ":help!",Vim 会先找相同语言的标 签。如果没有,再根据 'helplang' 选择语言。 Help 文件一定要使用 latin1 或 utf-8 编码。Vim 如果发现首行有非 ASCII 的字符, 就假设是 utf-8 编码。所以,你至少要翻译头部的 "For Vim version"。 同一个目录里相同语言的帮助文件必须使用相同的编码。不同语言或者相同语言但在不同 的目录下可以使用不同的编码。 为译者的提示: - 不要翻译标签本身。这样才能用 'helplang' 来指定语言偏好。你可以在自己的语言里 加入新的标签。 - 如果不想翻译文件的部分内容,用 "tag@en" 的形式标记英语版本的标签。 - 生成一个包,包含所有的帮助和和标签文件,以便下载。用户把它解开到某个 "doc" 目录下就可以开始使用了。请告知 Bram,他可以在 www.vim.org 上给加一个链接。 - 用 :helptags 命令生成标签文件 tags。该命令会在指定目录下找到所有语言的版 本。

3. 编 写 帮 助 文 件 help-writing

为了方便使用,为插件编写的 Vim 帮助文件应该遵循标准 Vim 帮助文件的格式,首行除 外。如果你在编写新帮助文件,最好从现有的文件复制一份作为模板。 帮助文件的首行的格式应该是这样的: plugin_name.txt {插件的简单描述} 第一个字段是 ":help plugin_name" 会跳转到的帮助标签。在制表符之后的此行其余部 分简短描述插件的目的。它会显示在主帮助文件的 "LOCAL ADDITIONS" 小节下。现在要 检查一下,可跳转到: local-additions 。 如果需要版本号或最后修改日期,放在第二行并右对齐。 在帮助文件的底部放上 Vim 的模式行,它设置 'textwidth''tabstop' 选项,并把 'filetype' 设为 "help"。请不要在模式行上设置全局选项,否则会有不希望的后果。 标 签 要定义帮助标签,把名字放在星号之间 (*标签名*)。标签名应该和所有 Vim 帮助标签名 不同,最好以 Vim 插件名开头。标签名通常行右对齐。 要引用已有帮助标签并建立一个热链,把名字放在竖线 (|) 之间,如 help-writing 。 要引用 Vim 命令并建立一个热链,把名字放在反引号之间,例如 :filetype 里。可见 它以命令形式高亮,如同代码块那样 (见下)。 要在帮助文件里引用 Vim 选项,可以把选项名在单引号之间,如 'statusline'。 高 亮 要定义栏标题,在行尾加上波浪符。栏标题会使用不同颜色的高亮。例如 栏标题 要分隔同一帮助文件的不同小节,加上一行从首列开始的 '=' 字符序列。小节分隔行会 使用不同的高亮。 要不加修饰地引用一段 ex 命令块,在块之前的那行最后加上一个大于号 (>) 字符,然 后在块之后的那行放上一个小于号 (<) 字符作为该行的第一个非空白字符。任何从第一 列开始的行也会隐含地结束之前的 ex 命令块。例如 function Example_Func() echo "Example" endfunction 以下内容在 Vim 帮助文件中采用不同的高亮: - 使用 <> 记号的特殊键名,如 <PageDown>,或 Ctrl 字符,如 CTRL-X - 任何 {花括号} 之间的内容,如 {lhs}{rhs} "Note","Notes" 和类似的单词会神奇地自动得到独特的高亮,下面的也是: *Todo something to do *Error something wrong 具体细节可见 $VIMRUNTIME/syntax/help.vim inclusion Vim 目标是服务所有人,不论种族、性别或其它。有些人很在意用户指称使用了 "他" 或 "他的",认为我们假定用户是男性。事实不是如此,这只是写帮助文本时的一种习惯,且 已沿习多年。另外,大量文本由英语不是第一语言的贡献者编写。不管行文如何,我们都 没有关于用户性别的任何假定。有些人建议使用 "他们" (译者注: 英语该词是中性的), 但这不是常规英语。我们也不想花时间在这方面的讨论上。我们的目标是帮助读者理解 Vim 如何工作,准确的措词是第二位的。 vim:tw=78:ts=8:noet:ft=help:norl: