Merge pull request #103 from openalloc/master

Blacklist support Jekyll front matter #92

.github/workflows/vint.yml

@@ -0,0 +1,16 @@
+name: Vint
+on: [push, pull_request]
+jobs:
+  vint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@master
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.7
+      - name: Setup dependencies
+        run: pip install vim-vint
+      - name: Run Vimscript Linter
+        run: vint .

.vintrc.yaml

@@ -0,0 +1,5 @@
+cmdargs:
+  severity: style_problem
+  color: true
+  env:
+    neovim: false

README.markdown

@@ -1,11 +1,13 @@
 # vim-pencil
 
+[![Vint](https://github.com/reedes/vim-pencil/workflows/Vint/badge.svg)](https://github.com/reedes/vim-pencil/actions?workflow=Vint)
+
 > Rethinking Vim as a tool for writers
 
 <br/>
 
 - - -
-![demo](http://i.imgur.com/0KYl5vU.gif)
+![demo](https://i.imgur.com/0KYl5vU.gif)
 - - -
 
 # Features
@@ -21,9 +23,6 @@ smooth the path to writing prose.
 * Adjusts navigation key mappings to suit the wrap mode
 * Creates undo points on common punctuation during Insert mode, including
   deletion via line `<C-U>` and word `<C-W>`
-* When using hard line breaks, _pencil_ enables Vim’s autoformat while
-  inserting text, except for tables and code blocks where you won’t want
-  it
 * Buffer-scoped configuration (with a few minor exceptions, _pencil_ preserves
   your global settings)
 * Support for Vim’s Conceal feature to hide markup defined by Syntax plugins
@@ -31,6 +30,12 @@ smooth the path to writing prose.
 * Support for display of mode indicator (`␍` and `⤸`, e.g.) in the status line
 * Pure Vimscript with no dependencies
 
+In addition, when using hard line break mode:
+
+* Makes use of Vim’s powerful autoformat while inserting text, except for
+  tables and code blocks where you won’t want it.
+* *NEW* Optional key mapping to suspend autoformat for the Insert.
+
 Need spell-check, distraction-free editing, and other features? Vim is about
 customization. To complete your editing environment, learn to configure Vim and
 draw upon its rich ecosystem of plugins.
@@ -54,7 +59,7 @@ switch away from the familiar word processor. Instead, you need
 a compelling reason—one that can appeal to a writer’s love for language
 and the tools of writing.
 
-You can find that reason in Vim's mysterious command sequences. Take `cas`
+You can find that reason in Vim’s mysterious command sequences. Take `cas`
 for instance. You might see it as a mnemonic for _Change Around Sentence_
 to replace an existing sentence. But dig a bit deeper to discover that
 such commands have a grammar of their own, comprised of nouns, verbs, and
@@ -63,93 +68,55 @@ specific language_ for manipulating text, one that can become a powerful
 tool in expressing yourself. For more details on vi-style editing, see...
 
 * [Learn to speak vim – verbs, nouns, and modifiers!][ls] (December 2011)
-* [Your problem with Vim is that you don't grok vi][gv] (December 2011)
-* [Intro to Vim's Grammar][ig] (January 2013)
+* [Your problem with Vim is that you don’t grok vi][gv] (December 2011)
+* [Intro to Vim’s Grammar][ig] (January 2013)
 * [Why Atom Can’t Replace Vim, Learning the lesson of vi][wa] (March 2014)
 * [Language of Vim/Neovim][lovn] (January 2015)
 
-[ls]: http://yanpritzker.com/2011/12/16/learn-to-speak-vim-verbs-nouns-and-modifiers/
-[gv]: http://stackoverflow.com/questions/1218390/what-is-your-most-productive-shortcut-with-vim/1220118#1220118
-[ig]: http://takac.github.io/2013/01/30/vim-grammar/
+[ls]: https://yanpritzker.com/2011/12/16/learn-to-speak-vim-verbs-nouns-and-modifiers/
+[gv]: https://stackoverflow.com/a/1220118/
+[ig]: https://takac.github.io/2013/01/30/vim-grammar/
 [wa]: https://medium.com/p/433852f4b4d1
-[lovn]: http://allsyed.com/language-of-vim-neovim/
+[lovn]: https://allsyed.com/posts/language-of-vim-neovim/
 
 # Installation
 
-_pencil_ is best installed using a Vim package manager, such as
-[Vundle][vnd], [Plug][plg], [NeoBundle][nbn], or [Pathogen][pth].
+You can install using your favorite Vim package manager. (E.g.,
+[Pathogen][pathogen], [Vundle][vundle], or [Plug][plug].) If you are using
+a recent version of vim or neovim, you can also use native package
+support. (See [:help packages][packages].)
 
 _For those new to Vim: before installing this plugin, consider getting
 comfortable with the basics of Vim by working through one of the many
 tutorials available._
 
-[vnd]: https://github.com/gmarik/Vundle.vim
-[plg]: https://github.com/junegunn/vim-plug
-[nbn]: https://github.com/Shougo/neobundle.vim
-[pth]: https://github.com/tpope/vim-pathogen
-
-#### Vundle
-
-Add to your `.vimrc` and save:
-
-```vim
-Plugin 'reedes/vim-pencil'
-```
-
-…then run the following in Vim:
-
-```vim
-:source %
-:PluginInstall
-```
-
-#### Plug
-
-Add to your `.vimrc` and save:
-
-```vim
-Plug 'reedes/vim-pencil'
-```
-
-…then run the following in Vim:
-
-```vim
-:source %
-:PlugInstall
-```
-
-#### NeoBundle
-
-Add to your `.vimrc` and save:
-
-```vim
-NeoBundle 'reedes/vim-pencil'
-```
-
-…then run the following in Vim:
-
-```vim
-:source %
-:NeoBundleInstall
-```
-
-#### Pathogen
-
-Run the following in a terminal:
-
-```bash
-cd ~/.vim/bundle
-git clone https://github.com/reedes/vim-pencil
-```
+[pathogen]: https://github.com/tpope/vim-pathogen
+[vundle]: https://github.com/VundleVim/Vundle.vim
+[plug]: https://github.com/junegunn/vim-plug
+[packages]: https://vimhelp.org/repeat.txt.html#packages
 
 # Configuration
 
-## Basic initialization
+## Initializing by command
 
-Initializing _pencil_ by `FileType` is _optional_, though doing so will
+You can manually enable, disable, and toggle _pencil_ as a command:
+
+* `Pencil` - initialize _pencil_ with auto-detect for the current buffer
+* `NoPencil` (or `PencilOff`) - removes navigation mappings and restores buffer to global settings
+* `TogglePencil` (or `PencilToggle`) - if on, turns off; if off, initializes with auto-detect
+
+Because auto-detect might not work as intended, you can invoke a command
+to set the behavior for the current buffer:
+
+* `SoftPencil` (or `PencilSoft`) - initialize _pencil_ with soft line wrap mode
+* `HardPencil` (or `PencilHard`) - initialize _pencil_ with hard line break mode (and Vim’s autoformat)
+
+## Initializing by file type
+
+Initializing _pencil_ by file type is _optional_, though doing so will
 automatically set up your buffers for editing prose.
 
-Add support for your desired filetypes to your `.vimrc`:
+Add support for your desired file types to your `.vimrc`:
 
 ```vim
 set nocompatible
@@ -182,7 +149,7 @@ also](#see-also) section below.
 
 Coders will have the most experience with the former, and writers the
 latter. But whatever your background, chances are that you must contend
-with both conventions. This plugin doesn't force you to choose a side—you
+with both conventions. This plugin doesn’t force you to choose a side—you
 can configure each buffer independently.
 
 In most cases you can set a default to suit your preference and let
@@ -198,51 +165,25 @@ augroup pencil
 augroup END
 ```
 
-In the example above, for files of type `markdown` this plugin will
+In the example above, for buffers of type `markdown` this plugin will
 auto-detect the line wrap approach, with soft line wrap as the default.
 
-For files of type `text`, it will initialize with hard line breaks, even
-if auto-detect might suggest soft line wrap.
-
-## Commands
-
-You can enable, disable, and toggle _pencil_ as a command:
-
-* `Pencil` - initialize _pencil_ with auto-detect for the current buffer
-* `NoPencil` (or `PencilOff`) - removes navigation mappings and restores buffer to global settings
-* `TogglePencil` (or `PencilToggle`) - if on, turns off; if off, initializes with auto-detect
-
-Because auto-detect might not work as intended, you can invoke a command
-to set the behavior for the current buffer:
-
-* `SoftPencil` (or `PencilSoft`) - initialize _pencil_ with soft line wrap mode
-* `HardPencil` (or `PencilHard`) - initialize _pencil_ with hard line break mode (and Vim’s autoformat)
+For buffers of type `text`, it will initialize with hard line breaks,
+even if auto-detect might suggest soft line wrap.
 
 ## Automatic formatting
 
-_The ‘autoformat’ feature affects *HardPencil* (hard line break) mode
+_The ‘autoformat’ feature affects `HardPencil` (hard line break) mode
 only._
 
-When inserting text while in *HardPencil* mode, Vim’s autoformat feature
-will be enabled by default and can offer many of the same benefits as
-soft line wrap.
+When inserting text while in `HardPencil` mode, Vim’s powerful autoformat
+feature will be _enabled_ by default and can offer many of the same
+benefits as soft line wrap.
 
-One useful exception (aka 'blacklisting'): if used with popular
-prose-oriented syntax plugins, _pencil_ will **not** enable autoformat when
-you enter Insert mode from inside a code block or table. (See the
-advanced section below for more details on the blacklisting feature.)
-
-Where you need to manually enable/disable autoformat for the current
-buffer, you can do so with a command:
-
-* `PFormat` - allows autoformat to be enabled (if not blacklisted)
-* `PFormatOff` - prevents autoformat from enabling (blacklist all)
-* `PFormatToggle` - toggle to allow if off, etc.
-
-To set the default behavior, add to your `.vimrc`:
+To set the default behavior in your `.vimrc`:
 
 ```vim
-let g:pencil#autoformat = 1      " 0=manual, 1=auto (def)
+let g:pencil#autoformat = 1      " 0=disable, 1=enable (def)
 ```
 
 You can override this default during initialization, as in:
@@ -250,43 +191,71 @@ You can override this default during initialization, as in:
 ```vim
 augroup pencil
   autocmd!
-  autocmd FileType text call pencil#init({'wrap': 'hard', 'autoformat': 0})
+  autocmd FileType markdown call pencil#init({'wrap': 'hard', 'autoformat': 1})
+  autocmd FileType text     call pencil#init({'wrap': 'hard', 'autoformat': 0})
   ...
 augroup END
 ```
 
-...where by default, files of type `text` will use hard line endings, but
-with autoformat disabled.
+...where buffers of type `markdown` and `text` will use hard line breaks,
+but `text` buffers will have autoformat disabled.
 
-Optionally, you can map a key in your `.vimrc` to toggle Vim's autoformat:
+## Suspend automatic formatting for the Insert
+
+There are two useful exceptions where autoformat (when enabled for the
+buffer) will be _temporarily disabled_ for the current Insert:
+
+**First** is _pencil’s_ ‘blacklisting’ feature: if used with popular
+prose-oriented syntax plugins, _pencil_ will suspend autoformat when you
+enter Insert mode from inside a code block or table.
+
+**Second**, where blacklisting falls short, you can optionally map
+a buffer-scoped ‘modifier’ key to suspend autoformat during the next
+Insert:
 
 ```vim
-noremap <buffer> <silent> <F7> :<C-u>PFormatToggle<cr>
-inoremap <buffer> <silent> <F7> <C-o>:PFormatToggle<cr>
+let g:pencil#map#suspend_af = 'K'   " default is no mapping
 ```
 
+Using the above mapping, with `Ko` you’ll enter Insert mode with the
+cursor on a new line, but autoformat will suspend for that Insert. Using
+`o` by itself will retain autoformat.
+
+By default no modifier key is mapped.
+
+(See the advanced section below for details on how blacklisting is
+implemented and configured).
+
 ## Manual formatting
 
 Note that you need not rely on Vim’s autoformat exclusively and can
 manually reformat paragraphs with standard Vim commands:
 
-* `gqip` or `gwip` - format current paragraph
-* `vipJ` - unformat (i.e., join all lines with hard line breaks) in current paragraph
+* `gqap` - format current paragraph (see `:help gq` for details)
+* `vapJgqap` - merge two paragraphs (current and next) and format
 * `ggVGgq` or `:g/^/norm gqq` - format all paragraphs in buffer
-* `:%norm vipJ` - unformat all paragraphs in buffer
 
 Optionally, you can map these operations to underutilized keys in your
 `.vimrc`:
 
 ```vim
-nnoremap <silent> Q gwip
+nnoremap <silent> Q gqap
+xnoremap <silent> Q gq
+nnoremap <silent> <leader>Q vapJgqap
 ```
 
+Or you may wish to ‘unformat’, (i.e., remove hard line breaks) when using
+soft line wrap.
+
+* `vipJ` - join all lines in current paragraph
+* `:%norm vipJ` - unformat all paragraphs in buffer
+
 ## Default textwidth
 
-You can configure the textwidth to be used in **HardPencil** mode when no
-textwidth is set globally, locally, or available via modeline. It
-defaults to `74`, but you can change that value in your `.vimrc`:
+You can configure the textwidth to be used in `HardPencil` (hard line
+break) mode when no textwidth is set globally, locally, or available via
+modeline. It defaults to `74`, but you can change that value in your
+`.vimrc`:
 
 ```vim
 let g:pencil#textwidth = 74
@@ -315,13 +284,13 @@ let g:pencil#cursorwrap = 1     " 0=disable, 1=enable (def)
 
 ## Concealing \_\_markup\_\_
 
-_pencil_ enables Vim's powerful Conceal feature, although support among
+_pencil_ enables Vim’s powerful Conceal feature, although support among
 Syntax and Colorscheme plugins is currently spotty.
 
 You can change _pencil’s_ default settings for conceal in your `.vimrc`:
 
 ```vim
-let g:pencil#conceallevel = 3     " 0=disable, 1=onechar, 2=hidechar, 3=hideall (def)
+let g:pencil#conceallevel = 3     " 0=disable, 1=one char, 2=hide char, 3=hide all (def)
 let g:pencil#concealcursor = 'c'  " n=normal, v=visual, i=insert, c=command (def)
 ```
 
@@ -343,10 +312,10 @@ To use Vim’s Conceal feature with Markdown, you will need to install:
 1. [tpope/vim-markdown][tm] as it’s currently the only Markdown syntax
    plugin that supports conceal.
 
-2. a monospaced font (such as [Cousine][co]) featuring the _italic_,
+2. A monospaced font (such as [Cousine][co]) featuring the _italic_,
    **bold**, and ***bold italic*** style variant for styled text.
 
-3. a colorscheme (such as [reedes/vim-colors-pencil][cp]) which supports
+3. A colorscheme (such as [preservim/vim-colors-pencil][cp]) which supports
    the Markdown-specific highlight groups for styled text.
 
 You should then only see the `_` and `*` markup for the cursor line and in
@@ -355,8 +324,8 @@ visual selections.
 **Terminal users:** consult your terminal’s documentation to configure your
 terminal to support **bold** and _italic_ styles.
 
-[co]: http://www.google.com/fonts/specimen/Cousine
-[tm]: http://github.com/tpope/vim-markdown
+[co]: https://fonts.google.com/specimen/Cousine
+[tm]: https://github.com/tpope/vim-markdown
 
 ## Status line indicator
 
@@ -376,7 +345,8 @@ let g:airline_section_x = '%{PencilMode()}'
 ```
 
 The default indicators now include ‘auto’ for when Vim’s autoformat is
-activated in hard line break mode.
+active in hard line break mode. (If autoformat is suspended for the
+Insert, it’ll show the ‘hard’ indicator.)
 
 ```vim
 let g:pencil#mode_indicators = {'hard': 'H', 'auto': 'A', 'soft': 'S', 'off': '',}
@@ -394,17 +364,61 @@ your `.vimrc`.
 Note that `PencilMode()` will return blank for buffers in which _pencil_
 has not been initialized.
 
-[va]: http://github.com/bling/vim-airline
+[va]: https://github.com/bling/vim-airline
 
 ## Advanced pencil
 
 ### Advanced initialization
 
-Configurable options for `pencil#init()` include: `autoformat`,
-`concealcursor`, `conceallevel`, `cursorwrap`, `joinspaces`, `textwidth`,
-and `wrap`. These are detailed above.
+You may want to refactor initialization statements into a function in
+your `.vimrc` to set up a buffer for writing:
 
-You can override _pencil_ and other configuration settings when initializing:
+```vim
+function! Prose()
+  call pencil#init()
+  call lexical#init()
+  call litecorrect#init()
+  call textobj#quote#init()
+  call textobj#sentence#init()
+
+  " manual reformatting shortcuts
+  nnoremap <buffer> <silent> Q gqap
+  xnoremap <buffer> <silent> Q gq
+  nnoremap <buffer> <silent> <leader>Q vapJgqap
+
+  " force top correction on most recent misspelling
+  nnoremap <buffer> <c-s> [s1z=<c-o>
+  inoremap <buffer> <c-s> <c-g>u<Esc>[s1z=`]A<c-g>u
+
+  " replace common punctuation
+  iabbrev <buffer> -- –
+  iabbrev <buffer> --- —
+  iabbrev <buffer> << «
+  iabbrev <buffer> >> »
+
+  " open most folds
+  setlocal foldlevel=6
+
+  " replace typographical quotes (reedes/vim-textobj-quote)
+  map <silent> <buffer> <leader>qc <Plug>ReplaceWithCurly
+  map <silent> <buffer> <leader>qs <Plug>ReplaceWithStraight
+
+  " highlight words (reedes/vim-wordy)
+  noremap <silent> <buffer> <F8> :<C-u>NextWordy<cr>
+  xnoremap <silent> <buffer> <F8> :<C-u>NextWordy<cr>
+  inoremap <silent> <buffer> <F8> <C-o>:NextWordy<cr>
+
+endfunction
+
+" automatically initialize buffer by file type
+autocmd FileType markdown,mkd,text call Prose()
+
+" invoke manually by command for other file types
+command! -nargs=0 Prose call Prose()
+```
+
+For highly-granular control, you can override _pencil_ and other configuration
+settings when initializing buffers by file type:
 
 ```vim
 augroup pencil
@@ -426,26 +440,45 @@ augroup pencil
 augroup END
 ```
 
-Alternatives include `after/ftplugin` modules as well as refactoring initialization
-statements into a function.
+Configurable options for `pencil#init()` include: `autoformat`,
+`concealcursor`, `conceallevel`, `cursorwrap`, `joinspaces`, `textwidth`,
+and `wrap`. These are detailed above.
+
+### Autoformat manual control
+
+_The ‘autoformat’ feature affects `HardPencil` (hard line break) mode
+only._
+
+To suspend autoformat for the next Insert, see above.
+
+When you need to manually enable/disable autoformat for the current
+buffer, you can do so with a command:
+
+* `PFormat` - enable autoformat for buffer (can still be disabled via blacklisting)
+* `PFormatOff` - disable autoformat for buffer
+* `PFormatToggle` - toggle to enable if disabled, etc.
+
+You can map a key in your `.vimrc` to toggle Vim’s autoformat:
+
+```vim
+noremap <silent> <F7> :<C-u>PFormatToggle<cr>
+inoremap <silent> <F7> <C-o>:PFormatToggle<cr>
+```
 
 ### Autoformat blacklisting (and whitelisting)
 
-_The ‘autoformat’ feature affects *HardPencil* (hard line break) mode
+_The ‘autoformat’ feature affects `HardPencil` (hard line break) mode
 only._
 
 When editing formatted text, such as a table or code block, Vim’s
 autoformat will wreak havoc with the formatting. In these cases you will
-want to temporarily deactivate autoformat, such as with the `PFormatOff`
-or `PFormatToggle` commands described above. However, in most cases, you
-won’t need to do this.
+want autoformat suspended for the duration of the Insert.
 
-_pencil_ will detect the syntax highlight group at the cursor position to
-determine whether or not autoformat should be activated.
-
-If you haven’t explicitly disabled autoformat, it will be activated at
-the time you enter Insert mode provided that the syntax highlighting
-group at the cursor position is _not_ in the blacklist.
+When entering Insert mode, _pencil_ will determine the highlight group at
+the cursor position. If that group has been blacklisted, _pencil_ will
+suspend autoformat for the Insert. For example, if editing a buffer of
+type ‘markdown’, autoformat will be suspended if you invoke Insert mode
+from inside a `markdownFencedCodeBlock` highlight group.
 
 Blacklists are now declared by file type. The default blacklists (and
 whitelists) are declared in the `plugin/pencil.vim` module. Here’s an
@@ -469,22 +502,18 @@ excerpt showing the configuration for the ‘markdown’ file type:
         \ }
 ```
 
-For example, if editing a file of type ‘markdown’ and you enter Insert
-mode from inside a `markdownFencedCodeBlock` highlight group, then Vim’s
-autoformat will _not_ be activated.
-
-The whitelist will override the blacklist and allow Vim’s autoformat to
-be activated if text that would normally be blacklisted doesn’t dominate
-the entire line. This allows autoformat to work with `inline` code and
-links.
+The whitelist will override the blacklist and enable Vim’s autoformat if
+text that would normally be blacklisted doesn’t dominate the entire line.
+This allows autoformat to work with `inline` code and links.
 
 ### Auto-detecting wrap mode
 
-If you didn't explicitly specify a wrap mode during initialization,
+If you didn’t explicitly specify a wrap mode during initialization,
 _pencil_ will attempt to detect it.
 
 It will first look for a `textwidth` (or `tw`) specified in a modeline.
-Failing that, _pencil_ will then sample lines from the start of the file.
+Failing that, _pencil_ will then sample lines from the start of the
+buffer.
 
 #### Detect via modeline
 
@@ -505,7 +534,8 @@ command upon loading the file into a buffer:
 ```
 
 It tells _pencil_ to assume hard line breaks, regardless of whether or
-not soft line wrap is the default editing mode for files of type ‘markdown’.
+not soft line wrap is the default editing mode for buffers of type
+‘markdown’.
 
 You explicitly specify soft wrap mode by specifying a textwidth of `0`:
 
@@ -518,12 +548,12 @@ reasons) the textwidth will still be set by this plugin.
 
 #### Detect via sampling
 
-If no modeline with a textwidth is found, _pencil_ will sample the initial
-lines from the file, looking for those excessively-long.
+If no modeline with a textwidth is found, _pencil_ will sample the
+initial lines from the buffer, looking for those excessively-long.
 
 There are two settings you can add to your `.vimrc` to tweak this behavior.
 
-The maximum number of lines to sample from the start of the file:
+The maximum number of lines to sample from the start of the buffer:
 
 ```vim
 let g:pencil#softDetectSample = 20
@@ -548,80 +578,98 @@ If no such lines found, _pencil_ falls back to the default wrap mode.
 
 Bloggers and developers discuss _pencil_ and its brethern:
 
-* [Reed Esau's growing list of Vim plugins for writers][regl] (2014) - by @pengwynn
+* [Reed Esau’s growing list of Vim plugins for writers][regl] (2014) - by @pengwynn
 * [Distraction Free Writing in Vim][dfwiv] (2014) - by @tlattimore
 * [Safari Blog: Turning vim into an IDE through vim plugins][tviai] (2014) - by @jameydeorio
 * [Quick tops for writing prose with Vim][qtfwp] (2014) - by @benoliver999
-* [UseVim: Reed Esau's Writing Plugins][rewp] (2015) - by @alexyoung
+* [UseVim: Reed Esau’s Writing Plugins][rewp] (2015) - by @alexyoung
 * [Tomasino Labs: Vim in Context][vic] (2015) - by @jamestomasino
-* [Writing with Vim][wwv] (2015) - by Pat Ambrosio
 
 Other plugins of specific interest to writers:
 
+* [danielbmarques/vim-ditto][vd] - highlight repeated words
 * [tpope/vim-abolish][ab] - search for, substitute, and abbr. multiple variants of a word
 * [tommcdo/vim-exchange][ex] - easy text exchange operator for Vim
 * [junegunn/limelight.vim][jl] - focus mode that brightens current paragraph
 * [junegunn/goyo.vim][jg] - distraction-free editing mode
 
-[qtfwp]: http://benoliver999.com/technology/2014/12/06/vimforprose/
-[wwv]: https://lilii.co/aardvark/writing-with-vim
-[vic]: https://labs.tomasino.org/vim-in-context.html
-[rewp]: http://usevim.com/2015/05/27/reedes/
+[vd]: https://github.com/danielbmarques/vim-ditto
+[qtfwp]: https://benoliver999.com/technology/2014/12/06/vimforprose/
+[vic]: https://labs.tomasino.org/vim-in-context/
+[rewp]: https://medium.com/usevim/reed-esaus-writing-plugins-5b6c65bc808f
 [tviai]: https://www.safaribooksonline.com/blog/2014/11/23/way-vim-ide/
 [regl]: http://wynnnetherland.com/journal/reed-esau-s-growing-list-of-vim-plugins-for-writers/
 [dfwiv]: http://tlattimore.com/blog/distraction-free-writing-in-vim/
-[ab]: http://github.com/tpope/vim-abolish
-[ex]: http://github.com/tommcdo/vim-exchange
-[jl]: http://github.com/junegunn/limelight.vim
-[jg]: http://github.com/junegunn/goyo.vim
+[ab]: https://github.com/tpope/vim-abolish
+[ex]: https://github.com/tommcdo/vim-exchange
+[jl]: https://github.com/junegunn/limelight.vim
+[jg]: https://github.com/junegunn/goyo.vim
 
 Markdown syntax plugins
 
-* [tpope/vim-markdown][tvm] - the latest version of the syntax plugin that ships with Vim
-* [plasticboy/vim-markdown][pvm]
+Markdown users typically won’t need to install a syntax plugin unless
+they want the latest version of Pope’s syntax highlighting:
+
+* [tpope/vim-markdown][tvm] - (recommended) the latest version of Pope’s
+  syntax plugin which ships with Vim
+
+Those using tables and footnotes should consider installing this plugin:
+
+* [mattly/vim-markdown-enhancements][mvme]
+
+Alternatives to Tim Pope’s syntax highlighting include:
+
+* [preservim/vim-markdown][pvm]
 * [gabrielelana/vim-markdown][gvm]
-* [mattly/vim-markdown-enhancements][mvme] - highlighting for tables and footnotes
 
-[tvm]: http://github.com/tpope/vim-markdown
-[pvm]: http://github.com/plasticboy/vim-markdown
-[gvm]: http://github.com/gabrielelana/vim-markdown
-[mvme]: http://github.com/mattly/vim-markdown-enhancements
+Note that the plasticboy and gabrielelana plugins may incorrectly
+reformat bulleted lists when Vim’s autoformat is active in _pencil_’s
+HardPencil mode.
 
-If you find the _pencil_ plugin useful, check out these others by [@reedes][re]:
+[tvm]: https://github.com/tpope/vim-markdown
+[pvm]: https://github.com/preservim/vim-markdown
+[gvm]: https://github.com/gabrielelana/vim-markdown
+[mvme]: https://github.com/mattly/vim-markdown-enhancements
+
+If you find the _pencil_ plugin useful, check out these others originally
+by [@reedes][re]:
 
 * [vim-colors-pencil][cp] - color scheme for Vim inspired by IA Writer
 * [vim-lexical][lx] - building on Vim’s spell-check and thesaurus/dictionary completion
 * [vim-litecorrect][lc] - lightweight auto-correction for Vim
-* [vim-one][vo] - make use of Vim’s _+clientserver_ capabilities
 * [vim-textobj-quote][qu] - extends Vim to support typographic (‘curly’) quotes
-* [vim-textobj-sentence][ts] - improving on Vim's native sentence motion command
+* [vim-textobj-sentence][ts] - improving on Vim’s native sentence motion command
 * [vim-thematic][th] - modify Vim’s appearance to suit your task and environment
 * [vim-wheel][wh] - screen-anchored cursor movement for Vim
 * [vim-wordy][wo] - uncovering usage problems in writing
+* [vim-wordchipper][wc] - power tool for shredding text in Insert mode
 
 Unimpressed by _pencil_? [vim-pandoc][vp] offers prose-oriented features
 with its own Markdown variant.
 
-[cp]: http://github.com/reedes/vim-colors-pencil
-[lc]: http://github.com/reedes/vim-litecorrect
-[lx]: http://github.com/reedes/vim-lexical
-[qu]: http://github.com/reedes/vim-textobj-quote
-[re]: http://github.com/reedes
+[cp]: https://github.com/preservim/vim-colors-pencil
+[lc]: https://github.com/preservim/vim-litecorrect
+[lx]: https://github.com/preservim/vim-lexical
+[qu]: https://github.com/preservim/vim-textobj-quote
+[re]: https://github.com/reedes
 [tc]: https://www.youtube.com/watch?v=Nim4_f5QUxA
-[th]: http://github.com/reedes/vim-thematic
-[ts]: http://github.com/reedes/vim-textobj-sentence
-[tv]: http://ianhocking.com/2013/11/17/to-vim/
-[vo]: http://github.com/reedes/vim-one
-[vw]: http://therandymon.com/woodnotes/vim-for-writers/vimforwriters.html
-[wh]: http://github.com/reedes/vim-wheel
-[wo]: http://github.com/reedes/vim-wordy
-[vp]: http://github.com/vim-pandoc/vim-pandoc
+[th]: https://github.com/preservim/vim-thematic
+[ts]: https://github.com/preservim/vim-textobj-sentence
+[tv]: https://ianhocking.com/2013/11/17/to-vim/
+[vo]: https://github.com/preservim/vim-one
+[vw]: https://therandymon.com/woodnotes/vim-for-writers/vimforwriters.html
+[wh]: https://github.com/preservim/vim-wheel
+[wo]: https://github.com/preservim/vim-wordy
+[wc]: https://github.com/preservim/vim-wordchipper
+[vp]: https://github.com/vim-pandoc/vim-pandoc
 
 # Future development
 
-If you’ve spotted a problem or have an idea on improving _pencil_,
-please report it as an issue, or better yet submit a pull request.
+If you’ve spotted a problem or have an idea on improving _pencil_, please
+report it [as an issue][issues], or better yet submit [a pull
+request][pull-request].
+
+[issues]: https://github.com/preservim/vim-pencil/issues
+[pull-request]: https://github.com/preservim/vim-pencil/pulls
 
-```
 <!-- vim: set tw=73 :-->
-```

autoload/pencil.vim

@@ -1,11 +1,14 @@
 " ============================================================================
 " File:        pencil.vim
 " Description: autoload functions for vim-pencil plugin
-" Maintainer:  Reed Esau <github.com/reedes>
+" Maintainer:  preservim <https://github.com/preservim>
 " Created:     December 28, 2013
 " License:     The MIT License (MIT)
 " ============================================================================
-if exists("autoloaded_pencil") | fini | en
+
+scriptencoding utf-8
+
+if exists('autoloaded_pencil') | fini | en
 let autoloaded_pencil = 1
 
 let s:WRAP_MODE_DEFAULT = -1
@@ -46,9 +49,9 @@ endf
 
 fun! s:imap(preserve_completion, key, icmd) abort
   if a:preserve_completion
-    exe ":ino <buffer> <silent> <expr> " . a:key . " pumvisible() ? \"" . a:key . "\" : \"" . a:icmd . "\""
+    exe ':ino <buffer> <silent> <expr> ' . a:key . " pumvisible() ? '" . a:key . "' : '" . a:icmd . "'"
   el
-    exe ":ino <buffer> <silent> " . a:key . " " . a:icmd
+    exe ':ino <buffer> <silent> ' . a:key . ' ' . a:icmd
   en
 endf
 
@@ -56,8 +59,14 @@ fun! s:maybe_enable_autoformat() abort
   " don't enable autoformat if in a blacklisted code block or table,
   " allowing for reprieve via whitelist in certain cases
 
-  let l:ft = get(g:pencil#autoformat_aliases, &ft, &ft)
-  let l:af_cfg = get(g:pencil#autoformat_config, l:ft, {})
+  " a flag to suspend autoformat for the Insert
+  if b:pencil_suspend_af
+    let b:pencil_suspend_af = 0   " clear the flag
+    return
+  en
+
+  let l:filetype = get(g:pencil#autoformat_aliases, &filetype, &filetype)
+  let l:af_cfg = get(g:pencil#autoformat_config, l:filetype, {})
   let l:black = get(l:af_cfg, 'black', [])
   let l:white = get(l:af_cfg, 'white', [])
   let l:has_black_re = len(l:black) > 0
@@ -149,7 +158,7 @@ fun! s:maybe_enable_autoformat() abort
 endf
 
 fun! pencil#setAutoFormat(af) abort
-  " 1=auto, 0=manual, -1=toggle
+  " 1=enable, 0=disable, -1=toggle
   if !exists('b:last_autoformat')
     let b:last_autoformat = 0
   en
@@ -166,7 +175,7 @@ fun! pencil#setAutoFormat(af) abort
     sil! au! pencil_autoformat * <buffer>
     if l:nu_af && !l:is_hard
       echohl WarningMsg
-      echo "autoformat can only be enabled in hard line break mode"
+      echo 'autoformat can only be enabled in hard line break mode'
       echohl NONE
       return
     en
@@ -180,10 +189,13 @@ endf
 fun! pencil#init(...) abort
   let l:args = a:0 ? a:1 : {}
 
+  " flag to suspend autoformat for the next Insert
+  let b:pencil_suspend_af = 0
+
   if !exists('b:pencil_wrap_mode')
     let b:pencil_wrap_mode = s:WRAP_MODE_OFF
   en
-  if !exists("b:max_textwidth")
+  if !exists('b:max_textwidth')
     let b:max_textwidth = -1
   en
 
@@ -232,6 +244,14 @@ fun! pencil#init(...) abort
       setl textwidth<
     en
     setl nowrap
+
+    " flag to suspend autoformat for next Insert
+    " optional user-defined mapping
+    if exists('g:pencil#map#suspend_af') &&
+     \ g:pencil#map#suspend_af !=# ''
+      exe 'no <buffer> <silent> ' . g:pencil#map#suspend_af . ' :let b:pencil_suspend_af=1<CR>'
+    en
+
   elsei b:pencil_wrap_mode ==# s:WRAP_MODE_SOFT
     setl textwidth=0
     setl wrap
@@ -366,12 +386,16 @@ fun! pencil#init(...) abort
   en
 
   if b:pencil_wrap_mode ==# s:WRAP_MODE_SOFT
-    nn <buffer> <silent> $ g$
-    nn <buffer> <silent> 0 g0
-    vn <buffer> <silent> $ g$
-    vn <buffer> <silent> 0 g0
+    exe 'nn <buffer> <silent>' . Mapkey('$', 'n') . ' g$'
+    exe 'nn <buffer> <silent>' . Mapkey('0', 'n') . ' g0'
+    exe 'vn <buffer> <silent>' . Mapkey('$', 'v') . ' g$'
+    exe 'vn <buffer> <silent>' . Mapkey('0', 'v') . ' g0'
     no <buffer> <silent> <Home> g<Home>
     no <buffer> <silent> <End>  g<End>
+    nn <buffer> <silent> g0 0
+    nn <buffer> <silent> g$ $
+    vn <buffer> <silent> g0 0
+    vn <buffer> <silent> g$ $
 
     " preserve behavior of home/end keys in popups
     call s:imap(1, '<Home>', '<C-o>g<Home>')
@@ -388,12 +412,16 @@ fun! pencil#init(...) abort
   en
 
   if b:pencil_wrap_mode
-    nn <buffer> <silent> j gj
-    nn <buffer> <silent> k gk
-    vn <buffer> <silent> j gj
-    vn <buffer> <silent> k gk
+    exe 'nn <buffer> <silent> ' . Mapkey('j', 'n') . ' gj'
+    exe 'nn <buffer> <silent> ' . Mapkey('k', 'n') . ' gk'
+    exe 'vn <buffer> <silent> ' . Mapkey('j', 'v') . ' gj'
+    exe 'vn <buffer> <silent> ' . Mapkey('k', 'v') . ' gk'
     no <buffer> <silent> <Up>   gk
     no <buffer> <silent> <Down> gj
+    nn <buffer> <silent> gj j
+    nn <buffer> <silent> gk k
+    vn <buffer> <silent> gj j
+    vn <buffer> <silent> gk k
 
     " preserve behavior of up/down keys in popups
     call s:imap(1, '<Up>'  , '<C-o>g<Up>'  )
@@ -405,6 +433,10 @@ fun! pencil#init(...) abort
     sil! vu  <buffer> k
     sil! unm <buffer> <Up>
     sil! unm <buffer> <Down>
+    sil! nun <buffer> gj j
+    sil! nun <buffer> gk k
+    sil! vu <buffer> gj j
+    sil! vu <buffer> gk k
 
     sil! iu <buffer> <Up>
     sil! iu <buffer> <Down>
@@ -450,7 +482,7 @@ endf
 fun! s:doOne(item) abort
   let l:matches = matchlist(a:item, '^\([a-z]\+\)=\([a-zA-Z0-9_\-.]\+\)$')
   if len(l:matches) > 1
-    if l:matches[1] =~ 'textwidth\|tw'
+    if l:matches[1] =~# 'textwidth\|tw'
       let l:tw = str2nr(l:matches[2])
       if l:tw > b:max_textwidth
         let b:max_textwidth = l:tw
@@ -479,19 +511,32 @@ endf
 " modeline(s) and max line length
 " Hat tip to https://github.com/ciaranm/securemodelines
 fun! s:doModelines() abort
-  if line("$") > &modelines
+  if line('$') > &modelines
     let l:lines={ }
     call map(filter(getline(1, &modelines) +
-          \ getline(line("$") - &modelines, "$"),
-          \ 'v:val =~ ":"'), 'extend(l:lines, { v:val : 0 } )')
+          \ getline(line('$') - &modelines, '$'),
+          \ 'v:val =~# ":"'), 'extend(l:lines, { v:val : 0 } )')
     for l:line in keys(l:lines)
       call s:doModeline(l:line)
     endfo
   el
-    for l:line in getline(1, "$")
+    for l:line in getline(1, '$')
       call s:doModeline(l:line)
     endfo
   en
 endf
 
+" Pass in a key sequence and the first letter of a vim mode. Returns key
+" mapping mapped to it in that mode, else the original key sequence if none.
+function! Mapkey (keys, mode) abort
+  redir => mappings | silent! map | redir END
+  for map in split(mappings, '\n')
+    let seq = matchstr(map, '\s\+\zs\S*')
+    if maparg(seq, a:mode) == a:keys
+      return seq
+    endif
+  endfor
+  return a:keys
+endfunction
+
 " vim:ts=2:sw=2:sts=2

doc/vim-pencil.txt

@@ -0,0 +1,608 @@
+*vim-pencil.txt*  Rethinking Vim as a tool for writers  Last change: 2020-07-29
+
+      _     _  _        ____  _____ _      ____  _  _    
+     / \ |\/ \/ \__/|  /  __\/  __// \  /|/   _\/ \/ \   
+     | | //| || |\ /|  | |  \/  |  |  \ |||  |  | || |   
+     | \// | || |  ||  |  __/|  /_ | | \|||  \_ | || |_/\
+     \__/  \_/\_/  \|  \_/   \____\\_/  \|\____/\_/\____/
+
+            Rethinking Vim as a tool for writers 
+
+CONTENTS                                                             *vim-pencil*
+
+    1. Intro                         |vim-pencil-intro|
+    2. Features                      |vim-pencil-features|
+    3. Why use Vim for writing?      |vim-pencil-writing|
+    4. Installation                  |vim-pencil-initialize|
+        4.1. By command              |vim-pencil-init-by-command|
+        4.2. By filetype             |vim-pencil-init-by-filetype|
+    5. Hard line breaks ro soft wrap |vim-pencil-break-or-wrap|
+    6. Automatic formatting          |vim-pencil-automatic-formatting|
+    7. Suspend automatic formatting  |vim-pencil-suspend-formatting|
+    8. Manual formatting             |vim-pencil-manual-formatting|
+    9. Default Text Width            |vim-pencil-default-width|
+    10. Sentence Spacing             |vim-pencil-sentence-spacing|
+    11. Cursor Wrap                  |vim-pencil-cursor-wrap|
+    12. Concealing markup            |vim-pencil-conceal-markup|
+    13. Concealing styled text       |vim-pencil-conceal-style|
+    14. Status line indicator        |vim-pencil-status-line|
+    15. Advanced pencil              |vim-pencil-advanced-pencil|
+        15.1 Advanced initialization |vim-pencil-advanced-initialization|
+        15.2 Autoformat-control      |vim-pencil-autoformat-control|
+        15.3 Autoformat black/white listing  |vim-pencil-autoformat-listing|
+        15.4 Autodetect wrap mode    |vim-pencil-autodetect-wrap|
+    16. Contributing & Bug reports   |vim-pencil-contributing|
+    17. Development                  |vim-pencil-development|
+    18. License                      |vim-pencil-license|
+
+
+==============================================================================
+1. Intro                                                     *vim-pencil-intro*
+
+The pencil plugin aspires to make Vim as powerful a tool for writers as it is
+for coders by focusing narrowly on the handful of tweaks needed to smooth the
+path to writing prose.
+
+==============================================================================
+2. Features                                               *vim-pencil-features*
+
+- For editing prose-oriented file types such as text, markdown, mail, rst,
+  tex, textile, and asciidoc
+- Agnostic on soft line wrap versus hard line breaks, supporting both
+- Auto-detects wrap mode via modeline and sampling
+- Adjusts navigation key mappings to suit the wrap mode
+- Creates undo points on common punctuation during Insert mode, including
+  deletion via line <C-U> and word <C-W>
+- Buffer-scoped configuration (with a few minor exceptions, pencil preserves
+  your global settings)
+- Support for Vim’s Conceal feature to hide markup defined by Syntax plugins
+  (e.g., _ and * markup for styled text in _Markdown_)
+- Support for display of mode indicator (␍ and ⤸, e.g.) in the status line
+- Pure Vimscript with no dependencies
+
+In addition, when using hard line break mode:
+
+- Makes use of Vim’s powerful autoformat while inserting text, except for
+  tables and code blocks where you won’t want it.
+- NEW Optional key mapping to suspend autoformat for the Insert.
+
+Need spell-check, distraction-free editing, and other features? Vim is about
+customization. 
+
+To complete your editing environment, learn to configure Vim and draw upon its
+rich ecosystem of plugins.  
+
+==============================================================================
+3. Why use Vim for Writing                                 *vim-pencil-writing*
+
+With plenty of word processing applications available, including those that
+specifically cater to writers, why use a modal editor like Vim? Several
+reasons have been offered:
+
+- Your hands can rest in a neutral ‘home’ position, only rarely straying to
+  reach for mouse, track pad, or arrow keys
+- Minimal chording, with many mnemonic-friendly commands
+- Sophisticated capabilities for navigating and manipulating text
+- Highly configurable, enabling you to build a workflow that suits your needs,
+  with many great plugins available 
+- No proprietary format lock-in
+
+But while such reasons might be sound, they remain scant justification to
+switch away from the familiar word processor. Instead, you need a compelling
+reason—one that can appeal to a writer’s love for language and the tools
+of writing.
+
+You can find that reason in Vim’s mysterious command sequences. Take cas for
+instance. You might see it as a mnemonic for Change Around Sentence to replace
+an existing sentence. But dig a bit deeper to discover that such commands have
+a grammar of their own, comprised of nouns, verbs, and modifiers. Think of
+them as the composable building blocks of a domain specific language for
+manipulating text, one that can become a powerful tool in expressing yourself.
+For more details on vi-style editing, see...
+
+    Learn to speak vim – verbs, nouns, and modifiers! (December 2011)
+    http://yanpritzker.com/2011/12/16/learn-to-speak-vim-verbs-nouns-and-modifiers/
+
+    Your problem with Vim is that you don’t grok vi (December 2011)
+    http://stackoverflow.com/questions/1218390/what-is-your-most-productive-shortcut-with-vim/1220118#1220118
+
+    Intro to Vim’s Grammar (January 2013)
+    http://takac.github.io/2013/01/30/vim-grammar/
+
+    Why Atom Can’t Replace Vim, Learning the lesson of vi (March 2014)
+    https://medium.com/p/433852f4b4d1
+
+    Language of Vim/Neovim (January 2015)
+    http://allsyed.com/language-of-vim-neovim/
+
+
+==============================================================================
+4. Installation                                         *vim-pencil-initialize*
+
+pencil is best installed using a Vim package manager, such as Vundle, Plug,
+NeoBundle, or Pathogen. If you are using a recent version of vim or neovim,
+you can also use native package support. (See |packages|.)
+
+------------------------------------------------------------------------------
+4.1. Initializing by command                       *vim-pencil-init-by-command*
+
+You can manually enable, disable, and toggle pencil as a command:
+
+- Pencil                            - initialize pencil with auto-detect for
+  the current buffer
+- NoPencil (or PencilOff)           - removes navigation mappings and restores
+  buffer to global settings
+- TogglePencil (or PencilToggle)    - if on, turns off; if off, initializes
+  with auto-detect
+
+Because auto-detect might not work as intended, you can invoke a command to
+set the behavior for the current buffer:
+
+- SoftPencil (or PencilSoft)        - initialize pencil with soft line wrap
+  mode
+- HardPencil (or PencilHard)        - initialize pencil with hard line break
+  mode (and Vim’s autoformat)
+
+------------------------------------------------------------------------------
+4.2. Initializing by file type                    *vim-pencil-init-by-filetype*
+
+Initializing pencil by file type is optional, though doing so will
+automatically set up your buffers for editing prose.
+
+Add support for your desired file types to your .vimrc:
+
+    set nocompatible
+    filetype plugin on       " may already be in your .vimrc
+
+    augroup pencil
+        autocmd!
+        autocmd FileType markdown,mkd call pencil#init()
+        autocmd FileType text         call pencil#init()
+    augroup END
+
+You can initialize several prose-oriented plugins together:
+
+    augroup pencil
+    autocmd!
+    autocmd FileType markdown,mkd call pencil#init()
+                                \ | call lexical#init()
+                                \ | call litecorrect#init()
+                                \ | call textobj#quote#init()
+                                \ | call textobj#sentence#init() 
+    augroup END
+
+
+==============================================================================
+5. Hard line breaks or soft line wrap               *vim-pencil-break-or-wrap*
+
+Coders will have the most experience with the former, and writers the latter.
+But whatever your background, chances are that you must contend with both
+conventions. This plugin doesn’t force you to choose a side—you can configure
+each buffer independently.
+
+In most cases you can set a default to suit your preference and let
+auto-detection figure out what to do.
+
+    let g:pencil#wrapModeDefault = 'soft'   " default is 'hard'
+
+    augroup pencil
+        autocmd!
+        autocmd FileType markdown,mkd call pencil#init()
+        autocmd FileType text         call pencil#init({'wrap': 'hard'})
+    augroup END
+
+In the example above, for buffers of type markdown this plugin will
+auto-detect the line wrap approach, with soft line wrap as the default.
+
+For buffers of type text, it will initialize with hard line breaks, even if
+auto-detect might suggest soft line wrap
+
+==============================================================================
+6. Automatic Formatting                       *vim-pencil-automatic-formatting*
+
+The ‘autoformat’ feature affects HardPencil (hard line break) mode only.
+
+When inserting text while in HardPencil mode, Vim’s powerful autoformat
+feature will be enabled by default and can offer many of the same benefits as
+soft line wrap.
+
+To set the default behavior in your .vimrc:
+
+    let g:pencil#autoformat = 1      " 0=disable, 1=enable (def)
+
+You can override this default during initialization, as in:
+
+    augroup pencil
+        autocmd!
+        autocmd FileType markdown call pencil#init({'wrap': 'hard', 'autoformat': 1})
+        autocmd FileType text     call pencil#init({'wrap': 'hard', 'autoformat': 0})
+        ...
+    augroup END
+
+...where buffers of type markdown and text will use hard line breaks, but text
+buffers will have autoformat disabled.
+
+
+==============================================================================
+7. Suspend automatic formatting for the insert  *vim-pencil-suspend-formatting*
+
+There are two useful exceptions where autoformat (when enabled for the buffer)
+will be temporarily disabled for the current Insert:
+
+First is pencil’s ‘blacklisting’ feature: if used with popular prose-oriented
+syntax plugins, pencil will suspend autoformat when you enter Insert mode from
+inside a code block or table.
+
+Second, where blacklisting falls short, you can optionally map a buffer-scoped
+‘modifier’ key to suspend autoformat during the next Insert:
+
+    let g:pencil#map#suspend_af = 'K'   " default is no mapping
+
+Using the above mapping, with Ko you’ll enter Insert mode with the cursor on a
+new line, but autoformat will suspend for that Insert. Using o by itself will
+retain autoformat.
+
+By default no modifier key is mapped.
+
+(See the advanced section below for details on how blacklisting is implemented
+and configured).
+
+==============================================================================
+8. Manual formatting                             *vim-pencil-manual-formatting*
+
+Note that you need not rely on Vim’s autoformat exclusively and can manually
+reformat paragraphs with standard Vim commands:
+
+- gqap                      - format current paragraph (see :help gq for details)
+- vapJgqap                  - merge two paragraphs (current and next) and format
+- ggVGgq or :g/^/norm gqq   - format all paragraphs in buffer
+
+Optionally, you can map these operations to underutilized keys in your .vimrc:
+
+    nnoremap <silent> Q gqap
+    xnoremap <silent> Q gq
+    nnoremap <silent> <leader>Q vapJgqap
+
+Or you may wish to ‘unformat’, (i.e., remove hard line breaks) when using soft
+line wrap.
+
+- vipJ                      - join all lines in current paragraph
+- :%norm vipJ               - unformat all paragraphs in buffer
+
+==============================================================================
+9. Default textwidth                                 *vim-pencil-default-width*
+
+You can configure the textwidth to be used in HardPencil (hard line break)
+mode when no textwidth is set globally, locally, or available via modeline. It
+defaults to 74, but you can change that value in your .vimrc:
+
+    let g:pencil#textwidth = 74
+
+
+==============================================================================
+10. Sentence Spacing                              *vim-pencil-sentence-spacing*
+
+By default, when formatting text (through gwip, e.g.) only one space will be
+inserted after a period(.), exclamation point(!), or question mark(?). You can
+change this default:
+
+    let g:pencil#joinspaces = 0     " 0=one_space (def), 1=two_spaces
+
+==============================================================================
+11. Cursor Wrap                                        *vim-pencil-cursor-wrap*
+
+By default, h/l and the left/right cursor keys will move to the previous/next
+line after reaching first/last character in a line with a hard break. If you
+wish to retain the default Vim behavior, set the cursorwrap value to 0 in your
+.vimrc:
+
+    let g:pencil#cursorwrap = 1     " 0=disable, 1=enable (def)
+
+==============================================================================
+12. Conceal Markup                                  *vim-pencil-conceal-markup*
+
+pencil enables Vim’s powerful Conceal feature, although support among Syntax
+and Colorscheme plugins is currently spotty.
+
+You can change pencil’s default settings for conceal in your .vimrc:
+
+    let g:pencil#conceallevel = 3     " 0=disable, 1=one char, 2=hide char, 3=hide all (def)
+    let g:pencil#concealcursor = 'c'  " n=normal, v=visual, i=insert, c=command (def)
+
+For more details on Vim’s Conceal feature, see:
+
+    :help conceallevel
+    :help concealcursor
+
+==============================================================================
+13. Conceal styled text in Markdown                  *vim-pencil-conceal-style*
+
+Syntax plugins such as tpope/vim-markdown support concealing the markup
+characters when displaying _italic_, **bold**, and ***bold italic*** styled
+text.
+
+To use Vim’s Conceal feature with Markdown, you will need to install:
+
+1. tpope/vim-markdown as it’s currently the only Markdown syntax plugin that
+supports conceal.
+
+2. A monospaced font (such as Cousine) featuring the italic, bold, and bold
+italic style variant for styled text.
+
+3. A colorscheme (such as reedes/vim-colors-pencil) which supports the
+Markdown-specific highlight groups for styled text.
+
+You should then only see the _ and * markup for the cursor line and in visual
+selections.
+
+Terminal users: consult your terminal’s documentation to configure your
+terminal to support bold and italic styles.
+
+==============================================================================
+14. Status line indicator                             *vim-pencil-status-line*
+
+Your status line can reflect the wrap mode for pencil buffers. For example, ␍
+to represent HardPencil (hard line break) mode. To configure your status line
+and ruler, add to your .vimrc:
+
+    set statusline=%<%f\ %h%m%r%w\ \ %{PencilMode()}\ %=\ col\ %c%V\ \ line\ %l\,%L\ %P
+    set rulerformat=%-12.(%l,%c%V%)%{PencilMode()}\ %P
+
+or if using bling/vim-airline:
+
+    let g:airline_section_x = '%{PencilMode()}'
+
+The default indicators now include ‘auto’ for when Vim’s autoformat is active
+in hard line break mode. (If autoformat is suspended for the Insert, it’ll
+show the ‘hard’ indicator.)
+
+    let g:pencil#mode_indicators = {'hard': 'H', 'auto': 'A', 'soft': 'S', 'off': '',}
+
+If Unicode is detected, the default indicators are:
+
+    let g:pencil#mode_indicators = {'hard': '␍', 'auto': 'ª', 'soft': '⤸', 'off': '',}
+
+If you don’t like the default indicators, you can specify your own in your
+.vimrc.
+
+Note that PencilMode() will return blank for buffers in which pencil has not
+been initialized.
+
+==============================================================================
+15. Advanced Pencil                               *vim-pencil-advanced-pencil*
+
+Pencil supports several advanced features
+
+==============================================================================
+15.1. Advanced initialization             *vim-pencil-advanced-initialization*
+
+You may want to refactor initialization statements into a function in your
+.vimrc to set up a buffer for writing:
+
+    function! Prose()
+        call pencil#init()
+        call lexical#init()
+        call litecorrect#init()
+        call textobj#quote#init()
+        call textobj#sentence#init()
+
+        " manual reformatting shortcuts
+        nnoremap <buffer> <silent> Q gqap
+        xnoremap <buffer> <silent> Q gq
+        nnoremap <buffer> <silent> <leader>Q vapJgqap
+
+        " force top correction on most recent misspelling
+        nnoremap <buffer> <c-s> [s1z=<c-o>
+        inoremap <buffer> <c-s> <c-g>u<Esc>[s1z=`]A<c-g>u
+
+        " replace common punctuation
+        iabbrev <buffer> -- –
+        iabbrev <buffer> --- —
+        iabbrev <buffer> << «
+        iabbrev <buffer> >> »
+
+        " open most folds
+        setlocal foldlevel=6
+
+        " replace typographical quotes
+        (reedes/vim-textobj-quote)
+        map <silent> <buffer> <leader>qc <Plug>ReplaceWithCurly
+        map <silent> <buffer> <leader>qs <Plug>ReplaceWithStraight
+
+        " highlight words
+        (reedes/vim-wordy)
+        noremap <silent> <buffer> <F8> :<C-u>NextWordy<cr>
+        xnoremap <silent> <buffer> <F8> :<C-u>NextWordy<cr>
+        inoremap <silent> <buffer> <F8> <C-o>:NextWordy<cr>
+
+    endfunction
+
+    " automatically initialize buffer by file type
+    autocmd FileType markdown,mkd,text call Prose()
+
+    " invoke manually by command for other file types
+    command! -nargs=0 Prose call Prose()
+
+For highly-granular control, you can override pencil and other configuration
+settings when initializing buffers by file type:
+
+    augroup pencil
+        autocmd!
+        autocmd FileType markdown,mkd call pencil#init()
+                                \ | call litecorrect#init()
+                                \ | setl spell spl=en_us fdl=4 noru nonu nornu
+                                \ | setl fdo+=search
+        autocmd Filetype git,gitsendemail,*commit*,*COMMIT* 
+                                \ call pencil#init({'wrap': 'hard', 'textwidth': 72})
+                                \ | call litecorrect#init() 
+                                \ | setl spell spl=en_us et sw=2 ts=2 noai
+        autocmd Filetype mail call pencil#init({'wrap': 'hard', 'textwidth': 60})
+                                \ | call litecorrect#init()
+                                \ | setl spell spl=en_us et sw=2 ts=2 noai nonu nornu
+        autocmd Filetype html,xml call pencil#init({'wrap': 'soft'})
+                                \ | call litecorrect#init()
+                                \ | setl spell spl=en_us et sw=2 ts=2
+    augroup END
+
+Configurable options for pencil#init() include: autoformat, concealcursor,
+conceallevel, cursorwrap, joinspaces, textwidth, and wrap. These are detailed
+above.
+
+==============================================================================
+15.2. Autoformat manual control                  *vim-pencil-autoformat-manual*
+
+The ‘autoformat’ feature affects HardPencil (hard line break) mode only.
+
+To suspend autoformat for the next Insert, see above.
+
+When you need to manually enable/disable autoformat for the current buffer,
+you can do so with a command:
+
+- PFormat - enable autoformat for buffer (can still be disabled via blacklisting)
+- PFormatOff - disable autoformat for buffer
+- PFormatToggle - toggle to enable if disabled, etc.
+
+You can map a key in your .vimrc to toggle Vim’s autoformat:
+
+    noremap <silent> <F7> :<C-u>PFormatToggle<cr>
+    inoremap <silent> <F7> <C-o>:PFormatToggle<cr>
+
+==============================================================================
+15.3. Autoformat blacklisting (& whitelisting)  *vim-pencil-autoformat-listing*
+
+The ‘autoformat’ feature affects HardPencil (hard line break) mode only.
+
+When editing formatted text, such as a table or code block, Vim’s autoformat
+will wreak havoc with the formatting. In these cases you will want autoformat
+suspended for the duration of the Insert.
+
+When entering Insert mode, pencil will determine the highlight group at the
+cursor position. If that group has been blacklisted, pencil will suspend
+autoformat for the Insert. For example, if editing a buffer of type
+‘markdown’, autoformat will be suspended if you invoke Insert mode from inside
+a markdownFencedCodeBlock highlight group.
+
+Blacklists are now declared by file type. The default blacklists (and
+whitelists) are declared in the plugin/pencil.vim module. Here’s an excerpt
+showing the configuration for the ‘markdown’ file type:
+
+    let g:pencil#autoformat_config = {
+          \   'markdown': {
+          \     'black': [
+          \       'htmlH[0-9]',
+          \       'markdown(Code|H[0-9]|Url|IdDeclaration|Link|Rule|Highlight[A-Za-z0-9]+)',
+          \       'markdown(FencedCodeBlock|InlineCode)',
+          \       'mkd(Code|Rule|Delimiter|Link|ListItem|IndentCode)',
+          \       'mmdTable[A-Za-z0-9]*',
+          \     ],
+          \     'white': [
+          \      'markdown(Code|Link)',
+          \     ],
+          \   },
+          [snip]
+          \ }
+
+The whitelist will override the blacklist and enable Vim’s autoformat if text
+that would normally be blacklisted doesn’t dominate the entire line. This
+allows autoformat to work with inline code and links.
+
+
+==============================================================================
+15.4. Auto-detecting wrap mode                       *vim-pencil-autodetect-wrap*
+
+If you didn’t explicitly specify a wrap mode during initialization, pencil
+will attempt to detect it.
+
+It will first look for a textwidth (or tw) specified in a modeline. Failing
+that, pencil will then sample lines from the start of the buffer.
+
+Detect via modeline
+
+    Will the wrap mode be detected accurately? Maybe. But you can improve its
+    chances by giving pencil an explicit hint.
+
+    At the bottom of this document is a odd-looking code:
+
+        <!-- vim: set tw=73 :-->
+
+    This is an optional ‘modeline’ that tells Vim to run the following command
+    upon loading the file into a buffer:
+
+        :set textwidth=73
+
+    It tells pencil to assume hard line breaks, regardless of whether or not
+    soft line wrap is the default editing mode for buffers of type ‘markdown’.
+
+    You explicitly specify soft wrap mode by specifying a textwidth of 0:
+
+        <!-- vim: set tw=0 :-->
+
+    Note that if the modelines feature is disabled (such as for security
+    reasons) the textwidth will still be set by this plugin.
+
+Detect via sampling 
+
+    If no modeline with a textwidth is found, pencil will sample the initial
+    lines from the buffer, looking for those excessively-long.
+
+    There are two settings you can add to your .vimrc to tweak this behavior.
+
+    The maximum number of lines to sample from the start of the buffer:
+
+        let g:pencil#softDetectSample = 20
+
+    Set that value to 0 to disable detection via line sampling.
+
+    When the number of bytes on a sampled line per exceeds this next value,
+    then pencil assumes soft line wrap.
+
+        let g:pencil#softDetectThreshold = 130
+
+    If no such lines found, pencil falls back to the default wrap mode.
+
+
+==============================================================================
+16. Contributing & Bug reports                        *vim-pencil-contributing*
+
+If you’ve spotted a problem or have an idea on improving pencil, please report
+it as an issue, or better yet submit a pull request.
+
+See https://github.com/preservim/vim-pencil for details
+
+==============================================================================
+17. Development                                          *vim-pencil-development*
+
+Github: https://github.com/preservim/vim-pencil
+
+For Contributors and their Github usernames please see the github repository
+
+==============================================================================
+18. License                                                 *vim-pencil-license*
+
+The MIT License
+http://www.opensource.org/licenses/mit-license.php
+
+Copyright (c) 2008-2010 Maxim Kim
+              2013-2017 Daniel Schemala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+
+ vim:tw=78:ts=8:ft=help

plugin/pencil.vim

@@ -1,17 +1,19 @@
 " ============================================================================
 " File:        pencil.vim
 " Description: vim-pencil plugin
-" Maintainer:  Reed Esau <github.com/reedes>
+" Maintainer:  preservim <https://github.com/preservim>
 " Created:     December 28, 2013
 " License:     The MIT License (MIT)
 " ============================================================================
-"
-if exists('g:loaded_pencil') || &cp | fini | en
+
+scriptencoding utf-8
+
+if exists('g:loaded_pencil') || &compatible | fini | en
 let g:loaded_pencil = 1
 
 " Save 'cpoptions' and set Vim default to enable line continuations.
-let s:save_cpo = &cpo
-set cpo&vim
+let s:save_cpoptions = &cpoptions
+set cpoptions&vim
 
 let s:WRAP_MODE_DEFAULT = -1
 let s:WRAP_MODE_OFF     = 0
@@ -31,7 +33,7 @@ fun! PencilMode()
     if b:pencil_wrap_mode ==# s:WRAP_MODE_SOFT
       return get(g:pencil#mode_indicators, 'soft', 'S')
     elsei b:pencil_wrap_mode ==# s:WRAP_MODE_HARD
-      if &fo =~ 'a'
+      if &formatoptions =~# 'a'
         return get(g:pencil#mode_indicators, 'auto', 'A')
       el
         return get(g:pencil#mode_indicators, 'hard', 'H')
@@ -76,9 +78,10 @@ if !exists('g:pencil#autoformat_config')
         \     'black': [
         \       'htmlH[0-9]',
         \       'markdown(Code|H[0-9]|Url|IdDeclaration|Link|Rule|Highlight[A-Za-z0-9]+)',
-        \       'markdown(FencedCodeBlock|InlineCode)',
-        \       'mkd(Code|Rule|Delimiter|Link|ListItem|IndentCode)',
+        \       'markdown(FencedCodeBlock|InlineCode|YamlHead)',
+        \       'mkd(Code|Rule|Delimiter|Link|ListItem|IndentCode|Snippet)',
         \       'mmdTable[A-Za-z0-9]*',
+        \       '^yaml*',
         \     ],
         \     'white': [
         \      'markdown(Code|Link)',
@@ -96,7 +99,8 @@ if !exists('g:pencil#autoformat_config')
         \   },
         \   'rst': {
         \     'black': [
-        \       'rst(CodeBlock|Directive|LiteralBlock|Sections)',
+        \       'rst(CodeBlock|Directive|ExDirective|LiteralBlock|Sections)',
+        \       'rst(Comment|Delimiter|ExplicitMarkup|SimpleTable)',
         \     ],
         \   },
         \   'tex': {
@@ -111,6 +115,16 @@ if !exists('g:pencil#autoformat_config')
         \       'txtCode',
         \     ],
         \   },
+        \   'pandoc': {
+        \     'black': [
+        \       '^pandoc.*Code.*',
+        \       'pandocHTML',
+        \       'pandocLaTeXMathBlock',
+        \       '^pandoc.*List.*',
+        \       '^pandoc.*Table.*',
+        \       'pandocYAMLHeader',
+        \     ],
+        \   }
         \ }
 en
 if !exists('g:pencil#autoformat_aliases')
@@ -168,20 +182,21 @@ en
 
 " Commands
 
-com -nargs=0 Pencil         call pencil#init({'wrap': 'on' })
-com -nargs=0 PencilOff      call pencil#init({'wrap': 'off' })
-com -nargs=0 NoPencil       call pencil#init({'wrap': 'off' })
-com -nargs=0 HardPencil     call pencil#init({'wrap': 'hard'})
-com -nargs=0 PencilHard     call pencil#init({'wrap': 'hard'})
-com -nargs=0 SoftPencil     call pencil#init({'wrap': 'soft'})
-com -nargs=0 PencilSoft     call pencil#init({'wrap': 'soft'})
-com -nargs=0 PencilToggle   call pencil#init({'wrap': 'toggle'})
-com -nargs=0 TogglePencil   call pencil#init({'wrap': 'toggle'})
-com -nargs=0 PFormat        call pencil#setAutoFormat(1)
-com -nargs=0 PFormatOff     call pencil#setAutoFormat(0)
-com -nargs=0 PFormatToggle  call pencil#setAutoFormat(-1)
+command-bar -nargs=0 Pencil         call pencil#init({'wrap': 'on' })
+command-bar -nargs=0 PencilOff      call pencil#init({'wrap': 'off' })
+command-bar -nargs=0 NoPencil       call pencil#init({'wrap': 'off' })
+command-bar -nargs=0 HardPencil     call pencil#init({'wrap': 'hard'})
+command-bar -nargs=0 PencilHard     call pencil#init({'wrap': 'hard'})
+command-bar -nargs=0 SoftPencil     call pencil#init({'wrap': 'soft'})
+command-bar -nargs=0 PencilSoft     call pencil#init({'wrap': 'soft'})
+command-bar -nargs=0 PencilToggle   call pencil#init({'wrap': 'toggle'})
+command-bar -nargs=0 TogglePencil   call pencil#init({'wrap': 'toggle'})
+command-bar -nargs=0 PFormat        call pencil#setAutoFormat(1)
+command-bar -nargs=0 PFormatOff     call pencil#setAutoFormat(0)
+command-bar -nargs=0 PFormatToggle  call pencil#setAutoFormat(-1)
 
 " NOTE: legacy commands have been disabled by default as of 31-Dec-15
+"       These will be removed entirely on 31-Dec-16
 if !exists('g:pencil#legacyCommands')
   let g:pencil#legacyCommands = 0
 en
@@ -192,7 +207,7 @@ if g:pencil#legacyCommands
   com -nargs=0 ShiftPencil   call pencil#setAutoFormat(-1)
 en
 
-let &cpo = s:save_cpo
-unlet s:save_cpo
+let &cpoptions = s:save_cpoptions
+unlet s:save_cpoptions
 
 " vim:ts=2:sw=2:sts=2