Vimscript 文檔

我們的Potion插件有著許多有用的功能，但是無人知曉這一點，除非我們留下了文檔！

Vim自身的文檔非常棒。它不僅是詳細(xì)地，而且也是非常透徹的。 同時，它也啟發(fā)了許多插件作者寫出很好的插件文檔，結(jié)果是在Vimscript社區(qū)里營造出強大的文檔文化。

如何使用文檔

當(dāng)你閱讀Vim里的:help條目時，你顯然注意到了有些內(nèi)容被高亮得跟別的不一樣。 讓我們看一下這是怎么回事。

打開任何幫助條目(比如:help help)并執(zhí)行:set filetype?。Vim顯示filetype=help。 現(xiàn)在執(zhí)行:set filetype=text，你將看到高亮消失了。 再次執(zhí)行:set filetype=help，高亮又回來了。

這表明Vim幫助文件只是獲得了語法高亮的文本文件，一如其他的文件格式！ 這意味著你可以照著寫并獲得同樣的高亮。

在你的插件repo中創(chuàng)建名為doc/potion.txt文件。 Vim/Pathogen在索引幫助條目時查找在doc文件夾下的文件，所以我們在此寫下插件的幫助文檔。

用Vim打開這個文件并執(zhí)行:set filetype=help，這樣你在輸入的時候就可以看到語法高亮。

幫助的題頭

幫助文件的格式是一個取決于個人品味的問題。 盡管這么說，我還是講講一種在當(dāng)前的Vimscript社區(qū)逐漸被廣泛使用的文檔格式。

文件的第一行應(yīng)該包括幫助文件的文件名，接下來是一行對插件功能的描述。 在你的potion.txt文件的第一行加上下面的內(nèi)容：

*potion.txt* functionality for the potion programming language

在幫助文件中用星號括起一個詞創(chuàng)建了一個可以用于跳轉(zhuǎn)的"tag"。 執(zhí)行:Helptags來讓Pathogen重新索引幫助tags，接著打開一個新的Vim窗口并執(zhí)行:help potion.txt。 Vim將打開你的幫助文檔，一如往日打開別人寫的。

接下來你應(yīng)該把你的插件的大名和一個老長老長的描述打上去。 有些作者(包括我)喜歡在這上面花點心思，用一些ASCII藝術(shù)字點綴一下。 在potion.txt文件內(nèi)加上一個不錯的標(biāo)題節(jié)：

*potion.txt* functionality for the potion programming language

                      ___      _   _              ~
                     / _ \___ | |_(_) ___  _ __   ~
                    / /_)/ _ \| __| |/ _ \| '_ \  ~
                   / ___/ (_) | |_| | (_) | | | | ~
                   \/    \___/ \__|_|\___/|_| |_| ~

          Functionality for the Potion programming language.
        Includes syntax highlighting, code folding, and more!

我是通過執(zhí)行figlet -f ogre "Potion"命令來得到這些有趣的字符的。?Figlet是一個好玩的小程序，可以生成ACSII藝術(shù)字。 每一行結(jié)尾的~字符保證Vim不會嘗試高亮或隱藏藝術(shù)字中的某些字符。

寫什么文檔

接下來通常是一個內(nèi)容目錄。不過，首先，讓我們決定我們想要寫的文檔內(nèi)容。

在給一個新插件寫文檔時，我通常從下面的列表開始：

• Introduction
• Usage
• Mappings
• Configuration
• License
• Bugs
• Contributing
• Changelog
• Credits

如果這是一個大插件，需要一個"大綱"，我將寫一個介紹段落來概括它的主要功能。 否則我會跳過它繼續(xù)下一段。

一個"usage"段落應(yīng)該解釋，大體上用戶將怎樣_使用_你的插件。如果他們需要通過映射進行交互，告訴他們。 如果映射數(shù)目不是很多，你可以簡單地在這里列出來，否則你可能需要創(chuàng)建一個單獨的"mappings"段落來一一列出。

"configuration"段落應(yīng)該詳盡列出用戶可以自定義的變量，以及它們的功能和默認(rèn)值。

"license"段落應(yīng)該指出插件代碼所用的協(xié)議，連同一個指向協(xié)議完整文本的URL。 不要把整份協(xié)議放入幫助文件 -- 大多數(shù)用戶知道這些常用的協(xié)議是什么意思，這樣做只會徒增混亂。

"bugs"段落應(yīng)該盡可能短小。列出所有你已知卻尚未解決的主要的bugs，并告知用戶如何向你報告他們抓到的新bug。

如果你希望你的用戶可以向項目奉獻bug fixes和features，他們需要怎么做。 應(yīng)該把pull request發(fā)到GitHub呢？還是Bitbucket?要用email寄補丁嗎？ 要選擇其中的一個還是全都得要？一個"contributing"段落可以清楚地表明你想要接受代碼的方式。

一個changlog也是值得包含在內(nèi)的，這樣當(dāng)用戶從版本X更新到版本Y時，他們立即可以看到什么改變了。 此外，我強烈推薦你為你的插件使用一個合理的版本號計劃，比如Semantic Versioning，并一直堅持。 你的用戶會感謝你的。

