2023-02-14 03:28:12 -05:00
|
|
|
|
<html>
|
|
|
|
|
|
<head>
|
2023-02-14 13:35:23 -05:00
|
|
|
|
<title>Unroff</title>
|
2023-02-14 03:28:12 -05:00
|
|
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<h1>Unroff</h1>
|
|
|
|
|
|
<i>Unroff</i>
|
|
|
|
|
|
is a Scheme-based, programmable, extensible troff translator
|
|
|
|
|
|
with a back-end for the Hypertext Markup Language.<tt> </tt>
|
|
|
|
|
|
Unroff is free software and is distributed both as source and
|
|
|
|
|
|
as precompiled binaries.
|
|
|
|
|
|
|
2023-02-14 13:35:23 -05:00
|
|
|
|
<p>Unroff was originally written by Oliver Laumann around 1995. It is
|
|
|
|
|
|
now maintained by volunteers at the Scheme Conservatory.
|
|
|
|
|
|
|
2023-02-14 03:28:12 -05:00
|
|
|
|
<h2>Contents</h2>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><a href="#overview">Overview</a>
|
|
|
|
|
|
<li><a href="#troff">Unroff and Troff</a>
|
|
|
|
|
|
<li><a href="#scheme">Unroff and Scheme</a>
|
|
|
|
|
|
<li><a href="#hypertext">Unroff and Hypertext</a>
|
|
|
|
|
|
<li><a href="#managing">Managing Hypertext Documents with Troff</a>
|
|
|
|
|
|
<li><a href="#dist">Source and Binary Distributions</a>
|
|
|
|
|
|
<li><a href="#browse">Browsing Source, Documentation, Examples</a>
|
|
|
|
|
|
<li><a href="#news">What's New?</a>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=overview>Overview</a></h2>
|
|
|
|
|
|
Unroff reads and parses UNIX troff documents and translates the embedded
|
|
|
|
|
|
markup into a different format (see <b>Figure 1</b>).<tt> </tt>
|
|
|
|
|
|
Neither the actual output format nor any knowledge about particular
|
|
|
|
|
|
troff macro sets (-man, -ms, etc.) are hard-wired into unroff.<tt> </tt>
|
|
|
|
|
|
Instead, the translation process is controlled by a set of
|
|
|
|
|
|
user-supplied procedures written in the
|
|
|
|
|
|
<a href="https://en.wikipedia.org/wiki/Scheme_%28programming_language%29"><i>Scheme</i></a>
|
|
|
|
|
|
programming language.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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'').<tt> </tt>
|
|
|
|
|
|
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.<tt> </tt>
|
|
|
|
|
|
Additional requests facilitate use of arbitrary hypertext links in
|
|
|
|
|
|
troff documents.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
<img src=fig1.gif alt="[Overview of unroff functionality]">
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=troff>Unroff and Troff</a></h2>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.<tt> </tt>
|
|
|
|
|
|
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 <i>copy mode</i> and the subtle differences
|
|
|
|
|
|
between request and macro invocations.<tt> </tt>
|
|
|
|
|
|
Unroff has adopted a number of <i>groff</i> extensions, among them long names
|
|
|
|
|
|
for macros, strings, number registers, and special characters, and the
|
|
|
|
|
|
escape sequences \$@ and \$*.
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=scheme>Unroff and Scheme</a></h2>
|
|
|
|
|
|
Unroff uses
|
|
|
|
|
|
<a href="http://www.informatik.uni-bremen.de/~net/elk"><i>Elk</i></a>,
|
|
|
|
|
|
the Scheme-based Extension Language Kit, to achieve
|
|
|
|
|
|
programmability (see <b>Figure 2</b>).<tt> </tt>
|
|
|
|
|
|
It includes a full Scheme language implementation
|
|
|
|
|
|
with the usual amenities such as garbage collection, interactive
|
|
|
|
|
|
programming and testing, and dynamic loading.<tt> </tt>
|
|
|
|
|
|
To help writing new unroff back-ends, unroff has augmented
|
|
|
|
|
|
standard Scheme by a set of new Scheme data types
|
|
|
|
|
|
and primitives.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
<img src=fig2.gif alt="[unroff and Elk/Scheme-code relationship]">
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Unroff may be viewed as a prototype for hybrid applications that use
|
|
|
|
|
|
Scheme (in particular Elk) as their extension language.<tt> </tt>
|
|
|
|
|
|
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.<tt> </tt>
|
|
|
|
|
|
Authors of Elk-based applications are encouraged to look into the
|
|
|
|
|
|
source code or reuse parts of it for their own projects.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=hypertext>Unroff and Hypertext</a></h2>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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 <i>tbl</i> output verbatim).
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=managing>Managing Hypertext Documents with Troff</a></h2>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.<tt> </tt>
|
|
|
|
|
|
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).
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Two new troff requests for embedding hypertext links in troff documents
|
|
|
|
|
|
are provided by the unroff HTML back-end.<tt> </tt>
|
|
|
|
|
|
Arbitrary forward and backward references using symbolic labels
|
|
|
|
|
|
(rather than actual file names) among
|
|
|
|
|
|
groups of troff source files are supported (see <b>Figure 3</b>).<tt> </tt>
|
|
|
|
|
|
Another new request and another extension to `.ig' allow for HTML code
|
|
|
|
|
|
to be embedded directly in troff documents.<tt> </tt>
|
|
|
|
|
|
The hypertext capabilities are demonstrated by the troff source of the
|
|
|
|
|
|
Programmer's Manual that is part of the unroff distribution.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
<img src=fig3.gif alt="[troff document with hypertext links]">
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=dist>Source and Binary Distributions</a></h2>
|
|
|
|
|
|
You need Elk 2.2 or
|
|
|
|
|
|
<a href="http://www.informatik.uni-bremen.de/~net/elk">Elk 3.0</a>
|
|
|
|
|
|
and an ANSI C compiler to compile and
|
|
|
|
|
|
install unroff from the source distribution.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
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.<tt> </tt>
|
|
|
|
|
|
Otherwise, use of the source distribution is recommended.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The unroff executable is linked dynamically in the binary distributions
|
2023-02-14 13:26:41 -05:00
|
|
|
|
for systems with shared libraries.
|
2023-02-14 03:28:12 -05:00
|
|
|
|
<p>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><b>Source Distribution</b> (about 80 Kbytes)
|
|
|
|
|
|
<ul>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0.tar.gz">unroff-1.0.tar.gz</a>
|
2023-02-14 03:28:12 -05:00
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><b>Binary Distributions</b> (about 200 Kbytes each)
|
|
|
|
|
|
<ul>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-alpha-dec-osf3.0.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-alpha-dec-osf3.0.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-hppa1.1-hp-hpux9.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-hppa1.1-hp-hpux9.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-i486-unknown-linux1.2.8.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-i486-unknown-linux1.2.8.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-m68k-next-ns3.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-m68k-next-ns3.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-mips-dec-ultrix4.2.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-mips-dec-ultrix4.2.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-mips-sgi-irix5.3.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-mips-sgi-irix5.2.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-rs6000-ibm-aix3.2.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-rs6000-ibm-aix3.2.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-sparc-sun-solaris2.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-sparc-sun-solaris2.tar.gz</a>
|
2023-02-14 12:07:19 -05:00
|
|
|
|
<li><a href="https://files.scheme.org/unroff-1.0-sparc-sun-sunos4.tar.gz">
|
2023-02-14 03:28:12 -05:00
|
|
|
|
unroff-1.0-sparc-sun-sunos4.tar.gz</a>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>The <b>Elk 3.0 Distribution</b> is available here:
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><a href="ftp://ftp.x.org/contrib/devel_tools/elk-3.0.tar.gz">
|
|
|
|
|
|
X Consortium Public FTP Server</a>
|
|
|
|
|
|
<li><a href=
|
|
|
|
|
|
"ftp://ftp.cs.indiana.edu/pub/scheme-repository/imp/elk-3.0.tar.gz">
|
|
|
|
|
|
Scheme Repository at Indiana University</a>
|
|
|
|
|
|
<li><a href=
|
|
|
|
|
|
"ftp://ftp.tzi.uni-bremen.de/tzi/dmn/elk/elk-3.0.tar.gz">
|
|
|
|
|
|
Universit<69>t Bremen, Germany</a>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=browse>Browsing Source, Documentation, Examples</a></h2>
|
|
|
|
|
|
You can have a look at the unroff source code and documentation
|
|
|
|
|
|
without having to download the distribution.<tt> </tt>
|
|
|
|
|
|
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).
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><b>Source Code</b>
|
2023-02-14 12:06:59 -05:00
|
|
|
|
<ul><li>Snoop around in the
|
|
|
|
|
|
<a href="https://gitea.scheme.org/conservatory/unroff">unroff</a>
|
2023-02-14 03:28:12 -05:00
|
|
|
|
source tree</a>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><b>Documentation</b>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>Manual page <b>unroff.1</b> as
|
|
|
|
|
|
<a href="doc/unroff.1.html">HTML</a>,
|
|
|
|
|
|
<a href="doc/unroff.1.ps">PostScript</a>,
|
|
|
|
|
|
<a href="doc/unroff.1">source</a>
|
|
|
|
|
|
<li>Manual page <b>unroff-html.1</b> as
|
|
|
|
|
|
<a href="doc/unroff-html.1.html">HTML</a>,
|
|
|
|
|
|
<a href="doc/unroff-html.1.ps">PostScript</a>,
|
|
|
|
|
|
<a href="doc/unroff-html.1">source</a>
|
|
|
|
|
|
<li>Manual page <b>unroff-html-man.1</b> as
|
|
|
|
|
|
<a href="doc/unroff-html-man.1.html">HTML</a>,
|
|
|
|
|
|
<a href="doc/unroff-html-man.1.ps">PostScript</a>,
|
|
|
|
|
|
<a href="doc/unroff-html-man.1">source</a>
|
|
|
|
|
|
<li>Manual page <b>unroff-html-ms.1</b> as
|
|
|
|
|
|
<a href="doc/unroff-html-ms.1.html">HTML</a>,
|
|
|
|
|
|
<a href="doc/unroff-html-ms.1.ps">PostScript</a>,
|
|
|
|
|
|
<a href="doc/unroff-html-ms.1">source</a>
|
|
|
|
|
|
<li><b>Programmer's Manual</b> as HTML
|
|
|
|
|
|
<menu>
|
|
|
|
|
|
<li><a href="doc/manual.html">single document</a>
|
|
|
|
|
|
<li><a href="doc/m.html">split at level-1 headers</a>
|
|
|
|
|
|
</menu>
|
|
|
|
|
|
<li><b>Programmer's Manual</b> as
|
|
|
|
|
|
<a href="doc/manual.ps">PostScript</a> or
|
|
|
|
|
|
<a href="doc/manual.ms">source</a>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li><b>More Examples</b>
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>X11R6 Release Notes in -ms format
|
|
|
|
|
|
(<a href="examples/RELNOTES.ms">source</a>)
|
|
|
|
|
|
<menu>
|
|
|
|
|
|
<li><a href="examples/rel.html">
|
|
|
|
|
|
single HTML document</a>
|
|
|
|
|
|
<br>with user-defined TOC at end (-ms index macros)
|
|
|
|
|
|
<li><a href="examples/r.html">
|
|
|
|
|
|
split at level-1 headers</a>
|
|
|
|
|
|
<br>with automatic TOC at first page
|
|
|
|
|
|
</menu>
|
|
|
|
|
|
<li>UNIX <a href="examples/pathconf.2.html">man page</a> with tables
|
|
|
|
|
|
(<a href="examples/pathconf.2">pathconf.2</a>)
|
|
|
|
|
|
<li>X11 <a href="examples/XtSetArg.3.html">man page</a> with
|
|
|
|
|
|
user-defined macros
|
|
|
|
|
|
(<a href="examples/XtSetArg.3">XtSetArg.3</a>)
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h2><a name=news>What's New?</a></h2>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<i>January 28, 1996:</i> <tt> </tt><b>Unofficial Patch
|
|
|
|
|
|
with -me support</b>
|
|
|
|
|
|
<dl><dt><dd>
|
2023-02-14 13:26:41 -05:00
|
|
|
|
George Helffrich
|
2023-02-14 03:28:12 -05:00
|
|
|
|
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.<tt> </tt>
|
|
|
|
|
|
A detailed table of contents of at the beginning of the
|
|
|
|
|
|
patch kit:
|
|
|
|
|
|
<p>
|
2023-02-14 03:34:38 -05:00
|
|
|
|
<a href="contrib/me-misc-patch.diff"><b>me-misc-patch</b></a>
|
|
|
|
|
|
<i>(39 kbytes)</i>
|
2023-02-14 03:28:12 -05:00
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<i>February 13, 1997:</i> <tt> </tt><b>Another Unofficial Patch</b>
|
|
|
|
|
|
<dl><dt><dd>
|
2023-02-14 13:26:41 -05:00
|
|
|
|
George Helffrich
|
2023-02-14 03:28:12 -05:00
|
|
|
|
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.
|
|
|
|
|
|
<p>
|
2023-02-14 03:34:38 -05:00
|
|
|
|
<a href="contrib/misc-patch-2.diff"><b>misc-patch-2</b></a>
|
|
|
|
|
|
<i>(79 kbytes)</i>
|
2023-02-14 03:28:12 -05:00
|
|
|
|
</dl>
|
|
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
