helphelp.cnx

*helphelp.txt*   For Vim version 7.3.  最近更新: 2010年8月


		  VIM 参考手册    by Bram Moolenaar
				译者: Willis
				http://vimcdoc.sf.net


帮助文件之帮助						*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' 选项选择使用
			的语言。
			{Vi 无此功能}

						*{subject}* *E149* *E661*
:h[elp] {subject}	类似于 ":help"，但附加跳转到 {subject} 标签上。
			{subject} 可以包含 "*"、"?" 和 "[a-z]" 这样的通配符:
			   :help z?	跳到任何包含 "z" 的命令的帮助
			   :help z.	跳到关于 "z." 的帮助
			如果不能完全匹配该模式，或者有多个匹配，那就使用 "最
			好" 的匹配。这里，有一个相当复杂的算法来排定匹配的优先
			顺序。它的计算涉及到以下诸方面:
			- 大小写完全相同的优先于大小写不完全相同的。
			- 开始于非字母数字之后的优先于从单词中间开始的。
			- 位于或接近标签开始处的优先于离此距离较远的。
			- 匹配的字母数字字符越多越优先。
			- 匹配越短的越优先。

			如果该 {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
<
			要使用正规式 |pattern|，先 ":help"，然后在帮助窗口里使
			用 ":tag {pattern}"。这时，":tnext" 命令可以跳转到后一
			个匹配，"tselect" 列出所有的匹配并让你选择一个。 >
				:help index| :tse z.

<			如果没有参数，你会看到 "help" 的匹配而不是列出所有可能
			的匹配 (那会非常慢)。
			显示的匹配个数限于 300 个。

			该命令可以后面跟一个 '|' 并紧跟另外一个命令。不过，你
			不需要在 help 命令里转义 '|'。所以下面这些都没问题: >
				:help |
				:help k| only
<			注意 如果 '|' 之前有空格，它是 ":help" 参数的一部分。
			你也可以用 <LF> 或 <CR> 来分隔 help 命令和其后的命令。
			你需要先输入 CTRL-V，再输入 <LF> 或 <CR>。例如: >
				:help so<C-V><CR>only
<			{Vi 无此功能}

:h[elp]! [subject]	类似于 ":help"，但在非英语帮助文件里，先查找包含和当前
			文件相同语言的标签的文件。参见 |help-translated|。

							*:helpg* *:helpgrep*
:helpg[rep] {pattern}[@xx]
			搜索所有的帮助文本并给出一个匹配 {pattern} 行的列表。
			跳转到第一个匹配。
			可选的 [@xx] 指定只寻找 "xx" 语言里的匹配。
			你可以用 |quickfix| 命令来浏览其它的匹配。例如，
			|:cnext| 会跳到下一个。在 quickfix 窗口里，也可以用
			|:cwindow| 得到所有的匹配的列表。
			{pattern} 视为 Vim 的正规表达式 |pattern|。
			不使用 'ignorecase'，你可以加上 "\c" 来忽略大小写。
			大小写敏感的搜索示例: >
				:helpgrep Uganda
<			大小写不敏感的搜索示例: >
				:helpgrep uganda\c
<			寻找中文帮助的搜索: >
				:helpgrep backspace@cn
<			模式不支持换行符，必须在一行内匹配。为此，可用 |:grep|
			代替，但要得到帮助文件的列表就比较复杂了。
			后面不能跟其他的命令。其余部分都被当作模式的一部分。如
			果需要，可以用 |:execute|。
			不会在压缩的帮助文件里搜索 (Fedora 压缩帮助文件)。
			{Vi 无此功能}

							*:lh* *:lhelpgrep*
:lh[elpgrep] {pattern}[@xx]
			类似于 ":helpgrep"，除了使用位置列表代替 quickfix 列表
			之外。如果帮助窗口已经打开，使用该窗口的位置列表。不
			然，打开新帮助窗口，并设置该窗口的位置列表。当前窗口的
			位置列表不改变。

							*:exu* *:exusage*
:exu[sage]		显示 Ex 命令的帮助。目的是为了模拟对应的 Nvi 命令。
			{Vi 无此功能}

							*:viu* *:viusage*
:viu[sage]		显示普通命令的帮助。目的是为了模拟对应的 Nvi 命令。
			{Vi 无此功能}

如果不给出参数，|:help| 会打开 'helpfile' 选项指定的文件。否则，就会在
'runtimepath' 选项指定的多个路径中所有的 "doc/tags" 文件里查找所要求的标签。

帮助窗口的起始高度可以用 'helpheight' 选项来设置 (缺省是 20)。

标签用来跳转到指定的主题。有两种方法可以选择:
- 在命令或选项之上用 "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| 特性才有效}
			{Vi 无此功能}

					*:helpt* *:helptags*
				*E154* *E150* *E151* *E152* *E153* *E670*
:helpt[ags] [++t] {dir}
			为目录 {dir} 生成帮助标签文件 tags。它扫描该目录中所有
			的 "*.txt" 和 "*.??x" 文件中帮助标签定义。标签定义出现
			在星号之间。"*.??x" 文件是经过翻译的文件。它们相应产生
			"tags-??" 文件，参见 |help-translated|。所生成的标签文
			件经过排序。
			如果其中有重复项，会给出错误信息。
			直接覆盖已有的标签文件，不会有提示。
			可选的 "++t" 参数强制加入 "help-tags" 标签。如果 {dir}
			等于 $VIMRUNTIME/doc，也会这样做。
			例如，要重建运行时目录的帮助标签 (需要有相应写权限): >
				:helptags $VIMRUNTIME/doc
<			{Vi 无此功能}


==============================================================================
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" 就省略。

如果在一个非英语帮助文件里使用 |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 帮助文件的格式。如果你
在编写新帮助文件，最好从现有的文件复制一份作为模板。

帮助文件的首行的格式应该是这样的:

*helpfile_name.txt*	For Vim version 7.3	Last change: 2010 June 4

第一个字段是指向帮助文件名的链接。第二个字段描述所适用的 Vim 版本。最后一个字
段给出该文件的最后修改日期。字段之间用制表符分隔。

在帮助文件的底部放上 Vim 的模式行，它设置 'textwidth'、'tabstop' 选项，并把
'filetype' 设为 'help'。请不要在 modeline 上设置全局选项，否则读取帮助的用户会
有不希望的后果。


标 签

要定义帮助标签，把名字放在星号之间 (*标签名*)。标签名应该和所有 Vim 帮助标签名
不同，最好以 Vim 插件名开头。标签名通常行右对齐。

要引用已有帮助标签并建立一个热链，把名字放在竖线 (|) 之间，如 |help-writing|。

要在帮助文件里引用 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

 vim:tw=78:ts=8:ft=help:norl: