Vimscript 文档

由 Loen 创建， 最后一次修改 2016-02-24 我们的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不会尝试高亮或隐藏艺术字中的某些字符。写什么文档接下来通常是一个内容目录。不过，首先，让我们决定我们想要写的文档内容。在给一个新插件写文档时，我通常从下面的列表开始：IntroductionUsageMappingsConfigurationLicenseBugsContributingChangelogCredits如果这是一个大插件，需要一个"大纲"，我将写一个介绍段落来概括它的主要功能。 否则我会跳过它继续下一段。一个"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 forPotion files (files ending