# HG changeset patch # User Steve Losh # Date 1351980930 14400 # Node ID 51a18213a0aa9ad00dde4f44211e3e70a2b33b43 # Parent ce37028052fe35d6c2ca7e65f479b895168d6674 Documentation chapter. diff -r ce37028052fe -r 51a18213a0aa chapters/54.markdown --- a/chapters/54.markdown Sat Nov 03 15:41:09 2012 -0400 +++ b/chapters/54.markdown Sat Nov 03 18:15:30 2012 -0400 @@ -1,11 +1,299 @@ Documentation ============= -Writing Documentation ---------------------- +Our Potion plugin has a bunch of useful functionality in it, but it won't be +really useful to anyone unless we document it so they know what it can do! + +Vim's own documentation is superb. It's not overly wordy, but it's extremely +thorough. It's also inspired many plugin authors to document their own plugins +very well, which has resulted in a wonderful culture of strong documentation in +the Vimscript community. + +How Documentation Works +----------------------- + +When you read a `:help` topic in Vim you've surely noticed that some things are +highlighted differently than others. Let's take a look at how this works. + +Open up any help topic (such as `:help help`) and run `:set filetype?`. Vim +will display `filetype=help`. Now run `:set filetype=text`, and you'll see that +the highlighting goes away. `:set filetype=help` again and it will come back. + +It turns out that Vim help files are simply syntax-highlighted text files like +any other file format! This means you can write your own and get the same +highlighting. + +Create a file called `doc/potion.txt` in your plugin repo. Vim/Pathogen looks +for files inside `doc` folders when indexing help topics, so this is where we'll +write the help for our plugin. + +Open this file in Vim and run `:set filetype=help` so you can see the syntax +highlighting as you type. + +Help Header +----------- + +The format of help files is a matter of personal taste. With that said, I'll +talk about one way to structure them that seems to be popular with the modern +Vimscript community. + +The first line of the file should contain the filename of the help file, +followed by a one-line description of what the plugin does. Add the following +as the first line of your `potion.txt` file: + + :::text + *potion.txt* functionality for the potion programming language + +Surrounding a word with asterisks in a help file creates a "tag" that can be +jumped to. Run `:Helptags` to tell Pathogen to rebuild the index of help tags, +and then open a new Vim window and run `:help potion.txt`. Vim will open your +help document like any other one. + +Next you should put the title of your plugin along with a longer description. +Some authors (including me) like to have a bit of fun with this and use some +ASCII-art to spice things up. Add a nice title section to the `potion.txt` +file: + + :::text + *potion.txt* functionality for the potion programming language + + ___ _ _ ~ + / _ \___ | |_(_) ___ _ __ ~ + / /_)/ _ \| __| |/ _ \| '_ \ ~ + / ___/ (_) | |_| | (_) | | | | ~ + \/ \___/ \__|_|\___/|_| |_| ~ + + Functionality for the Potion programming language. + Includes syntax highlighting, code folding, and more! + +I got those fun letters by running the `figlet -f ogre "Potion"` command. +[Figlet][] is a great little program for generating ASCII-art text. The `~` +characters at the end of the lines ensure that Vim doesn't try to highlight or +hide individual characters inside the art. + +[Figlet]: http://www.figlet.org/ What to Document ---------------- +Next usually comes a table of contents. First, though, let's decide what we +actually want to document. + +When writing documentation for a new plugin I usually start with the following +list of sections and work from there: + +* Introduction +* Usage +* Mappings +* Configuration +* License +* Bugs +* Contributing +* Changelog +* Credits + +If the plugin is large and requires an "overview" I'll write an introductory +section that summarizes how things work. Otherwise I'll skip that and just move +on. + +A "usage" section should explain in, general, how the user will actually *use* +your plugin. If they'll interact with it through mappings, tell them that. If +there aren't too many mappings you can simply list them here, otherwise you may +want to create a separate "mappings" section that lists them all. + +The "configuration" section should list each and every user-modifiable variable, +along with its effects and its default value. + +The "license" section should specify what license the plugin's code is under, as +well as a URL where the user can find the full text of that license. Don't +include the full text in the actual help file -- most users know what the common +licenses mean and it just clutters things up. + +The "bugs" section should be short and sweet. List any major bugs that you're +aware of but haven't gotten around to fixing, and tell the user how they can +report new bugs they find to you. + +If you want your users to be able to contribute bug fixes and features for the +plugin back to you, they'll need to know how to do it. Should they send a pull +request on GitHub? On Bitbucket? Send a patch in an email? Any/all of the +above? Include a "contributing" section makes it clear how you prefer to +receive code. + +A changelog is a wonderful thing to include so that when users update your +plugin from version X to version Y they can immediately see what changed. Also, +I highlight recommend you pick a sane versioning scheme like [Semantic +Versioning][] for your plugin and stick to it. Your users will thank you. + +Finally, I like to include a "credits" section to mention my own name, list +other plugins that this one was inspired by, thank contributors, and so on. + +This is usually a good starting point. For more unique plugins you may feel the +need to deviate from this list, and that's completely fine. There are no hard +and fast rules except the following: + +* Be thorough. +* Don't be too wordy. +* Take the user on a journey from having no idea what your plugin is to being an + expert user of it. + +[Semantic Versioning]: http://semver.org/ + +Table of Contents +----------------- + +Now that we have an idea of what sections we'll include, add the following to +the `potion.txt` file: + + :::text + ============================================================================== + CONTENTS *PotionContents* + + 1. Usage ................ |PotionUsage| + 2. Mappings ............. |PotionMappings| + 3. License .............. |PotionLicense| + 4. Bugs ................. |PotionBugs| + 5. Contributing ......... |PotionContributing| + 6. Changelog ............ |PotionChangelog| + 7. Credits .............. |PotionCredits| + +There are a couple things to note here. First, the line of `=` characters will +be syntax highlighted. You can use these lines to visually divide up sections +of your help document. You can also use lines of `-` characters for +subsections, if you want. + +The `*PotionContents*` will create another tag, so a user can type `:help +PotionContents` to go directly to the table of contents. + +Each of the words surrounded by `|` characters creates a link to a tag. Users +can place their cursor on the word in the help file and press `` to jump to +the tag, just as if they had typed `:help TheTag`. They can also click them +with their mouse. + +Vim will hide these `*` and `|` characters and syntax highlight them, so the +result will be a nice, pretty table of contents people can use to get to what +they're looking for. + +Sections +-------- + +You can create section headers like this: + + :::text + ============================================================================== + Section 1: Usage *PotionUsage* + + This plugin with automatically provide syntax highlighting for Potion files + (files ending in .pn). + + It also... + +Make sure to create the correct tags with the `*` characters so that all the +links in your table of contents work properly. + +Go ahead and create headers for each section in the table of contents. + +Examples +-------- + +I could try to go over all the syntax of help files and how to use it, but it's +really a matter of taste. So instead I'll give you a list of several Vim +plugins with extensive documentation. + +For each one, copy the raw source of the documentation into a Vim buffer and set +its filetype to `help` to see how it renders. Switch back to `text` when you +want to see how an effect was created. + +You may find it useful to use your Vimscript skills create a key mapping to +toggle the `help` and `text` filetypes for the current buffer. + +* [Clam][], my own plugin for working with shell commands. It's a pretty short + example that hits most of the sections I talked about. +* The [NERD tree][], a file navigation plugin by Scrooloose. Note the general + structure, as well as how he summarizes the mappings in an easy-to-read list + before explaining every one in detail. +* [Surround][], a plugin for handling "surrounding" characters by Tim Pope. + Note the lack of a table of contents, the different style of section + headers, and the table column headers. Figure out how these things were done, + and decide if you like them. It's a matter of taste. +* [Splice][], my own plugin for resolving three-way merge conflicts in version + control systems. Note how the lists of mappings are formatted, and how I used + ASCII-art diagrams to explain layouts. Sometimes a picture really is worth + a thousand words. + +Remember that all of the vanilla Vim documentation can also be used as an +example too. That should give you plenty to study and learn from. + +[Clam]: https://github.com/sjl/clam.vim/blob/master/doc/clam.txt +[Surround]: https://github.com/tpope/vim-surround/blob/master/doc/surround.txt +[NERD tree]: https://github.com/scrooloose/nerdtree/blob/master/doc/NERD_tree.txt +[Splice]: https://github.com/sjl/splice.vim/blob/master/doc/splice.txt + +Write! +------ + +Now that you've see how some other plugins structured and wrote their +documentation, fill in the sections for your Potion plugin. + +If you're not used to writing technical documentation this might be a challenge. +Learning to write certainly isn't simple, but like any other skill it definitely +requires practice, so just go to it! It doesn't need to be perfect and you can +always improve it later. + +Don't be afraid to write something you're not completely sure about and then +throw it away and rewrite it later. Often just getting *something* in the +buffer will get your mind in the mood to write. It'll still be in version +control if you ever want it back any way. + +A good way to start is to imagine you've got a friend who also uses Vim sitting +next to you. They've never used your plugin before but are intrigued, and your +goal is to turn them into an expert user of it. Thinking about explaining +things to an actual human being will help keep you grounded and avoid getting +too deeply technical before you've established a good overview of how things +work. + +If you're still stuck and feel like you're not up to the challenge of writing +the documentation for a full plugin, try doing something smaller. Pick +a mapping in your `~/.vimrc` file and document it fully in a comment. Explain +what it's for, how to use it, and how it works. For example, this is in my own +`~/.vimrc` file: + + :::vim + " "Uppercase word" mapping. + " + " This mapping allows you to press 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 to uppercase it, and then + " continue happily on your way: + " + " cursor + " v + " max_connections_allowed| + " + " 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 mzgUiw`za + +It's much shorter than the documentation for a full plugin, but it's a good +exercise that will help you practice writing. It's also very helpful for people +reading your `~/.vimrc` if you put it up on Bitbucket or GitHub. + Exercises --------- + +Write the documentation for each section of the Potion plugin. + +Read `:help help-writing` for help about writing help. + +Read `:help :left`, `:help :right`, and `:help :center` to learn about three +useful commands for getting your ASCII-art perfect. diff -r ce37028052fe -r 51a18213a0aa chapters/56.markdown --- a/chapters/56.markdown Sat Nov 03 15:41:09 2012 -0400 +++ b/chapters/56.markdown Sat Nov 03 18:15:30 2012 -0400 @@ -1,15 +1,48 @@ What Now? ========= +If you've read up to this point and completed all the examples and exercises +you now have a pretty solid grasp of the basics of Vimscript. Don't worry +though, there's still *plenty* left to learn! + +Here are a few ideas of topics to look into if you're hungry for more. + +The Command Command +------------------- + +Many plugins allow the user to interact with them through key mappings and +function calls, but some prefer to create Ex commands instead. For example, the +[Fugitive][] plugin creates commands like `:Gbrowse` and `:Gdiff` and leaves it up +to the user to decide how to call them. + +Commands like this are created with the `:command` command. Read `:help +user-commands` to learn how to make your own. You should know enough Vimscript +by now that reading Vim's documentation is sufficient for learning about new +commands. + +[Fugitive]: https://github.com/tpope/vim-fugitive + runtimepath ----------- -The Command Command -------------------- +In this book I've kind of glossed over how Vim decides which files to load by +saying "just use Pathogen". Now that you know a decent amount of Vimscript you +can read `:help runtimepath` and check out [Pathogen's source +code][pathogen-src] to find out what's *really* happening under the hood. + +[pathogen-src]: https://github.com/tpope/vim-pathogen/blob/master/autoload/pathogen.vim Omnicomplete ------------ +Vim offers a number of different ways to complete text (read `:help +ins-completion` for an overview). Most are fairly simple, but the most powerful +of them is "omnicomplete" which lets you call a custom Vimscript function to +determine completions in just about any way you could possibly think of. + +When you're ready to dive into the rabbit hole of omnicompletion you can start +with `:help omnifunc` and `:help coml-omni` and follow the trail from there. + Compiler Support ---------------- @@ -21,3 +54,5 @@ Exercises --------- + +Go write a Vim plugin for something you've always wanted!