我們的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藝術字更好看。