Groff Preprocessors and Tools

This repository is home to an assortment of preprocessors and macros for the GNU Troff typesetting package.

I have written all of them except sequence.pic which is part of the UML Graph package and included here for convenience only. These scripts do not strive to be complete, well tested and fit for general usage - they are merely quick and dirty hacks that accumulated on my hard drive :-).

EBNF

ebnf.sno is a CSNOBOL4 program that compiles extended BNF descriptions into GNU pic code using macros from syntax.pic. This effectively allows you to embed EBNF grammars in Groff source code and have it rendered as (box and arrow) syntax diagrams. Most EBNF constructs and some extensions are supported, but I'm too lazy to document all of them now.

To build the sample select-from.ebnf, type something like:

cat samples/select-from.ebnf | ./ebnf.sno | pic | groff -Tps >select-from.ps

HIGHLIGHT (Python)

pygments-groff.py is a syntax highlighting preprocessor based on Pygments and consequently written in Python 3. It is the most powerful (and probably fastest) of the syntax highlighting preprocessors presented here. It should also be more portable as it does not rely on stdout redirection magic. It should work with all Groff macro suites and even preserves the line numbering in Groff error messages.

You can process embedded blocks of code as in the following ms-based example:

.LD
.CW
.lg 0
.HIGHLIGHT c
#include <stdio.h>

int main(int argc, char **argv)
{
	printf("Hello world!\n");
	return 0;
}
.HIGHLIGHT
.DE

Note that you may have to do more before .HIGHLIGHT - for instance redefine chars - depending on your use case.

The default language identifier is useful to include code without highlighting, but still benefit from Pygment's preprocessing in order to achieve verbatim text. A list of language identifiers (short names) can be found on the Pygments website.

Just like highlight.lua, you can specify a file name directly after the language identifier:

.HIGHLIGHT c hello.c

HIGHLIGHT (SNOBOL4)

highlight.sno is a small preprocessor written in CSNOBOL4 that processes blocks of source code embedded in your Groff document with GNU Source-highlight to produce syntax highlighted text.

The output is formatted according to groff.outlang. Versions for the mom macros (groff-mom.outlang) and for the classic ms macros (groff-ms.outlang) are provided.

Example (mom):

.QUOTE
.CODE
.HIGHLIGHT c
#include <stdio.h>

int main(int argc, char **argv)
{
	printf("Hello world!\n");
	return 0;
}
.HIGHLIGHT
.CODE OFF
.QUOTE OFF

HIGHLIGHT (Lua)

highlight.lua is a reimplementation of highlight.sno in Lua 5.2 and may work better on some operating systems.

In addition to the aforementioned syntax, the Lua version allows you to specify a filename after the language identifier to process an external file:

.HIGHLIGHT c hello.c

UML

uml.sno is a small preprocessor (again requires CSNOBOL4) that renders an embedded diagram with PlantUML and automatically emits the appropriate Mom PDF_IMAGE macro calls.

Naturally, this leaves around PDF images (uml_tempX.pdf) that you should remove after generating your document.

HTML Tables

htbl.tes is a quick and dirty SciTECO script that can act as a drop-in replacement for the tbl preprocessor that generates proper HTML tables when the Groff html output device is used. With the original tbl preprocessor, tables are (and must be) rendered by the postscript device and will be embedded as images into the HTML page.