Vimscript 文档
我们的Potion插件有着许多有用的功能，但是无人知晓这一点，除非我们留下了文档！
Vim自身的文档非常棒。它不仅是详细地，而且也是非常透彻的。 同时，它也启发了许多插件作者写出很好的插件文档，结果是在Vimscript社区里营造出强大的文档文化。
如何使用文档
当你阅读Vim里的:help条目时，你显然注意到了有些内容被高亮得跟别的不一样。 让我们看一下这是怎么回事。
打开任何帮助条目(比如:help help)并执行:set filetype?。Vim显示filetype=help。 现在执行:set filetype=text，你将看到高亮消失了。 再次执行:set filetype=help，高亮又回来了。
这表明Vim帮助文件只是获得了语法高亮的文本文件，一如其他的文件格式！ 这意味着你可以照着写并获得同样的高亮。
在你的插件repo中创建名为doc/potion.txt文件。 Vim/Pathogen在索引帮助条目时查找在doc文件夹下的文件，所以我们在此写下插件的帮助文档。
用Vim打开这个文件并执行:set filetype=help，这样你在输入的时候就可以看到语法高亮。
帮助的题头
帮助文件的格式是一个取决于个人品味的问题。 尽管这么说，我还是讲讲一种在当前的Vimscript社区逐渐被广泛使用的文档格式。
文件的第一行应该包括帮助文件的文件名，接下来是一行对插件功能的描述。 在你的potion.txt文件的第一行加上下面的内容：
*potion.txt* functionality for the potion programming language在帮助文件中用星号括起一个词创建了一个可以用于跳转的"tag"。 执行:Helptags来让Pathogen重新索引帮助tags，接着打开一个新的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是一个好玩的小程序，可以生成ACSII艺术字。 每一行结尾的~字符保证Vim不会尝试高亮或隐藏艺术字中的某些字符。
写什么文档
接下来通常是一个内容目录。不过，首先，让我们决定我们想要写的文档内容。
在给一个新插件写文档时，我通常从下面的列表开始：
- Introduction
- Usage
- Mappings
- Configuration
- License
- Bugs
- Contributing
- Changelog
- Credits
如果这是一个大插件，需要一个"大纲"，我将写一个介绍段落来概括它的主要功能。 否则我会跳过它继续下一段。
一个"usage"段落应该解释，大体上用户将怎样_使用_你的插件。如果他们需要通过映射进行交互，告诉他们。 如果映射数目不是很多，你可以简单地在这里列出来，否则你可能需要创建一个单独的"mappings"段落来一一列出。
"configuration"段落应该详尽列出用户可以自定义的变量，以及它们的功能和默认值。
"license"段落应该指出插件代码所用的协议，连同一个指向协议完整文本的URL。 不要把整份协议放入帮助文件 -- 大多数用户知道这些常用的协议是什么意思，这样做只会徒增混乱。
"bugs"段落应该尽可能短小。列出所有你已知却尚未解决的主要的bugs，并告知用户如何向你报告他们抓到的新bug。
如果你希望你的用户可以向项目奉献bug fixes和features，他们需要怎么做。 应该把pull request发到GitHub呢？还是Bitbucket?要用email寄补丁吗？ 要选择其中的一个还是全都得要？一个"contributing"段落可以清楚地表明你想要接受代码的方式。
一个changlog也是值得包含在内的，这样当用户从版本X更新到版本Y时，他们立即可以看到什么改变了。 此外，我强烈推荐你为你的插件使用一个合理的版本号计划，比如Semantic Versioning，并一直坚持。 你的用户会感谢你的。
最后，我喜欢加入一个"credits"段落来留下自己的大名，列出影响该插件创作的其他插件，感谢奉献者，等等。
这样我们就有一个成功的开始了。对于许多特殊的插件，你可能觉得需要不这么做，那也没问题。 你仅需追随下面几条规则：
- 透彻明了
- 不要废话
- 带领你的用户漫步于你的插件，从一无所知到了如指掌。
内容目录
既然我们已经了解了应该要有的段落，把下面内容加入到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*将创建另一个tag，这样用户可以输入:help PotionContents来直接跳到内容目录。
用|包起每一个词将创建一个跳转到tag的链接。 用户可以把他们的光标移到词上并按下<c-]>跳转到对应tag，就像他们输入:help TheTag一样。 他们也可以用鼠标点开。
Vim将隐藏*和|并高亮其间的内容，所以用户将会看到一个整洁漂亮的目录，以便于跳到感兴趣的地方。
段落
你可以像这样创建一个段头：
====================================================================
Section 1: Usage *PotionUsage*
This plugin with automatically provide syntax highlighting for
Potion files (files ending in .pn).
It also...确保对*围起的内容创建了正确的tags，这样你的目录的链接才能正常工作。
继续并为目录中每一部分创建段头。
例子
我可以讲述所有的帮助文件语法和怎样使用它们，但我不喜欢这样。 所以，不如我给你一系列不同类型的Vim插件文档作为例子。
对于每个例子，复制文档源代码到一个Vim缓冲区并设置它的filetype为help来观察它的渲染。 如果你想比较每个渲染效果，切回text看看。
你也许需要使用你的Vimscript技能为当前缓冲区创建一个切换于help和text的映射。
- Clam，我自己用来写shell命令的插件。这是一个很小的范例，满足了我前面讲过的大多数内容。
- NERD tree，Scrooloose写的一个文件浏览插件。 注意大体结构，还有他如何在详尽解释每一项之前，总结出一个易读的列表。
- Surround，Tim Pope写的一个处理环绕字符的插件。 注意到它没有目录，以及不同的段头风格和表格列项(table column headers)。 弄懂他是怎么做到的，并想想你是否喜欢这种风格。这是个人风格问题啦。
- Splice，我自己用来解决版本控制中three-way merge conflict的插件。 注意映射列表的排版方式，以及我怎样使用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它比一个完整插件的文档短很多，却是一个练习写作的好练习。 如果你把~/.vimrc放到Bitbucket或GitHub，别人也更容易理解。
练习
给Potion插件每一部分写下文档。
阅读:help help-writing来帮助你写帮助文档。
阅读:help :left, :help :right,和:help :center来学习三个有用的命令使得你的ASCII艺术字更好看。
