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-reload¹ 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 already².

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-reloads³.

The groff options required are guessed by grog which will determine the macro package to be used and whether preprocessors such as -t, -e, etc are required depending on the content of the file. To see what options grog has guessed for the current buffer view :messages where it will be listed beginning with Ran:. Grog can be turned off if required, see Disabling Grog.

The wordcount functionality displays in the statusline a count of printed words and characters that will be output by groff, for instance the very minimal ms macro document:

  .PP
  Hello small-world?

Will show as Words: 2, Characters: 17 in the statusline. As the above example shows whitespace is not included in the character count. The mechanism for counting words is not entirely precise and is prone to slight over-counting, this should improve in future versions of vim-groff-viewer. Unfortunately the mom macro does not support the wordcount functionality, see Known Issues for more.

Wordcount does not utilise grog, rather the macro to be used 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. Not using grog here ensures that any bibliography files are not counted as part of the main body of text.

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 Linux 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).

Disabling grog

Should you wish to not have grog guess your groff options, then add the following line to your vim.rc / init.vim:

let groffviewer_grog=v:false

This will however mean that the macro (or other options) to be used will have to be explicitly set. For instance in the case of the -me macro you would need to also include:

let groffviewer_options="-me"

Setting the printer

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

Disabling keymappings

To disable the default keymappings, as specified at Usage, then add the following line to your vim.rc / init.vim:

let groffviewer_no_mappings=v:true

Default keymappings are also disabled if no_plugin_maps has been set by the user.

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

• Not compatible with Windows. Not tested on Mac, but it is likely xdg-open would need to be installed or a default viewer set.
• A correct xdg-open setting does not always result in the chosen application opening the postscript file⁴. If this is the case, then use groffviewer_default to over-ride as above.
• The pdf-only document viewer apvlp does not work with the -T pdf option listed above.
• Error handling needs to be improved. If groff fails to create valid output due to a syntax error, no warning is generated and subsequently xdg-open may attempt to use the wrong application to open a file it does not recognise as postscript.
• The word count functionality does not work with the mom macro. As running wordcount on certain mom documents caused vim to freeze, this functionality has been disabled for mom only. Further information on the behaviour of the mom macro in this regard is filed under GNU roff bug #63581 ("nroff -mom sample_docs.mom" causes infinite loop).

If you have discovered an issue not listed please add via the issues section of the repo; excuse in advance a slow response. There is a default template for raising issues should it be helpful. I'm also happy to be contacted.

Source code, Feature requests and Contributing

Source code can be found at the github repository PreciousChicken/vim-groff-viewer. Contributions, including feature requests, welcome (though development on this project is sporadic).

Feedback / Sponsor

Like the plugin? Starring the repository on github is always nice:  Star

Really like the plugin? You are always welcome to:

₿⚡ Or buy me a coffee with Bitcoin Lightning

Change log

As per GitHub release history.

Related work

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

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

Licence

Copyright 2023 PreciousChicken

Licenced under the Apache Licence, Version 2.0 (the "Licence"); you may not use this software except in compliance with the Licence. You may obtain a copy of the Licence at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licence for the specific language governing permissions and limitations under the Licence.