我們的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](http://www.figlet.org/)是一個好玩的小程序,可以生成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](http://semver.org/),并一直堅持。 你的用戶會感謝你的。
最后,我喜歡加入一個"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](https://github.com/sjl/clam.vim/blob/master/doc/clam.txt),我自己用來寫shell命令的插件。這是一個很小的范例,滿足了我前面講過的大多數內容。
* [NERD tree](https://github.com/scrooloose/nerdtree/blob/master/doc/NERD_tree.txt),Scrooloose寫的一個文件瀏覽插件。 注意大體結構,還有他如何在詳盡解釋每一項之前,總結出一個易讀的列表。
* [Surround](https://github.com/tpope/vim-surround/blob/master/doc/surround.txt),Tim Pope寫的一個處理環繞字符的插件。 注意到它沒有目錄,以及不同的段頭風格和表格列項(table column headers)。 弄懂他是怎么做到的,并想想你是否喜歡這種風格。這是個人風格問題啦。
* [Splice](https://github.com/sjl/splice.vim/blob/master/doc/splice.txt),我自己用來解決版本控制中[three-way merge conflict](http://en.wikipedia.org/wiki/Merge_(revision_control)#Three-way_merge)的插件。 注意映射列表的排版方式,以及我怎樣使用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藝術字更好看。
- 前言
- 鳴謝
- 預備知識
- 打印信息
- 設置選項
- 基本映射
- 模式映射
- 精確映射
- Leaders
- 編輯你的Vimrc文件
- Abbreviations
- 更多的Mappings
- 鍛煉你的手指
- 本地緩沖區的選項設置和映射
- 自動命令
- 本地緩沖區縮寫
- 自動命令組
- Operator-Pending映射
- 更多Operator-Pending映射
- 狀態條
- 負責任的編碼
- 變量
- 變量作用域
- 條件語句
- 比較
- 函數
- 函數參數
- 數字
- 字符串
- 字符串函數
- Execute命令
- Normal命令
- 執行normal!
- 基本的正則表達式
- 實例研究:Grep 運算符(Operator),第一部分
- 實例研究:Grep運算符(Operator),第二部分
- 實例研究:Grep運算符(Operator),第三部分
- 列表
- 循環
- 字典
- 切換
- 函數式編程
- 路徑
- 創建一個完整的插件
- 舊社會下的插件配置方式
- 新希望:用Pathogen配置插件
- 檢測文件類型
- 基本語法高亮
- 高級語法高亮
- 更高級的語法高亮
- 基本折疊
- 高級折疊
- 段移動原理
- Potion段移動
- 外部命令
- 自動加載
- 文檔
- 發布
- 還剩下什么?