From dad5a3626ab68039f2676c46e7a1635e0669cc63 Mon Sep 17 00:00:00 2001 From: Ian Stanley Date: Wed, 29 Jul 2020 22:14:39 +0100 Subject: [PATCH] Added support for :help vim-pencil (#91) --- doc/vim-pencil.txt | 651 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 651 insertions(+) create mode 100644 doc/vim-pencil.txt diff --git a/doc/vim-pencil.txt b/doc/vim-pencil.txt new file mode 100644 index 0000000..2f0d0ec --- /dev/null +++ b/doc/vim-pencil.txt @@ -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 and word +- 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 Q gqap + xnoremap Q gq + nnoremap 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 Q gqap + xnoremap Q gq + nnoremap Q vapJgqap + + " force top correction on most recent misspelling + nnoremap [s1z= + inoremap u[s1z=`]Au + + " replace common punctuation + iabbrev -- – + iabbrev --- — + iabbrev << « + iabbrev >> » + + " open most folds + setlocal foldlevel=6 + + " replace typographical quotes + (reedes/vim-textobj-quote) + map qc ReplaceWithCurly + map qs ReplaceWithStraight + + " highlight words + (reedes/vim-wordy) + noremap :NextWordy + xnoremap :NextWordy + inoremap :NextWordy + + 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 :PFormatToggle + inoremap :PFormatToggle + +============================================================================== +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: + + + + 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: + + + + 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