Merge pull request #74 from actionless/patch-1

markdown comment syntax

README.markdown

@@ -21,9 +21,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>`
-* 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
@@ -31,6 +28,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 +57,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,8 +66,8 @@ 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)
 
@@ -144,12 +147,26 @@ git clone https://github.com/reedes/vim-pencil
 
 # 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 +199,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,32 +215,18 @@ 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 powerful autoformat
+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.
 
@@ -252,11 +255,11 @@ but `text` buffers will have autoformat disabled.
 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
+**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
+**Second**, where blacklisting falls short, you can optionally map
 a buffer-scoped ‘modifier’ key to suspend autoformat during the next
 Insert:
 
@@ -268,6 +271,8 @@ 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).
 
@@ -276,16 +281,17 @@ implemented and configured).
 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
-* `vapJgwip` - merge two paragraphs (current and next) and format
+* `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`:
 
 ```vim
-nnoremap <silent> Q gwip
-nnoremap <silent> <leader>Q vapJgwip
+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
@@ -296,9 +302,10 @@ soft line wrap.
 
 ## 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
@@ -327,13 +334,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)
 ```
 
@@ -355,10 +362,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 [reedes/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
@@ -413,11 +420,55 @@ has not been initialized.
 
 ### 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
@@ -439,24 +490,25 @@ 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
+_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
+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:
+You can map a key in your `.vimrc` to toggle Vim’s autoformat:
 
 ```vim
 noremap <silent> <F7> :<C-u>PFormatToggle<cr>
@@ -465,20 +517,18 @@ 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 suspend autoformat for the Insert. 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 suspended.
-
-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 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
@@ -502,22 +552,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 be suspended for the Insert.
-
-The whitelist will override the blacklist and allow Vim’s autoformat to
-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.
+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
 
@@ -538,7 +584,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`:
 
@@ -551,12 +598,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
@@ -581,13 +628,12 @@ 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:
 
@@ -599,9 +645,8 @@ Other plugins of specific interest to writers:
 
 [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/
+[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/
@@ -612,10 +657,24 @@ Other plugins of specific interest to writers:
 
 Markdown syntax plugins
 
-* [tpope/vim-markdown][tvm] - the latest version of the syntax plugin that ships with Vim
+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:
+
 * [plasticboy/vim-markdown][pvm]
 * [gabrielelana/vim-markdown][gvm]
-* [mattly/vim-markdown-enhancements][mvme] - highlighting for tables and footnotes
+
+Note that the plasticboy and gabrielelana plugins may incorrectly
+reformat bulleted lists when Vim’s autoformat is active in _pencil_’s
+HardPencil mode.
 
 [tvm]: http://github.com/tpope/vim-markdown
 [pvm]: http://github.com/plasticboy/vim-markdown
@@ -629,7 +688,7 @@ If you find the _pencil_ plugin useful, check out these others by [@reedes][re]:
 * [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
@@ -654,9 +713,7 @@ with its own Markdown variant.
 
 # 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, or better yet submit a pull request.
 
-```
 <!-- vim: set tw=73 :-->
-```

autoload/pencil.vim

@@ -411,6 +411,10 @@ fun! pencil#init(...) abort
     vn <buffer> <silent> k 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>'  )
@@ -422,6 +426,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>

plugin/pencil.vim

@@ -77,7 +77,7 @@ if !exists('g:pencil#autoformat_config')
         \       '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)',
+        \       'mkd(Code|Rule|Delimiter|Link|ListItem|IndentCode|Snippet)',
         \       'mmdTable[A-Za-z0-9]*',
         \     ],
         \     'white': [
@@ -111,6 +111,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')
@@ -182,6 +192,7 @@ com -nargs=0 PFormatOff     call pencil#setAutoFormat(0)
 com -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