From 99e2499500677371e3d4ae4062923db8e648c5c6 Mon Sep 17 00:00:00 2001 From: Reed Esau Date: Thu, 18 Aug 2016 14:10:42 -0600 Subject: [PATCH] Improve wording and formatting. --- README.markdown | 61 ++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/README.markdown b/README.markdown index d9a084c..eb433e7 100644 --- a/README.markdown +++ b/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 `` and word `` -* 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. @@ -198,11 +201,11 @@ 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. +For buffers of type `text`, it will initialize with hard line breaks, +even if auto-detect might suggest soft line wrap. ## Commands @@ -276,7 +279,7 @@ 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 +* `gqip` or `gwip` - format current paragraph (see `:help gq`) * `vapJgwip` - merge two paragraphs (current and next) and format * `ggVGgq` or `:g/^/norm gqq` - format all paragraphs in buffer @@ -284,7 +287,8 @@ Optionally, you can map these operations to underutilized keys in your `.vimrc`: ```vim -nnoremap Q gwip +nnoremap Q gqip +xnoremap Q gq nnoremap Q vapJgwip ``` @@ -470,15 +474,13 @@ 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,14 +504,9 @@ 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 @@ -517,7 +514,8 @@ 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 +536,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 +550,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 @@ -654,8 +653,8 @@ 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. ```