Formatting text with par
‘Do one thing and do it well’ is the principle of the Unix toolkit. Editing text is a broad domain, and there are many related tasks with which it overlaps. Vim acknowledges this by enabling certain tasks to be outsourced to external programs which do that one thing, and do it well. This episode will demonstrate how the par program can be used for formatting text.
I’ll be running my Core Vim Class online on Thursday, December 5th. Tickets cost $255, but you can get the earlybird discount of $230 if you buy yours before November 29th. The price includes an exclusive screencast that summarises the material from the class.
Par was written by Adam Costello in 1993, aiming to do one narrow task: reformat a single paragraph that might have a border on either side. The documentation is terse, and the author apologises for the implementation being unclean. Nevertheless, the program is stable, portable, and most important of all, extremely useful.
formatprg option allows you to specify an external program that will be called when you run the
gq command. The simplest possible configuration would be:
By default, par sets line width at 72 columns. You can alter this by passing the
-w flag with a number, for example:
:set formatprg=par\ -w50
This sets the line width to 50 columns. The backslash is necessary to escape the space at the command line. There are many different flags that can be passed to the par program in this fashion. You can view a summary of these by running
par help at the command line.
In the video, I give a quick overview of the following options:
- w – specify line length
- r – repeat characters in bodiless lines
- j – justifies text
- e – remove ‘superflous’ lines
- q – handle nested quotations in plaintext email
Before you can call par from Vim, you will have to make sure that it is installed on your system.
Installing Par on OS X with macports
If you have macports installed, you can install par on OS X by running:
sudo port install par
You will be prompted for your password.
Installing par on other platforms
I haven’t had time to try this out on either Linux or Windows. Please leave a comment if you find an article on the web with good instructions on how to install par, or build it from source.