<ruby id="bdb3f"></ruby>

    <p id="bdb3f"><cite id="bdb3f"></cite></p>

      <p id="bdb3f"><cite id="bdb3f"><th id="bdb3f"></th></cite></p><p id="bdb3f"></p>
        <p id="bdb3f"><cite id="bdb3f"></cite></p>

          <pre id="bdb3f"></pre>
          <pre id="bdb3f"><del id="bdb3f"><thead id="bdb3f"></thead></del></pre>

          <ruby id="bdb3f"><mark id="bdb3f"></mark></ruby><ruby id="bdb3f"></ruby>
          <pre id="bdb3f"><pre id="bdb3f"><mark id="bdb3f"></mark></pre></pre><output id="bdb3f"></output><p id="bdb3f"></p><p id="bdb3f"></p>

          <pre id="bdb3f"><del id="bdb3f"><progress id="bdb3f"></progress></del></pre>

                <ruby id="bdb3f"></ruby>

                ??碼云GVP開源項目 12k star Uniapp+ElementUI 功能強大 支持多語言、二開方便! 廣告
                我們的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藝術字更好看。
                  <ruby id="bdb3f"></ruby>

                  <p id="bdb3f"><cite id="bdb3f"></cite></p>

                    <p id="bdb3f"><cite id="bdb3f"><th id="bdb3f"></th></cite></p><p id="bdb3f"></p>
                      <p id="bdb3f"><cite id="bdb3f"></cite></p>

                        <pre id="bdb3f"></pre>
                        <pre id="bdb3f"><del id="bdb3f"><thead id="bdb3f"></thead></del></pre>

                        <ruby id="bdb3f"><mark id="bdb3f"></mark></ruby><ruby id="bdb3f"></ruby>
                        <pre id="bdb3f"><pre id="bdb3f"><mark id="bdb3f"></mark></pre></pre><output id="bdb3f"></output><p id="bdb3f"></p><p id="bdb3f"></p>

                        <pre id="bdb3f"><del id="bdb3f"><progress id="bdb3f"></progress></del></pre>

                              <ruby id="bdb3f"></ruby>

                              哎呀哎呀视频在线观看