New optional key mapping to suspend autoformat #48

When using hard line break mode, autoformat is enabled by default.

Blacklisting is the existing mechanism to suspend autoformat for code blocks. You can now optionally map a buffer-scoped 'modifier' key to suspend autoformat for the Insert.

Also simplified README by moving things to the advanced section.

README.markdown

@@ -21,9 +21,9 @@ 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 (**NEW: blacklisting now based on filetype**)
+* 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.
 * 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
@@ -66,11 +66,13 @@ tool in expressing yourself. For more details on vi-style editing, see...
 * [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/
 [wa]: https://medium.com/p/433852f4b4d1
+[lovn]: http://allsyed.com/language-of-vim-neovim/
 
 # Installation
 
@@ -221,26 +223,14 @@ to set the behavior for the current buffer:
 _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:
@@ -248,38 +238,62 @@ 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.
+
+[**NEW**] 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.
+
+(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
+* `vapJgwip` - 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> <leader>Q vapJgwip
 ```
 
+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
@@ -374,7 +388,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': '',}
@@ -427,6 +442,27 @@ augroup END
 Alternatives include `after/ftplugin` modules as well as refactoring initialization
 statements into a function.
 
+### Autoformat manual control
+
+_The ‘autoformat’ feature affects *HardPencil* (hard line break) mode
+only._
+
+To suspend autoformat for the next Insert, see above.
+
+Where 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
@@ -434,16 +470,15 @@ 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
+want to suspend autoformat for the Insert. However, in most cases, you
 won’t need to do this.
 
 _pencil_ will detect the syntax highlight group at the cursor position to
-determine whether or not autoformat should be activated.
+determine whether or not autoformat should be suspended.
 
-If you haven’t explicitly disabled autoformat, it will be activated at
+If you haven’t explicitly disabled autoformat, it will be suspended at
 the time you enter Insert mode provided that the syntax highlighting
-group at the cursor position is _not_ in the blacklist.
+group at the cursor position is in the blacklist.
 
 Blacklists are now declared by file type. The default blacklists (and
 whitelists) are declared in the `plugin/pencil.vim` module. Here’s an
@@ -469,12 +504,12 @@ 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.
+autoformat will be suspended for the Insert.
 
 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.
+be avoid suspension 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
 
@@ -544,13 +579,32 @@ If no such lines found, _pencil_ falls back to the default wrap mode.
 * [Vim Training Class - Basic motions and commands][tc] - video tutorial by Shawn Biddle
 * [Vim for Writers][vw] - guide to the basics geared to writers
 
+Bloggers and developers discuss _pencil_ and its brethern:
+
+* [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
+* [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
 
+[vd]: https://github.com/danielbmarques/vim-ditto
+[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/
+[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
@@ -600,8 +654,8 @@ with its own Markdown variant.
 
 # Future development
 
-If you’ve spotted a problem or have an idea on improving this plugin,
-please post it to the github project issue page or submit a pull request.
+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.
 
 ```
 <!-- vim: set tw=73 :-->

autoload/pencil.vim

@@ -56,6 +56,12 @@ 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
 
+  " 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:ft = get(g:pencil#autoformat_aliases, &ft, &ft)
   let l:af_cfg = get(g:pencil#autoformat_config, l:ft, {})
   let l:black = get(l:af_cfg, 'black', [])
@@ -149,7 +155,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
@@ -180,6 +186,9 @@ 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
@@ -232,6 +241,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
@@ -243,7 +260,7 @@ fun! pencil#init(...) abort
       setl breakat-=@         " avoid breaking at email addresses
     en
 
-    if has('syntax')
+    if exists('&colorcolumn')
       setl colorcolumn=0      " doesn't align as expected
     en
   el
@@ -255,7 +272,7 @@ fun! pencil#init(...) abort
       setl breakat<
     en
 
-    if has('syntax')
+    if exists('&colorcolumn')
       setl colorcolumn<
     en
   en
@@ -421,7 +438,14 @@ fun! pencil#init(...) abort
     ino <buffer> : :<c-g>u
     ino <buffer> <c-u> <c-g>u<c-u>
     ino <buffer> <c-w> <c-g>u<c-w>
-    ino <buffer> <cr> <c-g>u<cr>
+
+    " map <cr> only if not already mapped
+    if empty(maparg('<cr>', 'i'))
+      ino <buffer> <cr> <c-g>u<cr>
+      let b:pencil_cr_mapped = 1
+    el
+      let b:pencil_cr_mapped = 0
+    en
   el
     sil! iu <buffer> .
     sil! iu <buffer> !
@@ -431,7 +455,11 @@ fun! pencil#init(...) abort
     sil! iu <buffer> :
     sil! iu <buffer> <c-u>
     sil! iu <buffer> <c-w>
-    sil! iu <buffer> <cr>
+
+    " unmap <cr> only if we mapped it ourselves
+    if exists('b:pencil_cr_mapped') && b:pencil_cr_mapped
+      sil! iu <buffer> <cr>
+    en
   en
 endf
 

plugin/pencil.vim

@@ -101,7 +101,7 @@ if !exists('g:pencil#autoformat_config')
         \   },
         \   'tex': {
         \     'black': [
-        \       'tex(BeginEndName|Delimiter|DocType|InputFile|Math|RefZone|Title)',
+        \       'tex(BeginEndName|Delimiter|DocType|InputFile|Math|RefZone|Statement|Title)',
         \       'texSection$',
         \     ],
         \     'enforce-previous-line': 1,
@@ -181,9 +181,9 @@ com -nargs=0 PFormat        call pencil#setAutoFormat(1)
 com -nargs=0 PFormatOff     call pencil#setAutoFormat(0)
 com -nargs=0 PFormatToggle  call pencil#setAutoFormat(-1)
 
-" NOTE: legacy commands will be disabled by default on 31-Dec-15
+" NOTE: legacy commands have been disabled by default as of 31-Dec-15
 if !exists('g:pencil#legacyCommands')
-  let g:pencil#legacyCommands = 1
+  let g:pencil#legacyCommands = 0
 en
 if g:pencil#legacyCommands
   com -nargs=0 DropPencil    call pencil#init({'wrap': 'off' })