Utroff.org

Utroff manual

Name

Utroff - Use Troff !

Description

Utroff is collection of tools to use easily Heirloom Troff today.

Utroff session

To use efficiently utroff, you should process as follow.

Configure your environment

The U(1) script gives you an easy access to the utroff tools, and configure some environment variables for you. Followed by a command, it will set the environment variables for this onliest command. With no argument, it can be sourced to set the utroff environment, or to reset your default environment.

Think

The idx(1) script will help you to produce indexes of the books you’re working on.

Write

The syntax of troff documents is line oriented : each command is on a line. A troff document should not contain blank lines, nor lines begining by a blank caracters. Commands are recognized by the dot ’.’ at the begin at the line. A line containing only a dot is ignored by troff. Comments begin by a slash followed by an apostrophe : ’\"

Troff macros (usually named tmac) define the commands one can use. On utroff, all the macros follow the same syntax, which is described on the utmac(7) manual page. Here is a simple utmac document :

.DA Author name metadata
.H1 Document title
.PP
A paragraph
.PQ
A quotation\**.
.NS
A note, between NS and NE. \** is used to insert the number
of the note.
.NE
End of the quotation.
.PP
Another paragraph.
.XT \" table of content

Pre-process

Pre-processors will help you to format your documents. soelim(1) will source files in your current document, tbl(1) insert tables, eqn(1) write equations, refer(1) format references — referformat(7) explain its syntax —, ugrind(1) highlight source code, tchars(1) write polytonic greek. Most of them define a mini-language, and will translate this mini-language to the raw troff language.

The preprocessor prexml(1) is used to produce xml files.

Format

Troff(1) will format your documents for typesetters. Nroff(1) will produce plain text documents and xml files if you use the ux macro. On both of them, the -m option will define the macro you want to use.

Post-process

If you used troff, dpost(1) will produce postscript files, dpage(1) will put two A4 page on an A3 sheet of paper, ps2pdf(1) will produce pdf files.

If you used nroff with the -mux option, postxml(1) will produce xml files, and trxtr(1) will translate the utroff xml format to famous xml formats, such as xhtml and fodt.

Recover your environment

If you sourced the U script, source it again to recover your default environment.

Example

All in one, a complex utroff session looks like :

 . U
vim f.tr
soelim f.tr | tbl | eqn | refer -p biblio.ref | ugrind \
| tchars > f.t
troff -mus f.t | dpost | dpage | ps2pdf - > f.pdf
prexml f.t | nroff -mux | postxml | trxtr html > f.html
prexml f.t | nroff -mux | postxml | trxtr fodt > f.fodt
nroff -mut f.t > f.txt
 . U

But most often, you only have to do :

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

Environment

If you don’t use the U(1) script, you should define the following environment variables :

See also

Utroff manual pages : U(1), idx(1), utmac(7), u-ref(7). soelim(1), felim(1), slelim(1), ugrind(1), tchars(1). refer(1), referformat(7), sortbib(1), hunt(1), inv(1), mkey(1). dpost(1), dpage(1), prexml(1), trxtr(1).

Some Heirloom Troff manual pages : otfdump(1), nroff(1), troff(1), dpost(1). tbl(1), eqn(1), eqnchar(7), checknr(1), pickpack(1), grap(1), pic(1).

Other usefull manual pages : ps2pdf(1).

License

This man page is distributed under a two clause BSD license.

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.

Author

Written by Pierre-Jean Fichet.