Chicken silhouette

vim-groff-viewer

A Vim plugin for displaying Groff files in a document viewer.

Introduction

A Vim plugin for displaying Groff files in a document viewer as determined by the system default or chosen by the user. The document viewer used should auto-reload1 and preferably support the postscript file format - examples are Zathura, Evince, Okular or Xreader.

Installation

Install using your preferred plugin manager, for instance with vim-plug:

Plug 'PreciousChicken/vim-groff-viewer'

or dein.vim:

call dein#add('PreciousChicken/vim-groff-viewer')

Alternatively manually install:

Neovim

mkdir -p ~/.local/share/nvim/site/pack/preciouschicken/start/groff-viewer
git clone https://github.com/PreciousChicken/vim-groff-viewer.git ~/.local/share/nvim/site/pack/preciouschicken/start/groff-viewer

Vim

mkdir -p ~/.vim/pack/preciouschicken/start/groff-viewer
git clone https://github.com/PreciousChicken/vim-groff-viewer.git ~/.vim/pack/preciouschicken/start/groff-viewer

Additionally ensure that you have the line filetype plugin on added to your .vimrc if not already2.

Usage

With a groff file open in the current buffer select:

<localleader>o
Open groff file in selected document viewer
<localleader>p
Hard copy print groff file
<localleader>wc
Displays word and character count. The character count does not include whitespace.

Saving the file in the normal way, e.g. :w, will result in the groff preview updating in the document viewer, providing the selected viewer auto-reloads3.

The groff macro used by the plugin is determined by the file extension, for example the file myfile.me will be processed using the me macro package. For further information on groff file extensions see man 5 groff_filenames.

Video demonstration

Configuration

Setting postscript document viewer

The system default for opening postscript files according to xdg-open will be used as the default document viewer. The default xdg-open postscript application can be changed to, for example, Zathura by the following terminal command:

xdg-mime default org.pwmt.zathura.desktop application/postscript

Alternatively if you do not wish to make a system wide change, then the plugin will ignore the xdg-open default if the following line is adding to the .vimrc / init.vim, with the variable as the postscript viewer:

let groffviewer_default="zathura"

or, for instance:

let groffviewer_default="okular"

Setting groff options

The command line options available to groff can be added via your vim.rc / init.vim e.g.:

let groffviewer_options="-dpaper=a4"

Using a pdf-only document viewer

Using a document viewer that supports pdf but not postscript is possible by amending the groff options in your vim.rc / init.vim for pdf output. For example should you want to use ePDFView as a document viewer:

let groffviewer_default="epdfview" 
let groffviewer_options="-T pdf"

A pdf document viewer that auto-reloads should however still be chosen otherwise the document will fail to update on write (ePDFView would be a bad choice in this regard).

Setting the printer

The <localleader>p mapping uses the lp command to hard copy print; this assumes a default printer has been set.

Documentation

Helptags for the plugin can be loaded by using the command :helptags ALL when a groff file is open. Help will then be accessible within Vim via :help groff-viewer.

Known issues

Contributing

Contributions welcome. Please raise issues, pull requests, via the issues section of the GitHub repo; excuse in advance a slow response. When raising an issue you are very much invited to suggest solutions! There is a default template for raising issues should it be helpful.

Change log

As per GitHub release history.

Credits

The example used in the demonstration video can be found in the Groff and the art of letter writing tutorial.

Related work

A (non-maintained) alternative to vim-groff-viewer is texgroff.vim.


  1. A document viewer that auto-reloads is one that refreshes the view when the underlying document changes.↩︎

  2. This does not appear to be needed for Neovim.↩︎

  3. A document viewer that auto-reloads is one that refreshes the view when the underlying document changes.↩︎

  4. Testing on a fresh install of Ubuntu 22.04 has consistently opened the file in Gedit, regardless of the xdg-open setting.↩︎