358 lines
14 KiB
HTML
358 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Unroff</title>
|
|
</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. Unroff is free software and is distributed both
|
|
as source and as precompiled binaries.
|
|
<p>Unroff was originally written by Oliver Laumann around 1995.
|
|
It is now maintained by volunteers at the Scheme
|
|
Conservatory.</p>
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li>
|
|
<a href="#overview">Overview</a>
|
|
</li>
|
|
<li>
|
|
<a href="#troff">Unroff and Troff</a>
|
|
</li>
|
|
<li>
|
|
<a href="#scheme">Unroff and Scheme</a>
|
|
</li>
|
|
<li>
|
|
<a href="#hypertext">Unroff and Hypertext</a>
|
|
</li>
|
|
<li>
|
|
<a href="#managing">Managing Hypertext Documents with
|
|
Troff</a>
|
|
</li>
|
|
<li>
|
|
<a href="#dist">Source and Binary Distributions</a>
|
|
</li>
|
|
<li>
|
|
<a href="#browse">Browsing Source, Documentation,
|
|
Examples</a>
|
|
</li>
|
|
<li>
|
|
<a href="#news">What's New?</a>
|
|
</li>
|
|
</ul>
|
|
<h2><a name="overview" id="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>). 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 <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''). 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.</p>
|
|
<hr>
|
|
<img src="fig1.gif" alt="[Overview of unroff functionality]">
|
|
<hr>
|
|
<h2><a name="troff" id="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.
|
|
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. 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 \$*.</p>
|
|
<h2><a name="scheme" id="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>). 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.
|
|
<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>
|
|
<p>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.</p>
|
|
<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.</p>
|
|
<h2><a name="hypertext" id="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>
|
|
<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).</p>
|
|
<h2><a name="managing" id="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. 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>
|
|
<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>
|
|
<p>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 <b>Figure 3</b>). 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.</p>
|
|
<hr>
|
|
<img src="fig3.gif" alt="[troff document with hypertext links]">
|
|
<hr>
|
|
<h2><a name="dist" id="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. Otherwise, use of the
|
|
source distribution is recommended.</p>
|
|
<p>The unroff executable is linked dynamically in the binary
|
|
distributions for systems with shared libraries.</p>
|
|
<ul>
|
|
<li>
|
|
<b>Source Distribution</b> (about 80 Kbytes)
|
|
<ul>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0.tar.gz">unroff-1.0.tar.gz</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<b>Binary Distributions</b> (about 200 Kbytes each)
|
|
<ul>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-alpha-dec-osf3.0.tar.gz">
|
|
unroff-1.0-alpha-dec-osf3.0.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-hppa1.1-hp-hpux9.tar.gz">
|
|
unroff-1.0-hppa1.1-hp-hpux9.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-i486-unknown-linux1.2.8.tar.gz">
|
|
unroff-1.0-i486-unknown-linux1.2.8.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-m68k-next-ns3.tar.gz">
|
|
unroff-1.0-m68k-next-ns3.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-mips-dec-ultrix4.2.tar.gz">
|
|
unroff-1.0-mips-dec-ultrix4.2.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-mips-sgi-irix5.3.tar.gz">
|
|
unroff-1.0-mips-sgi-irix5.3.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-rs6000-ibm-aix3.2.tar.gz">
|
|
unroff-1.0-rs6000-ibm-aix3.2.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-sparc-sun-solaris2.tar.gz">
|
|
unroff-1.0-sparc-sun-solaris2.tar.gz</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"https://files.scheme.org/unroff-1.0-sparc-sun-sunos4.tar.gz">
|
|
unroff-1.0-sparc-sun-sunos4.tar.gz</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</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>
|
|
<li>
|
|
<a href=
|
|
"ftp://ftp.cs.indiana.edu/pub/scheme-repository/imp/elk-3.0.tar.gz">
|
|
Scheme Repository at Indiana University</a>
|
|
</li>
|
|
<li>
|
|
<a href=
|
|
"ftp://ftp.tzi.uni-bremen.de/tzi/dmn/elk/elk-3.0.tar.gz">Universität
|
|
Bremen, Germany</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h2><a name="browse" id="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.
|
|
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).
|
|
<ul>
|
|
<li>
|
|
<b>Source Code</b>
|
|
<ul>
|
|
<li>Snoop around in the <a href=
|
|
"https://gitea.scheme.org/conservatory/unroff">unroff</a>
|
|
source tree
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<li>
|
|
<b>Programmer's Manual</b> as HTML
|
|
<ul>
|
|
<li>
|
|
<a href="doc/manual.html">single document</a>
|
|
</li>
|
|
<li>
|
|
<a href="doc/m.html">split at level-1 headers</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<b>Programmer's Manual</b> as <a href=
|
|
"doc/manual.ps">PostScript</a> or <a href=
|
|
"doc/manual.ms">source</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<b>More Examples</b>
|
|
<ul>
|
|
<li>X11R6 Release Notes in -ms format (<a href=
|
|
"examples/RELNOTES.ms">source</a>)
|
|
<ul>
|
|
<li>
|
|
<a href="examples/rel.html">single HTML
|
|
document</a><br>
|
|
with user-defined TOC at end (-ms index macros)
|
|
</li>
|
|
<li>
|
|
<a href="examples/r.html">split at level-1
|
|
headers</a><br>
|
|
with automatic TOC at first page
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>UNIX <a href="examples/pathconf.2.html">man page</a>
|
|
with tables (<a href="examples/pathconf.2">pathconf.2</a>)
|
|
</li>
|
|
<li>X11 <a href="examples/XtSetArg.3.html">man page</a>
|
|
with user-defined macros (<a href=
|
|
"examples/XtSetArg.3">XtSetArg.3</a>)
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h2><a name="news" id="news">What's New?</a></h2>
|
|
<p><i>January 28, 1996:</i> <b>Unofficial Patch with -me
|
|
support</b></p>
|
|
<blockquote>
|
|
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:
|
|
<p><a href=
|
|
"contrib/me-misc-patch.diff"><b>me-misc-patch</b></a> <i>(39
|
|
kbytes)</i></p>
|
|
</blockquote>
|
|
<p><i>February 13, 1997:</i> <b>Another Unofficial
|
|
Patch</b></p>
|
|
<blockquote>
|
|
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.
|
|
<p><a href="contrib/misc-patch-2.diff"><b>misc-patch-2</b></a>
|
|
<i>(79 kbytes)</i></p>
|
|
</blockquote>
|
|
</body>
|
|
</html>
|