Add common settings and overhaul README formatting, esp. bindings sec…

…tion

README.md

@@ -1,35 +1,39 @@
-# Installation
+# NERD Commenter
 
-## Via Plugin Manager (Recommended)
+Comment functions so powerful—no comment necessary.
 
-### [Vim-Plug](https://github.com/junegunn/vim-plug)
+## Installation
+
+### Via Plugin Manager (Recommended)
+
+#### [Vim-Plug](https://github.com/junegunn/vim-plug)
 
 1. Add `Plug 'Plug scrooloose/nerdcommenter'` to your vimrc file.
 2. Reload your vimrc or restart
 3. Run `:PlugInstall`
 
-### [Vundle](https://github.com/VundleVim/Vundle.vim) or similar
+#### [Vundle](https://github.com/VundleVim/Vundle.vim) or similar
 
 1. Add `Plugin 'scrooloose/nerdcommenter'` to your vimrc file.
 2. Reload your vimrc or restart
 3. Run `:BundleInstall`
 
-### [NeoBundle](https://github.com/Shougo/neobundle.vim)
+#### [NeoBundle](https://github.com/Shougo/neobundle.vim)
 
 1. Add `NeoBundle 'scrooloose/nerdcommenter'` to your vimrc file.
 2. Reload your vimrc or restart
 3. Run `:NeoUpdate``
 
-### [Pathogen](https://github.com/tpope/vim-pathogen)
+#### [Pathogen](https://github.com/tpope/vim-pathogen)
 
 ```sh
 cd ~/.vim/bundle
 git clone https://github.com/scrooloose/nerdcommenter.git
 ```
 
-## Manual Installation
+### Manual Installation
 
-### Unix
+#### Unix
 
 (For Neovim, change `~/.vim/` to `~/.config/nvim/`.)
 
@@ -40,7 +44,7 @@ curl -fLo ~/.vim/doc/NERD_Commenter.txt --create-dirs \
   https://raw.githubusercontent.com/scrooloose/nerdcommenter/master/doc/NERD_commenter.txt
 ```
 
-### Windows (PowerShell)
+#### Windows (PowerShell)
 
 ```powershell
 md ~\vimfiles\plugin
@@ -51,63 +55,93 @@ $docsuri = 'https://raw.githubusercontent.com/scrooloose/nerdcommenter/master/do
 (New-Object Net.WebClient).DownloadFile($uri, $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath("~\vimfiles\doc\NERD_commenter.txt"))
 ```
 
-## Post Installation
+### Post Installation
 
-Make sure that you have filetype plugins enabled, as the plugin makes use of
-**|commentstring|** where possible (which is usually set in a filetype plugin).
-See **|filetype-plugin-on|** for details, but the short version is make sure this line appears in your vimrc:
+Make sure that you have filetype plugins enabled, as the plugin makes use of **|commentstring|** where possible (which is usually set in a filetype plugin). See **|filetype-plugin-on|** for details, but the short version is make sure this line appears in your vimrc:
 
 ```sh
 filetype plugin on
 ```
 
