Rethinking Vim as a tool for writers

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.

• 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>
• When using hard line breaks, pencil enables Vim’s autoformat while inserting text, except for tables and code blocks where you won’t want it
• 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

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.

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 to suit 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)
• Your problem with Vim is that you don't grok vi (December 2011)
• Intro to Vim's Grammar (January 2013)
• Why Atom Can’t Replace Vim, Learning the lesson of vi (March 2014)

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.

Add to your .vimrc and save:

Plugin 'reedes/vim-pencil'

…then run the following in Vim:

:source %
:PluginInstall

For Vundle version < 0.10.2, replace Plugin with Bundle above.

Add to your .vimrc and save:

Plug 'reedes/vim-pencil'

…then run the following in Vim:

:source %
:PlugInstall

Add to your .vimrc and save:

NeoBundle 'reedes/vim-pencil'

…then run the following in Vim:

:source %
:NeoBundleInstall

Run the following in a terminal:

cd ~/.vim/bundle
git clone https://github.com/reedes/vim-pencil

Initializing pencil by FileType is optional, though doing so will automatically set up your buffers for editing prose.

Add support for your desired filetypes 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

For other prose-oriented plugins, consult the See also section below.

For more details, see the advanced initialization 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 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 files 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.

You can enable, disable, and toggle pencil as a command:

• Pencil - initialize pencil with auto-detect for the current buffer
• PencilOff (or NoPencil) - removes navigation mappings and restores buffer to global settings
• PencilToggle (or TogglePencil) - 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)

The ‘autoformat’ feature affects HardPencil (hard line break) mode only.

When inserting text while in HardPencil mode, Vim’s autoformat feature will be enabled by default and can offer many of the same benefits as soft line wrap.

One useful exception (aka 'blacklisting'): if used with popular prose-oriented syntax plugins, pencil will not enable autoformat when you enter Insert mode from inside a code block or table. (See the advanced section below for more details on the blacklisting feature.)

Where you need to manually enable/disable autoformat for the current buffer, you can do so with a command:

• PFormat - allows autoformat to be enabled (if not blacklisted)
• PFormatOff - prevents autoformat from enabling (blacklist all)
• PFormatToggle - toggle to allow if off, etc.

To set the default behavior, add to your .vimrc:

let g:pencil#autoformat = 1      " 0=manual, 1=auto (def)

You can override this default during initialization, as in:

augroup pencil
  autocmd!
  autocmd FileType text call pencil#init({'wrap': 'hard', 'autoformat': 0})
  ...
augroup END

...where by default, files of type text will use hard line endings, but with autoformat disabled.

Note that you need not rely on autoformat exclusively and can manually reformat paragraphs with standard Vim commands:

• gqip or gwip - format current paragraph
• vipJ - unformat (i.e., join all lines with hard line breaks) in current paragraph
• ggVGgq or :g/^/norm gqq - format all paragraphs in buffer
• :%norm vipJ - unformat all paragraphs in buffer

Optionally, you can map these operations to underutilized keys in your .vimrc:

nnoremap <silent> Q gwip

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:

let g:pencil#textwidth = 74

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

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)

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=onechar, 2=hidechar, 3=hideall (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

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.

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()}'

If you don’t like the default indicators, you can specify different ones:

let g:pencil#mode_indicators = {'hard': '␍', 'soft': '⤸', 'off': '',}

Note that PencilMode() will return blank for buffers in which pencil has not been initialized.

Configurable options for pencil#init() include: autoformat, concealcursor, conceallevel, cursorwrap, joinspaces, textwidth, and wrap. These are detailed above.

You can override pencil and other configuration settings when initializing:

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

Alternatives include after/ftplugin modules as well as refactoring initialization statements into a function.

The ‘autoformat’ feature affects HardPencil (hard line break) mode only.

When editing formatted text, such as a table or code block, autoformat will wreak havoc with the formatting. In these cases you will want to temporarily deactivate autoformat, such as with the PFormatOff or PFormatToggle commands described above. However, in most cases, you won’t need to do this.

pencil will detect the syntax highlight group at the cursor position to determine whether or not autoformat should be activated.

If autoformat is on, it will be activated at the time you enter Insert mode provided that the syntax highlighting group at the cursor position is not in the blacklist. The current blacklist is:

let g:pencil#autoformat_blacklist = [
      \ 'markdownCode',
      \ 'markdownH[0-9]',
      \ 'markdownUrl',
      \ 'markdownIdDeclaration',
      \ 'markdownLink',
      \ 'markdownRule',
      \ 'markdownHighlight[A-Za-z0-9]+',
      \ 'mkdCode',
      \ 'mkdRule',
      \ 'mkdDelimiter',
      \ 'mkdLink',
      \ 'mkdIndentCode',
      \ 'htmlH[0-9]',
      \ 'markdownFencedCodeBlock',
      \ 'markdownInlineCode',
      \ 'mmdTable[A-Za-z0-9]*',
      \ 'txtCode',
      \ 'rstCodeBlock',
      \ 'rstDirective',
      \ 'rstLiteralBlock',
      \ 'rstSections',
      \ 'texBeginEndName',
      \ 'texDelimiter',
      \ 'texDocType',
      \ 'texInputFile',
      \ 'texMath',
      \ 'texRefZone',
      \ 'texSection$',
      \ 'texTitle',
      \ 'asciidocAttribute',
      \ 'asciidocList',
      \ 'asciidocLiteral',
      \ 'asciidoc[A-Za-z]*Block',
      \ 'asciidoc[A-Za-z]*Macro',
      \ 'asciidoc[A-Za-z]*Title',
      \ ]

WARNING: the implementation of this blacklist may be changing in the future.

There’s also a whitelist to override the blacklist. See code for details.

You can override this in your .vimrc. Additions to defaults with good use cases are welcome.

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.

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 files 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.

If no modeline with a textwidth is found, pencil will sample the initial lines from the file, 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:

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.

• To Vim - Writer and psychologist Ian Hocking on using Vim for writing
• Vim Training Class - Basic motions and commands - video tutorial by Shawn Biddle
• Vim for Writers - guide to the basics geared to writers

Other plugins of specific interest to writers:

• tpope/vim-abolish - search for, substitute, and abbr. multiple variants of a word
• tommcdo/vim-exchange - easy text exchange operator for Vim
• junegunn/limelight.vim - focus mode that brightens current paragraph
• junegunn/goyo.vim - distraction-free editing mode

Markdown syntax plugins

• tpope/vim-markdown - the latest version of the syntax plugin that ships with Vim
• plasticboy/vim-markdown
• gabrielelana/vim-markdown
• mattly/vim-markdown-enhancements - highlighting for tables and footnotes

If you find the pencil plugin useful, check out these others by @reedes:

• vim-colors-pencil - color scheme for Vim inspired by IA Writer
• vim-lexical - building on Vim’s spell-check and thesaurus/dictionary completion
• vim-litecorrect - lightweight auto-correction for Vim
• vim-one - make use of Vim’s +clientserver capabilities
• vim-textobj-quote - extends Vim to support typographic (‘curly’) quotes
• vim-textobj-sentence - improving on Vim's native sentence motion command
• vim-thematic - modify Vim’s appearance to suit your task and environment
• vim-wheel - screen-anchored cursor movement for Vim
• vim-wordy - uncovering usage problems in writing

Unimpressed by pencil? vim-pandoc offers prose-oriented features with its own Markdown variant.

If you’ve spotted a problem or have an idea on improving this plugin, please post it to the github project issue page or submit a pull request.

<!-- vim: set tw=73 :-->