box.matto.nl
Enjoying Open Source Software

Posted:

Use par in vi or vim to create nice formatted text paragraphs

Par with vi or vim

Jirka pointed in his phlog to an article of kvothe on the use of par to create nicely formatted flat text files in vim.

See: gopher://sdf.org:70/0/users/kvothe/phlog/2018/02/07-text-formatting-is-beautiful

It turns out, it is easy to use par as an external formatter in vi or vim. Although I did know of the existence of par, I did not know that it could be used this way directly in vi and vim. It seems a good idea to use this setup.

If you want to use par as external formatter for gopher posts only, you want to have a separate .vimrc for that. To facilitate this, change the configuration of vim to enable the use of local .vimrc files. This allows the use of a .vimrc file in a directory, to configure vim specific for the files in this directory.

Set exrc to enable use of local .vimrc files

Normally, vim reads your $HOME/.vimrc file. It is however possible to use per directory .vimrc files. This adds a security risk, because this will result in vim executing commands from any .vimrc file. Enabling the use of per directory .vimrc is done with the exrc command:

set exrc

Insert this line into the .vimrc file in your $HOME directory.

Configure the local .vimrc to use par

Vim is configured to use par as an external formatter with "set formatprg=par". Additional switches can be added with, like "set formatprg=par\ -w68", which means that par will reformat to a text width of 68 chars. In his article, kvothe proposes the following setting:

set formatprg=par\ -w76ej

This tells par to format the text to a text width of 76 chars, removes superfluous lines (e), and justify the text (j).

Create a local .vimrc and put this line in it, now you can format your paragraphs with gqip, or use gq on a visual block. You can mark a visual block with Ctr-V at one end and "walk" to the other end. There, issue the command "gq".

Use par with vi (not vim)

The manual page of par tells us how to use par with standard vi commands. So if you don't want to use vim or the system you are working doesn't provide vim, than you can still use par to create beautiful paragraphs.

First we have to add some lines to your $HOME/.exrc file:

set shell=/bin/sh
map ** {!}par^M} 
map *^V {!}par

The ^M and ^V are special characters, in vi your create the ^M with Cltr-V Cltr-M and the ^V with Ctrl-V Cltr-V. There are two spaces after the ^V in the last line.

When you have added these lines to your .exrc, you can use par to format your file by typing "**" (without quotes) in command mode. If you want to add some switches to par, you use the second option, typing "* " (a star followed by a space) and than type the commands, like 76ej from our example above. Of course, you can change the mapping of e.g., **, to use your favorite par switches.

Tags:

⇽ Running a virtual machine on OpenBSD vmm My adventures in using Taskwarrior ⇾