文档

我们的 Potion 插件中有很多有用的功能，但并不是对任何人都真的有用， 我们需要编写良好的文档，这样他们才能知道它能做什么！

Vim 本身的文档是非常棒的。它没有过度冗长，但确十分缜密。 这也鼓励很多插件作者认真地编写文档，并使 Vimscript 社区形成了一种编写强健文档的良好习惯。

文档如何工作

当阅读一个 Vim 的 :help 主题时，你肯定会注意到有些内容会高亮显示，明显不同于其他的。 让我们看看这是如何工作的。

打开任意一个帮助主题（例如 :help help）并运行 :set filetype?。Vim 会显示 filetype=help。 现在运行 :set filetype=text，会看到高亮消失了。再次 :set filetype=help，又会变回来。

这说明 Vim 帮助文件只是和其他类型的文件一样会把文本语法高亮！ 这意味着你可以自己写代码来达到同样的效果。

在插件仓库中创建一个名为 doc/potion.txt 的文件。 当 Vim/Pathogen 构建帮助主题时，会在 doc 目录中寻找这些文件， 所以我们会在这个文件中为我们的插件编写帮助文档。

在 Vim 中打开这个文件，并运行 :set filetype=help，这样就能在输入的时候就看到语法高亮了。

帮助文档头部

帮助文件的格式完全取决于个人喜好。照这种说法，我会讲一种在现代 Vimscript 社区非常流行的组织方式。

文件的第一行应该包含它的文件名，紧接着是描述这个插件是做什么的一句话。 potion.txt 文件的第一行如下：

*potion.txt* functionality for the potion programming language

在帮助文件中，用星号把单词包裹起来会创建一个“标签”，它能用于跳转。 运行 :Helptags，告诉 Pathogen 重新构建帮助标签的索引，然后打开一个新的 Vim 窗口，并运行 :help potion.txt。 Vim 会打开你的帮助文档，就和其他的一样。

下一步，你应该添加一段长长的描述，并把插件名包裹起来。 有些作者（包括我）喜欢一些有意思的东西，我们会使用一些 ASCII 艺术字来使它们看起来有趣些。 在 potion.txt 文件中添加上非常棒的标题：

*potion.txt* functionality for the potion programming language

                      ___      _   _              ~
                     / _ \___ | |_(_) ___  _ __   ~
                    / /_)/ _ \| __| |/ _ \| '_ \  ~
                   / ___/ (_) | |_| | (_) | | | | ~
                   \/    \___/ \__|_|\___/|_| |_| ~

          Functionality for the Potion programming language.
        Includes syntax highlighting, code folding, and more!

我通过运行 figlet -f ogre "Potion" 命令获得这些有趣的文字。 figlet 是一个非常棒的用来生成 ASCII 艺术字的小程序。 每行结尾处的 ~ 字符让 Vim 不会高亮或隐藏艺术字中的字符。

什么需要写进文档

再下一步通常是一个目录表。但首先，我们需要决定想把什么写进文档。

在为一个新插件编写文档时，我通常从以下段落列表开始：

• 介绍（Introduction）
• 用法（Usage）
• 映射（Mappings）
• 配置（Configuration）
• 许可（License）
• 漏洞（Bugs）
• 贡献（Contributing）
• 更新日志（Changelog）
• 授信（Credits）

如果插件很大而且需要“概要”，我就会写一段介绍，简要说明它是如何工作的。否则，就直接跳过。

“用法”段落通常来说应该解释用户应该如何使用你的插件。 如果需要通过映射来交互，那就告诉他们。 如果并没有很多映射，可以直接在这里列出来，否则，你会想单独写一个“映射”段落来把它们都列出来。

“配置”段落应该把所有用户可以修改的变量都列出来，并且附上各自的作用和默认值。

“许可”段落应该指明插件代码使用的是什么许可，以及一个能查看许可全部内容的 URL。 不要把全部的内容都放进帮助文件中 —— 大部分用户都知道常用的许可表示什么意思， 否则只会乱成一团。

"漏洞"段落应该简短、友好。把所有已知但还未修复的重大漏洞都列出来， 并告诉用户如何把新发现的漏洞报告给你。

如果你想让用户为插件贡献漏洞修复和新功能，那他们得知道如何操作。 他们是应该在 GitHub 上发送一个合并请求？还是在 Bitbucket 上？亦或是通过邮件发送一个补丁？ 以上任意一种还是全部？添加一个“贡献”段落能让别人清楚你想要如何接收代码。

包含更新日志是个非常有意义的事，这样，当用户从版本 X 升级到了版本 Y 时，他们才能立即知道改了些什么。 另外，我强烈建议选用一个健全的版本管理方案，例如 Semantic Versioning，并坚持用下去。 你的用户会感谢你的。

最后，我喜欢添加一个“授信”段落，并提及我的名字，列出借鉴过的其他插件，感谢贡献者，诸如此类。

这通常是个不错的开始。但对于更独特的插件来说，也许会觉得不用依照这个列表，那也是完全没问题的。 并没有什么强制和严格的规则，除了以下几点：

• 要全面。
• 不要太冗长。
• 让用户享受从对你的插件一无所知到成为一个专家的过程。

目录表

既然我们已经知道了需要包含哪些段落，那把以下内容添加到 potion.txt 文件中：