最后，我喜歡加入一個"credits"段落來留下自己的大名，列出影響該插件創(chuàng)作的其他插件，感謝奉獻者，等等。

這樣我們就有一個成功的開始了。對于許多特殊的插件，你可能覺得需要不這么做，那也沒問題。 你僅需追隨下面幾條規(guī)則：

• 透徹明了
• 不要廢話
• 帶領(lǐng)你的用戶漫步于你的插件，從一無所知到了如指掌。

內(nèi)容目錄

既然我們已經(jīng)了解了應(yīng)該要有的段落，把下面內(nèi)容加入到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*將創(chuàng)建另一個tag，這樣用戶可以輸入:help PotionContents來直接跳到內(nèi)容目錄。

用|包起每一個詞將創(chuàng)建一個跳轉(zhuǎn)到tag的鏈接。 用戶可以把他們的光標(biāo)移到詞上并按下<c-]>跳轉(zhuǎn)到對應(yīng)tag，就像他們輸入:help TheTag一樣。 他們也可以用鼠標(biāo)點開。

Vim將隱藏*和|并高亮其間的內(nèi)容，所以用戶將會看到一個整潔漂亮的目錄，以便于跳到感興趣的地方。

段落

你可以像這樣創(chuàng)建一個段頭：

====================================================================
Section 1: Usage                                       *PotionUsage*

This plugin with automatically provide syntax highlighting for
Potion files (files ending in .pn).

It also...

確保對*圍起的內(nèi)容創(chuàng)建了正確的tags，這樣你的目錄的鏈接才能正常工作。

繼續(xù)并為目錄中每一部分創(chuàng)建段頭。

例子

我可以講述所有的幫助文件語法和怎樣使用它們，但我不喜歡這樣。 所以，不如我給你一系列不同類型的Vim插件文檔作為例子。

對于每個例子，復(fù)制文檔源代碼到一個Vim緩沖區(qū)并設(shè)置它的filetype為help來觀察它的渲染。 如果你想比較每個渲染效果，切回text看看。

你也許需要使用你的Vimscript技能為當(dāng)前緩沖區(qū)創(chuàng)建一個切換于help和text的映射。

• Clam，我自己用來寫shell命令的插件。這是一個很小的范例，滿足了我前面講過的大多數(shù)內(nèi)容。
• NERD tree，Scrooloose寫的一個文件瀏覽插件。 注意大體結(jié)構(gòu)，還有他如何在詳盡解釋每一項之前，總結(jié)出一個易讀的列表。
• Surround，Tim Pope寫的一個處理環(huán)繞字符的插件。 注意到它沒有目錄，以及不同的段頭風(fēng)格和表格列項(table column headers)。 弄懂他是怎么做到的，并想想你是否喜歡這種風(fēng)格。這是個人風(fēng)格問題啦。
• Splice，我自己用來解決版本控制中three-way merge conflict的插件。 注意映射列表的排版方式，以及我怎樣使用ASCII流派的圖片來解釋布局。有時候，一圖勝千言。

不要忘了，Vim本身的文檔也可以作為一個例子。這會給你許多可供學(xué)習(xí)的內(nèi)容。

寫！

既然你已經(jīng)看過其他插件如何規(guī)劃和撰寫它們的文檔，給你的Potion插件填補上文檔內(nèi)容吧。

如果你不熟悉技術(shù)文檔的寫作，這可能會是個挑戰(zhàn)。 學(xué)習(xí)如何去寫并不容易，但一如其他技能，它需要的是更多的練習(xí)，所以現(xiàn)在開始吧！ 你不必苛求完美，從戰(zhàn)爭中學(xué)習(xí)戰(zhàn)爭即可。

不要懼于寫你沒有完全弄懂的事情，待會丟掉它重寫即可。 經(jīng)常只要在緩沖區(qū)中信手留下幾筆，將會帶動你的頭腦進入寫作狀態(tài)。 任何時候你想重起爐灶，舊版本一直會在版本控制中等你。

一個開始的好方法是想象你身邊也有一個使用Vim的好基友。 他對你的插件很感興趣卻未曾用過，而你的目標(biāo)是讓他熟練掌握。 在你寫下插件工作的方式之前，考慮如何向人類進行介紹，可以讓你腳踏實地，避免太深入于技術(shù)層面。

如果你依舊卡住了，感覺自己無力應(yīng)對寫一個完整插件的文檔的挑戰(zhàn)，嘗試做點簡單的。 在你的~/.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

它比一個完整插件的文檔短很多，卻是一個練習(xí)寫作的好練習(xí)。 如果你把~/.vimrc放到Bitbucket或GitHub，別人也更容易理解。

練習(xí)

給Potion插件每一部分寫下文檔。

閱讀:help help-writing來幫助你寫幫助文檔。

閱讀:help :left,?:help :right,和:help :center來學(xué)習(xí)三個有用的命令使得你的ASCII藝術(shù)字更好看。