# vim-pencil
> “Rethinking Vim as a tool for writers”
- - -
- - -
# Features
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 wrapping _versus_ hard line breaks, supporting
both
* Auto-detects wrap mode via modeline if present
* Adjusts navigation key mappings to suit the wrap mode
* Creates undo points on common punctuation
* When using hard line breaks, enables autoformat while inserting text
* Buffer-scoped configuration (leaves your global settings alone)
Need spellcheck 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 apps available, including those that
specifically cater to writers, why use a programmer’s editor like Vim for
writing?
There are good reasons NOT to use Vim for writing:
* Primitive in certain respects (no WYSIWYG or proportionally spaced
characters, e.g.)
* A modal editor with a steep learning curve
* Time and effort to configure to your needs
But Vim offers a unique editing environment not matched by other writing
tools:
* Hands 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
## Installation
Install using Pathogen, Vundle, Neobundle, or your favorite Vim package
manager.
_For those new to Vim: before installing this plugin, you should first
work through one of the many tutorials available to get comfortable with
the basics of Vim._
## Configuration
### Hard line breaks or soft line wrapping?
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`:
```vim
let g:pencil#wrapModeDefault = 'hard' " or 'soft'
augroup pencil
autocmd!
autocmd FileType markdown 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 wrapping 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` - mode for soft line wrapping
* `HardPencil` - mode for hard line breaks
* `DropPencil` - removes navigation mappings and restores buffer to global settings
* `TogglePencil` - if off, enables with detection; if on, turns off
Optionally, you can map to keys in your `.vimrc`:
```vim
nmap ps :SoftPencil
nmap ph :HardPencil
nmap pd :DropPencil
nmap pt :TogglePencil
```
### Automatic formatting
_This ‘autoformat’ feature affects **HardPencil** mode only._
When in **HardPencil** mode, Vim’s autoformat feature will be enabled by
default in Insert mode and can offer many of the same benefits as soft
line wrapping. 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` - enables if disabled, etc.
Or optionally map to keys in your `.vimrc`:
```vim
nnoremap pa :AutoPencil
nnoremap pm :ManualPencil
nnoremap pp :ShiftPencil
```
To set the default behavior, add to your `.vimrc`:
```vim
let g:pencil#autoformat = 1 " 0=manual, 1=auto
```
You can override this default during initialization, as in:
```vim
let g:pencil#wrapModeDefault = 'soft'
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` - format current paragraph
* `vipJ` - unformat current paragraph
* `ggVGgq` - format all paragraphs in buffer
* `:%norm vipJ` - unformat all paragraphs in buffer
Optionally, you can map these sequences to underutilized keys in your
`.vimrc`:
```vim
nnoremap Q gqip
nnoremap K vipJ
nnoremap Q ggVGgq
nnoremap K :%norm vipJ
```
### 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`:
```vim
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:
```vim
let g:pencil#joinspaces = 0 " 0=one_space, 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`:
```vim
let g:pencil#cursorwrap = 0 " 0=disable, 1=enable
```
NOTE: temporarily disabled by default while I research related bug in
vim-quotable.
## Auto-detection via modeline
Will the wrapping mode be detected accurately? Maybe. But you can improve
its chances by giving it a hint.
At the bottom of this document is a strange code:
```
```
This is a ‘modeline’ that tells Vim to run the following command upon
loading this file into a buffer:
```vim
:set textwidth=74
```
That’s a strong hint to this plugin that we should assume hard line
endings, regardless of whether or not soft wrapping is the default editing
mode for files of type ‘markdown’.
If it’s `0`, then pencil assumes you want soft line wrapping.
```
```
For more details:
```vim
:help modeline
```
Note that even if the modelines feature is disabled (such as for security
reasons) the textwidth may nevertheless be set by this plugin.
## See also
* [To Vim](http://ianhocking.com/2013/11/17/to-vim/) - Writer and psychologist Ian Hocking on using Vim for writing
* [Vim Training Class - Basic motions and commands](https://www.youtube.com/watch?v=Nim4_f5QUxA) - video tutorial by Shawn Biddle
* [Vim for Writers](http://therandymon.com/woodnotes/vim-for-writers/vimforwriters.html) - guide to the basics geared to writers
* [Vim-related books](http://iccf-holland.org/click5.html) - collection of books on learning Vim
* [pencil at vim.org](http://www.vim.org/scripts/script.php?script_id=4824)
If you like this plugin, you might like these others from the same author:
* [vim-lexical](http://github.com/reedes/vim-lexical) - Building on Vim’s spell-check and thesaurus/dictionary completion
* [vim-litecorrect](http://github.com/reedes/vim-litecorrect) - Lightweight auto-correction for Vim
* [vim-quotable](http://github.com/reedes/vim-quotable) - extends Vim to support typographic (‘curly’) quotes
* [vim-thematic](http://github.com/reedes/vim-thematic) — Conveniently manage Vim’s appearance to suit your task and environment
* [vim-colors-pencil](http://github.com/reedes/vim-colors-pencil) — A color scheme for Vim inspired by IA Writer
## 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.
```
```