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 files in text, markdown, textile, and other prose-oriented file types
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, incl. deletion via line <C-U> and word <C-W>
When using hard line breaks, enables autoformat while inserting text
Buffer-scoped configuration (with a few minor exceptions, pencil preserves your global settings)
Pure Vimscript with no dependencies
Support for Vim’s Conceal feature to hide _ and * characters when displaying _italic_, **bold** and ***bold italic*** styled text in Markdown

Need spell-check and other features? Vim is about customization. To complete your editing environment, learn to configure Vim and draw upon its rich ecosystem of plugins.

Why use Vim for 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 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)

Installation

Install using Pathogen, Vundle, Neobundle, or your favorite Vim package manager.

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.

Configuration

Hard line breaks or soft line 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. Add to your .vimrc:

set nocompatible
filetype plugin on       " may already be in your .vimrc

let g:pencil#wrapModeDefault = 'hard'   " or 'soft'

augroup pencil
  autocmd!
  autocmd FileType markdown,mkd call pencil#init()
  autocmd FileType textile call pencil#init()
  autocmd FileType text call pencil#init({'wrap': 'hard'})
augroup END

In the example above, for files of type markdown and textile, this plugin will auto-detect the line wrap approach, with hard as the default. But for files of type text, it will always initialize with hard line break mode.

Commands

Because auto-detect might not work as intended, you can invoke a command to set the behavior for the current buffer:

SoftPencil - enable soft line wrap mode
HardPencil - enable hard line break mode
NoPencil - removes navigation mappings and restores buffer to global settings
TogglePencil - if on, turns off; if off, enables with detection

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

nnoremap <silent> <leader>ps :SoftPencil<cr>
nnoremap <silent> <leader>ph :HardPencil<cr>
nnoremap <silent> <leader>pn :NoPencil<cr>
nnoremap <silent> <leader>pt :TogglePencil<cr>

Automatic formatting

This ‘autoformat’ feature affects HardPencil mode only.

When in HardPencil mode, Vim’s autoformat feature will be enabled by default while in Insert mode and can offer many of the same benefits as soft line wrap. But autoformat will cause havoc when editing anything but paragraphs of words, such as a code block or table. In these cases you will need to disable it, at least temporarily, via a command:

AutoPencil - enables autoformat
ManualPencil - disables autoformat
ShiftPencil - toggle to enable if disabled, etc.

Or optionally map to keys in your .vimrc:

nnoremap <silent> <leader>pa :AutoPencil<cr>
nnoremap <silent> <leader>pm :ManualPencil<cr>
nnoremap <silent> <leader>pp :ShiftPencil<cr>

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.

Manual formatting

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 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
nnoremap <silent> K vipJ
nnoremap <silent> <leader>Q ggVGgq
nnoremap <silent> <leader>K :%norm vipJ<cr>

Default textwidth

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

Sentence spacing

By default, when formatting 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

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)

Concealing markup in Markdown

Syntaxes such as tpope/vim-markdown support Vim’s Conceal feature, where the _ and * characters will be hidden automatically when displaying _italic_, **bold** and ***bold italic*** styled text. To enable, set the following to 2 in your .vimrc:

let g:pencil#conceallevel = 2     " 0=disable (def), 1=onechar, 2=autohide

A couple of things you will need:

a font (such as Cousine) featuring the italic, bold, and bold italic style variants
a colorscheme (such as reedes/vim-colors-pencil) which supports the Markdown-specific highlight groups.

Terminal users: sadly, the bold italic style won’t be available. Consult your terminal’s documentation to configure your terminal to support bold and italic styles.

For more details on Vim’s Conceal feature, see:

:help conceallevel

Auto-detecting wrap mode

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.

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=74 :-->

This is an optional ‘modeline’ that tells Vim to run the following command upon loading the file into a buffer:

:set textwidth=74

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.

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.

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 mentioned earlier:

let g:pencil#wrapModeDefault = 'hard'   " or 'soft'

Future development

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

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

README.markdown Unescape Escape

vim-pencil

Features