文档

我们的 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 不会高亮或隐藏艺术字中的字符。

什么需要写进文档

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

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

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

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

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

“许可”段落应该指明插件代码使用的是什么许可,以及一个能查看许可全部内容的 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 技能为当前缓冲创建一个映射来切换 helptext 文件类型,这会很有用。

记住,所有原始的 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