better docs for autoformat

README.markdown

@@ -40,20 +40,20 @@ There are good reasons NOT to use Vim for writing:
 But then again Vim offers a unique editing environment not matched by
 other writing tools:
 
-* Your hands rest in a neutral ‘home’ position, only rarely straying to
+* Hands rest in a neutral ‘home’ position, only rarely straying to reach
-  reach for mouse, track pad, or arrow keys
+  for mouse, track pad, or arrow keys
 * Minimal chording, with many mnemonic-friendly commands
 * Sophisticated capabilities for navigating and manipulating text
 * Highly configurable to suit your needs, with many plugins available
 
 ## Installation
 
-Install using Pathogen, Vundle, Neobundle, or your favorite Vim package manager.
+Install using Pathogen, Vundle, Neobundle, or your favorite Vim package
+manager.
 
-(Suggestion for those who are new to Vim: you should first work through
+(For those who are new to Vim: you should first work through one of the
-one of the Vim tutorials listed at the bottom of this document. Then, once
+Vim tutorials listed at the bottom of this document. Then, once you are
-you are comfortable with the basics of Vim, consider installing this
+comfortable with the basics of Vim, consider installing this plugin.)
-plugin.)
 
 ## Configuration
 
@@ -120,17 +120,17 @@ let g:pencil#joinspaces = 0
 
 ## Automatic formatting
 
-(This feature affects ‘hard’ line break mode only.)
+_This ‘autoformat’ feature affects ‘hard’ line break mode only._
 
 When using hard line breaks, Vim’s autoformat feature can offer many of
 the same benefits as soft wrapping lines. But autoformat can cause havoc
-when editing outside of paragraphs of sentences. Occasionally, you will
+when editing outside of paragraphs of sentences, such as when editing
-need to disable it.
+a table or code block. In these cases you will need to disable it.
 
 To set the default behavior, add to your `.vimrc`:
 
 ```vim
-let g:pencil#autoformat = 1      " 1=enable, 0=disable
+let g:pencil#autoformat = 1      " 1=auto, 0=manual
 ```
 
 You can override this default during initialization, as in:
@@ -153,16 +153,29 @@ You can also toggle it as needed with a command:
 Or bind to keys in your `.vimrc`:
 
 ```vim
-nmap <silent> <leader>pa :AutoPencil<cr>
+nnoremap <silent> <leader>pa :AutoPencil<cr>
-nmap <silent> <leader>pm :ManualPencil<cr>
+nnoremap <silent> <leader>pm :ManualPencil<cr>
-nmap <silent> <leader>pt :ToggleAutoPencil<cr>
+nnoremap <silent> <leader>pt :ToggleAutoPencil<cr>
 ```
 
-Again, when using soft line wrapping, Vim’s autoformat feature does not
+Note that you don’t have to rely on autoformat and can alway reformat your
-apply.
+paragraphs manually with the standard Vim commands:
+
+* `gqip` - manual format
+* `vipJ` - manual unformat
+
+Optionally, you may want to map these to keys in your `.vimrc`:
+
+```vim
+nnoremap <silent> Q gqip
+nnoremap <silent> K vipJ
+```
 
 ## Auto-detection via modeline
 
+Will the wrapping mode be detected automatically? Maybe. But you can
+improve its chances by giving it a hint.
+
 At the bottom of this document is a strange code:
 
 ```
@@ -180,6 +193,12 @@ That’s a strong hint to this plugin that we should assume hard line
 endings, regardless of whether or not soft wrapping is the default editing
 mode for files of type ‘markdown’.
 
+If it’s 0, then soft line wrapping is assumed.
+
+```
+<!-- vim: set tw=0 :-->
+```
+
 To provide a hint for detection, you can add a modeline to the last line
 of your documents. For more details: