Utroff.org

Utroff readme

Presentation of Utroff

Utroff is a set of macro, pre-processors, and post-processors to use easily Heirloom Troff today. It handles the Heirloom troff typographic features (paragraph at once adjustment, hanging characters, OpenType fonts, utf8), provides default support for index, table of contents, summary, bibliography, syntax highlighting, polytonic greek, and it is able to produce pdf, xml, html, fodt, man, plain text and markdown files.

Utroff is distributed in two forms : a pre-built archive with a version number for quick installs, and a development archive.

Quick start

Dependencies

Utroff depends on Heirloom-doctools. A recipe to install Heirloom-doctools in a conveniant way for utroff can be found on the ’heirloom’ subdirectory of this archive. You should look at it.

By default, utmac needs the OpenType Libertine font.

Trxtr, from trofftoxml, depends on xsltproc, from libxslt.

Configuration

Configure the file config.mk to suit your needs.

Build and install

To build, install, and clean run :

make all
make install
make clean

In some circumstances, you might need utroff tools themselves to build the manual pages. In that case, build and install executables before manual pages like this :

make bin
make installbin
make man
make installman

Environment variables

The easiest way to configure utroff is to add its bin directory at the end of your PATH, and use the U script, which will set a temporary environment for utroff.

U man utroff
U troff -mus f.tr | U dpost | ps2pdf - > f.pdf

Once done, you might want to set the UTMAC environment variable, which contain the absolute file name of a user defined macro. This macro can be used to source a macro which sets your locale (such as u-en or u-fr), and a macro which sets your prefered font (such as u-libertine and u-apolline).

But you can also set the environment variables manually :

Conflicts

Since groff and utroff share the same tools, the directory to install utroff must be choosen carefully :

In both case, you have to check the configuration of your man command. If man expect to find the groff tools, add the path to this tools in the man configuration file (usually /etc/man_db.conf) :

DEFINE     troff   groff -mandoc
DEFINE     nroff   /usr/bin/nroff -mandoc
DEFINE     eqn     /usr/bin/eqn
DEFINE     neqn    /usr/bin/neqn
DEFINE     tbl     /usr/bin/tbl
DEFINE     vgrind
DEFINE     refer   /usr/bin/refer
DEFINE     grap
DEFINE     pic     /usr/bin/pic -S

Makefile options

The makefile offers a lot of commands. You can use them from the root directory or from a subdirectory. From the root directory, you can also use the shortcut subdir/command.

About the pre-built archive

Utroff tools written from scratch are distributed under a two clause BSD license. The other tools are modifications of the Heirloom Tools, which are mostly distributed under the CDDL-1.0 license. Here is a summary of the licenses of the tools :

About the development archive

The development archive (utroff-dev) contains the RCS revision files, and the following tools :

The makefile of the development archive offers some usefull commands for developpers and packagers :

Help and bugs

Don’t hesitate to ask questions at help at utroff dot org. Please, send bugs and patches at help at utroff dot org.