Unroff

Unroff is a Scheme-based, programmable, extensible troff translator with a back-end for the Hypertext Markup Language. Unroff is free software and is distributed both as source and as precompiled binaries.

Unroff was originally written by Oliver Laumann around 1995. It is now maintained by volunteers at the Scheme Conservatory.

Contents

Overview

Unroff reads and parses UNIX troff documents and translates the embedded markup into a different format (see Figure 1). Neither the actual output format nor any knowledge about particular troff macro sets (-man, -ms, etc.) are hard-wired into unroff. Instead, the translation process is controlled by a set of user-supplied procedures written in the Scheme programming language.

Translation rules for new output formats and troff macro packages can be added easily by providing a corresponding set of Scheme procedures (a ``back-end''). Version 1.0 of unroff includes back-ends for translating documents using the ``man'' and ``ms'' macros into the Hypertext Markup Language (HTML) version 2.0. Additional requests facilitate use of arbitrary hypertext links in troff documents.

[Overview of unroff functionality]

Unroff and Troff

In contrast to conventional troff ``converters'' (usually Perl scripts some of which process nroff output) unroff includes a full troff parser and closely mimics the troff processing engine. This enables unroff to handle user-defined macros, strings, and number registers, nested if-else requests, arbitrary fonts and font positions, low-level formatting requests such as \l, \c, and \h, and idiosyncrasies such as troff copy mode and the subtle differences between request and macro invocations. Unroff has adopted a number of groff extensions, among them long names for macros, strings, number registers, and special characters, and the escape sequences \$@ and \$*.

Unroff and Scheme

Unroff uses Elk, the Scheme-based Extension Language Kit, to achieve programmability (see Figure 2). It includes a full Scheme language implementation with the usual amenities such as garbage collection, interactive programming and testing, and dynamic loading. To help writing new unroff back-ends, unroff has augmented standard Scheme by a set of new Scheme data types and primitives.

[unroff and Elk/Scheme-code relationship]

A new troff request and an extension to the `.ig' request allow for Scheme code to be embedded in troff documents; the code is then evaluated on the fly as the documents are processed by unroff.

Unroff may be viewed as a prototype for hybrid applications that use Scheme (in particular Elk) as their extension language. Approximately half of its source consists of portable ANSI C code, and the other half is written in Scheme and can be configured and tailored easily without the need to recompile unroff. Authors of Elk-based applications are encouraged to look into the source code or reuse parts of it for their own projects.

As the time-critical Scheme primitives provided of unroff have been coded in (efficient) C, its performance comes close to that of nroff processing the same troff input.

Unroff and Hypertext

troff documents that were originally written without intentions to make them available in the World Wide Web (such as UNIX manual pages) can easily be translated to the Hypertext Markup Language using the predefined HTML back-ends.

As unroff closely simulates ordinary troff, even large or complex documents (like technical reports or theses with many user-defined macros) can be translated to HTML automatically without having to add any structural cues to the documents.

The ``-man'' support has been tested with several hundred vendor- and user-supplied manual pages and has produced good results in all but less than a dozen cases (a few manual pages were found to make excessive use of low-level troff constructs or to include tbl output verbatim).

Managing Hypertext Documents with Troff

Authors can benefit from unroff not only as a converter for existing documents, but also when writing new documents that must exist both in high-quality paper form and in the World Wide Web as hypertext.

Rather than writing hypertext documents directly in HTML (which is cumbersome for long or complex texts), authors can continue using ordinary troff together with the usual preprocessors and macro packages. Unroff is then employed to produce the WWW form, while troff is used in the normal way to typeset the same text, producing the printed version (or, using nroff, an ASCII version if desired).

In this way authors of hypertext documents can take full advantage of the usual troff facilities such as user-defined macros, conditional text, tables, equations, and drawings, automatic table of contents generation, footnotes/endnotes, indexes, etc., none of which are available when composing documents directly in plain HTML.

Two new troff requests for embedding hypertext links in troff documents are provided by the unroff HTML back-end. Arbitrary forward and backward references using symbolic labels (rather than actual file names) among groups of troff source files are supported (see Figure 3). Another new request and another extension to `.ig' allow for HTML code to be embedded directly in troff documents. The hypertext capabilities are demonstrated by the troff source of the Programmer's Manual that is part of the unroff distribution.

[troff document with hypertext links]

Source and Binary Distributions

You need Elk 2.2 or Elk 3.0 and an ANSI C compiler to compile and install unroff from the source distribution.

If you do not have Elk at your site and do not want to install it, or if you just wish to have a quick look at unroff, download the binary distribution for your system. Otherwise, use of the source distribution is recommended.

The unroff executable is linked dynamically in the binary distributions for systems with shared libraries.

Browsing Source, Documentation, Examples

You can have a look at the unroff source code and documentation without having to download the distribution. All the HTML documents mentioned below have been produced with unroff from the corresponding troff source (observe the automatically created hypertext links in the Programmer's Manual).

What's New?

January 28, 1996:  Unofficial Patch with -me support

George Helffrich has contributed a patch for unroff-1.0 that includes, among other things, an experimental implementation of a backend for the -me macros and several fixes for the code that deals with equations. A detailed table of contents of at the beginning of the patch kit:

me-misc-patch (39 kbytes)

February 13, 1997:  Another Unofficial Patch

George Helffrich has contributed another large patch kit for unroff-1.0 that fixes several things in the -me support contributed earlier and in the -ms package and also adds some new functionality.

misc-patch-2 (79 kbytes)