m-vim_plugins/vim-pencil
1
0
Fork 0
mirror of https://github.com/preservim/vim-pencil.git synced 2025-11-16 05:43:47 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve wording and formatting.

Browse Source
This commit is contained in:
Reed Esau
2016-08-18 14:10:42 -06:00
parent f5f456ccdc
commit 99e2499500
1 changed files with 30 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
README.markdown
View File

@@ -21,9 +21,6 @@ smooth the path to writing prose.
* Adjusts navigation key mappings to suit the wrap mode * Adjusts navigation key mappings to suit the wrap mode
* Creates undo points on common punctuation during Insert mode, including * Creates undo points on common punctuation during Insert mode, including
deletion via line `<C-U>` and word `<C-W>` 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 * Buffer-scoped configuration (with a few minor exceptions, _pencil_ preserves
your global settings) your global settings)
* Support for Vim’s Conceal feature to hide markup defined by Syntax plugins * 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 * Support for display of mode indicator (`␍` and `⤸`, e.g.) in the status line
* Pure Vimscript with no dependencies * 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 Need spell-check, distraction-free editing, and other features? Vim is about
customization. To complete your editing environment, learn to configure Vim and customization. To complete your editing environment, learn to configure Vim and
draw upon its rich ecosystem of plugins. draw upon its rich ecosystem of plugins.
@@ -198,11 +201,11 @@ augroup pencil
augroup END 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. 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 For buffers of type `text`, it will initialize with hard line breaks,
if auto-detect might suggest soft line wrap. even if auto-detect might suggest soft line wrap.
## Commands ## Commands
@@ -276,7 +279,7 @@ implemented and configured).
Note that you need not rely on Vim’s autoformat exclusively and can Note that you need not rely on Vim’s autoformat exclusively and can
manually reformat paragraphs with standard Vim commands: 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 * `vapJgwip` - merge two paragraphs (current and next) and format
* `ggVGgq` or `:g/^/norm gqq` - format all paragraphs in buffer * `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`: `.vimrc`:
```vim ```vim
nnoremap <silent> Q gwip nnoremap <silent> Q gqip
xnoremap <silent> Q gq
nnoremap <silent> <leader>Q vapJgwip nnoremap <silent> <leader>Q vapJgwip
``` ```
@@ -470,15 +474,13 @@ only._
When editing formatted text, such as a table or code block, Vim’s 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 autoformat will wreak havoc with the formatting. In these cases you will
want to suspend autoformat for the Insert. However, in most cases, you want autoformat suspended for the duration of the Insert.
won’t need to do this.
_pencil_ will detect the syntax highlight group at the cursor position to When entering Insert mode, _pencil_ will determine the highlight group at
determine whether or not autoformat should be suspended. the cursor position. If that group has been blacklisted, _pencil_ will
suspend autoformat for the Insert. For example, if editing a buffer of
If you haven’t explicitly disabled autoformat, it will be suspended at type ‘markdown’, autoformat will be suspended if you invoke Insert mode
the time you enter Insert mode provided that the syntax highlighting from inside a `markdownFencedCodeBlock` highlight group.
group at the cursor position is in the blacklist.
Blacklists are now declared by file type. The default blacklists (and Blacklists are now declared by file type. The default blacklists (and
whitelists) are declared in the `plugin/pencil.vim` module. Here’s an 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 The whitelist will override the blacklist and enable Vim’s autoformat if
mode from inside a `markdownFencedCodeBlock` highlight group, then Vim’s text that would normally be blacklisted doesn’t dominate the entire line.
autoformat will be suspended for the Insert. This allows autoformat to work with `inline` code and links.
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.
### Auto-detecting wrap mode ### 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. _pencil_ will attempt to detect it.
It will first look for a `textwidth` (or `tw`) specified in a modeline. 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 #### 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 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`: 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 #### Detect via sampling
If no modeline with a textwidth is found, _pencil_ will sample the initial If no modeline with a textwidth is found, _pencil_ will sample the
lines from the file, looking for those excessively-long. initial lines from the buffer, looking for those excessively-long.
There are two settings you can add to your `.vimrc` to tweak this behavior. 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 ```vim
let g:pencil#softDetectSample = 20 let g:pencil#softDetectSample = 20
@@ -654,8 +653,8 @@ with its own Markdown variant.
# Future development # Future development
If you’ve spotted a problem or have an idea on improving _pencil_, If you’ve spotted a problem or have an idea on improving _pencil_, please
please report it as an issue, or better yet submit a pull request. report it as an issue, or better yet submit a pull request.
``` ```
<!-- vim: set tw=73 :--> <!-- vim: set tw=73 :-->