====================================================================
CONTENTS                                            *PotionContents*

    1. Usage ................ |PotionUsage|
    2. Mappings ............. |PotionMappings|
    3. License .............. |PotionLicense|
    4. Bugs ................. |PotionBugs|
    5. Contributing ......... |PotionContributing|
    6. Changelog ............ |PotionChangelog|
    7. Credits .............. |PotionCredits|

这里有一些需要注意的东西。首先，= 字符的行会被语法高亮。 你可以用这种行来可视化分割帮助文档的段落。 如果需要，你也可以用 - 字符的行来分割分段落。

*PotionContents* 会创建另一个标签，这样用户可以键入 :help PotionContents 来直接跳转到目录表这里。

每个被 | 字符包裹的单词都会创建一个指向标签的链接。 用户可以把光标放置在帮助文件中的这些单词上，然后按下 <c-]> 跳转到标签处，就和键入了 :help TheTag 一样。 用户也可以通过鼠标来点击。

Vim 会隐藏 * 和 | 字符，并且把它们语法高亮，所以最终看到的是一个非常美观的目录表， 用户可以使用它来查找想要的东西。

段落

你可以像这样创建段落头部：

====================================================================
Section 1: Usage                                       *PotionUsage*

This plugin with automatically provide syntax highlighting for
Potion files (files ending in .pn).

It also...

务必正确使用 * 字符来创建标签，这样所有目录表中的链接才能正常工作。

继续为目录表中的每个段落创建头部。

例子

我可以尝试着把所有帮助文件的语法都讲一遍，以及如何使用它们，但这只关乎个人喜好问题。 因此，我会列给你们一些有非常全面文档的 Vim 插件。

对于每一个插件，把它的原始文档复制到一个 Vim 缓冲中，然后把文件类型设置为 help，看看它是如何渲染的。 如果想看看某个效果是如何生成的，就切换回 text。

用你学到的 Vimscript 技能为当前缓冲创建一个映射来切换 help 和 text 文件类型，这会很有用。

• Clam，我自己的插件，用来运行 shell 命令。这是个非常短小的例子，但是包含了之前讲的大部分段落。
• NERD tree，Scrooloose 写的文件导航插件。 注意查看总体结构，以及他是如何在一个易于阅读的列表里概述映射，并在后面进行详细介绍的。
• Surround，Tim Pope 写的插件，用来处理“包围”字符。 注意它缺少了目录表，并有着不同样式的段落头部，以及表格列的头部。 理解这些内容是如何实现的，并想想你是否喜欢这样。这完全是个人喜好问题。
• Splice，我自己的插件，用来解决版本控制系统中的三向合并冲突。 注意映射的列表是如何格式化的，以及我是如何用 ASCII 艺术图表来解释布局的。 有时一张实实在在的图胜过千言万语。

记住，所有原始的 Vim 文档也能用作参考。它们有大量的东西供你学习和研究。

写吧！

既然已经看过了其他插件是如何组织和编写文档的，那就开始填写 Potion 插件文档中的段落吧。

如果你没有写过技术文档，这可能会是个挑战。 学习去写确实不是个简单的事，但和其他任何技术一样，肯定是需要练习的，所以赶紧开始吧！ 目前并不需要很完美，你可以在以后随时改进它。

如果写了一些不完全确定的东西也不用担心，先把它放在一边，以后再去重新写它。 通常只要有些东西在缓冲中就能激发你的写作欲望。 如果你想要把一些东西找回来，它们都会在版本控制中。

假设你有个朋友也使用 Vim 并坐在旁边会是个不错的开始。 他们从来没用过你的插件，却很感兴趣，而你的目标就是让他们成为使用它的专家。 在指定一个不错的用来解释如何工作的概要之前，要思考如何对他人解释清楚， 这能帮助你脚踏实地并避免过于深入于技术。

如果你仍然感到困惑，并觉得还没有准备好挑战为一个完整插件编写文档，那就先从一些更小的事情开始。 在 ~/.vimrc 文件中挑选一个映射，然后在注释中为它编写完整的文档。 解释它是用来干什么的、如何使用它、以及它是如何工作的。 例如，下面是我自己的 ~/.vimrc 文件：

" "Uppercase word" mapping.
"
" This mapping allows you to press <c-u> in insert mode to convert the
" current word to uppercase.  It's handy when you're writing names of
" constants and don't want to use Capslock.
"
" To use it you type the name of the constant in lowercase.  While
" your cursor is at the end of the word, press <c-u> to uppercase it,
" and then continue happily on your way:
"
"                            cursor
"                            v
"     max_connections_allowed|
"     <c-u>
"     MAX_CONNECTIONS_ALLOWED|
"                            ^
"                            cursor
"
" It works by exiting out of insert mode, recording the current cursor
" location in the z mark, using gUiw to uppercase inside the current
" word, moving back to the z mark, and entering insert mode again.
"
" Note that this will overwrite the contents of the z mark.  I never
" use it, but if you do you'll probably want to use another mark.
inoremap <C-u> <esc>mzgUiw`za

这比为完整的插件编写文档短多了，但确是个不错的练习，能帮助你练习编写文档。 如果你把它放到 Bitbucket 或 GitHub 上，对其他阅读你的 ~/.vimrc 的人也是非常有帮助的。

练习

为 Potion 插件的每个段落编写文档。

阅读 :help help-writing 来获得关于编写帮助文档的帮助。

阅读 :help :left，:help :right，和 :help :center 来学习这三个有用的命令，它们可以使 ASCII 艺术字更加完美。

原文地址：http://learnvimscriptthehardway.stevelosh.com/chapters/54.html