-# Usage
+## Usage
+
+### Documentation
+
+Please see the vim help system for full documentation of all options: `:help nerdcommenter`
+
+### Settings
+
+Several settings can be added to your vimrc to change the default behavior. Some examples:
+
+```vim
+" Add spaces after comment delimiters by default
+let g:NERDSpaceDelims = 1
+
+" Use compact syntax for prettified multi-line comments
+let g:NERDCompactSexyComs = 1
+
+" Align line-wise comment delimiters flush left instead of following code indentation
+let g:NERDDefaultAlign = 'left'
+
+" Add your own custom formats or override the defaults
+let g:NERDCustomDelimiters = { 'c': { 'left': '/**','right': '*/' } }
+```
+
+### Default mappings
+
+The following key mappings are provided by default (there is also a menu provided that contains menu items corresponding to all the below mappings):
+
+Most of the following mappings are for normal/visual mode only. The **|NERDComInsertComment|** mapping is for insert mode only.
+
+  * `[count]<leader>cc` **|NERDComComment|**
+
+    Comment out the current line or text selected in visual mode.
+
+  * `[count]<leader>cn` **|NERDComNestedComment|**
+
+    Same as <leader>cc but forces nesting.
+
+  * `[count]<leader>c<space>` **|NERDComToggleComment|**
+
+    Toggles the comment state of the selected line(s). If the topmost selected line is commented, all selected lines are uncommented and vice versa.
+
+  * `[count]<leader>cm` **|NERDComMinimalComment|**
+
+    Comments the given lines using only one set of multipart delimiters.
+
+  * `[count]<leader>ci` **|NERDComInvertComment|**
+
+    Toggles the comment state of the selected line(s) individually.
+
+  * `[count]<leader>cs` **|NERDComSexyComment|**
 
-The following key mappings are provided by default (there is also a menu
-provided that contains menu items corresponding to all the below mappings):
+    Comments out the selected lines with a pretty block formatted layout.
 
-Most of the following mappings are for normal/visual mode only. The |NERDComInsertComment| mapping is for insert mode only.
+  * `[count]<leader>cy` **|NERDComYankComment|**
 
-**[count]\<leader\>cc |NERDComComment|**
-Comment out the current line or text selected in visual mode.
+    Same as <leader>cc except that the commented line(s) are yanked first.
 
-**[count]\<leader\>cn |NERDComNestedComment|**
-Same as \<leader\>cc but forces nesting.
+  * `<leader>c$` **|NERDComEOLComment|**
 
-**[count]\<leader\>c\<space\> |NERDComToggleComment|**
-Toggles the comment state of the selected line(s). If the topmost selected
-line is commented, all selected lines are uncommented and vice versa.
+    Comments the current line from the cursor to the end of line.
 
-**[count]\<leader\>cm |NERDComMinimalComment|**
-Comments the given lines using only one set of multipart delimiters.
+  * `<leader>cA` **|NERDComAppendComment|**
 
-**[count]\<leader\>ci |NERDComInvertComment|**
-Toggles the comment state of the selected line(s) individually.
+    Adds comment delimiters to the end of line and goes into insert mode between them.
 
-**[count]\<leader\>cs |NERDComSexyComment|**
-Comments out the selected lines ``sexily''
+  * **|NERDComInsertComment|**
 
-**[count]\<leader\>cy |NERDComYankComment|**
-Same as \<leader\>cc except that the commented line(s) are yanked first.
+    Adds comment delimiters at the current cursor position and inserts between. Disabled by default.
 
-**\<leader\>c$ |NERDComEOLComment|**
-Comments the current line from the cursor to the end of line.
+  * `<leader>ca` **|NERDComAltDelim|**
 
-**\<leader\>cA |NERDComAppendComment|**
-Adds comment delimiters to the end of line and goes into insert mode between
-them.
+    Switches to the alternative set of delimiters.
 
-**|NERDComInsertComment|**
-Adds comment delimiters at the current cursor position and inserts between.
-Disabled by default.
+  * `[count]<leader>cl`  
+    `[count]<leader>cb` **|NERDComAlignedComment|**
 
-**\<leader\>ca |NERDComAltDelim|**
-Switches to the alternative set of delimiters.
+    Same as **|NERDComComment|** except that the delimiters are aligned down the left side (`<leader>cl`) or both sides (`<leader>cb`).
 
-**[count]\<leader\>cl**
-**[count]\<leader\>cb    |NERDComAlignedComment|**
-Same as |NERDComComment| except that the delimiters are aligned down the
-left side (\<leader\>cl) or both sides (\<leader\>cb).
+  * `[count]<leader>cu` **|NERDComUncommentLine|**
 
-**[count]\<leader\>cu |NERDComUncommentLine|**
-Uncomments the selected line(s).
+    Uncomments the selected line(s).