文档
我们的 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