unroff-website/www/index.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.2.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>&nbsp; <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>&nbsp; <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>