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

Added support for :help vim-pencil (#91)

Browse Source
This commit is contained in:
Ian Stanley
2020-07-29 22:14:39 +01:00
committed by GitHub
parent 0945852760
commit dad5a3626a
1 changed files with 651 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

651
doc/vim-pencil.txt Normal file
View File

@@ -0,0 +1,651 @@
*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.
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.
Vundle:
Add to your .vimrc and save:
Plugin 'reedes/vim-pencil'
…then run the following in Vim:
:source %
:PluginInstall
Plug:
Add to your .vimrc and save:
Plug 'reedes/vim-pencil'
…then run the following in Vim:
:source %
:PlugInstall
NeoBundle:
Add to your .vimrc and save:
NeoBundle 'reedes/vim-pencil'
…then run the following in Vim:
:source %
:NeoBundleInstall
Pathogen:
Run the following in a terminal:
cd ~/.vim/bundle
git clone https://github.com/reedes/vim-pencil
------------------------------------------------------------------------------
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/reedes/vim-pencil for details
==============================================================================
17. Development *vim-pencil-development*
Github: https://github.com/reedes/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