conservatory
/
unroff-website
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Drop duplicate of the front page 

index.html and unroff.html were identical, except for the URL of the
Scheme link.
This commit is contained in:
Lassi Kortela 2023-02-14 10:28:33 +02:00
parent b9ca94c317
commit 1a5da7c315
1 changed files with 0 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
www/unroff.html
View File

@ -1,326 +0,0 @@
<html>
<head>
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
<title>unroff release 1.0 information</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.<tt> </tt>
Unroff is free software and is distributed both as source and
as precompiled binaries.
<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="#patches">Patches</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="http://www-swiss.ai.mit.edu/scheme-home.html"><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
for systems with shared libraries.<tt> </tt>
Please send a message to
<a href="mailto:net@informatik.uni-bremen.de">net@informatik.uni-bremen.de</a>
if you need a statically linked version, or if you think that statically
linked executables should be offered in addition to or in place of
the dynamically linked ones (or if you need an entirely different format).
<p>
<ul>
<li><b>Source Distribution</b> (about 80 Kbytes)
<ul>
<li><a href="dist/unroff-1.0.tar.gz">unroff-1.0.tar.gz</a>
</ul>
</ul>
<ul>
<li><b>Binary Distributions</b> (about 200 Kbytes each)
<ul>
<li><a href="dist/unroff-1.0-alpha-dec-osf3.0.tar.gz">
unroff-1.0-alpha-dec-osf3.0.tar.gz</a>
<li><a href="dist/unroff-1.0-hppa1.1-hp-hpux9.tar.gz">
unroff-1.0-hppa1.1-hp-hpux9.tar.gz</a>
<li><a href="dist/unroff-1.0-i486-unknown-linux1.2.8.tar.gz">
unroff-1.0-i486-unknown-linux1.2.8.tar.gz</a>
<li><a href="dist/unroff-1.0-m68k-next-ns3.tar.gz">
unroff-1.0-m68k-next-ns3.tar.gz</a>
<li><a href="dist/unroff-1.0-mips-dec-ultrix4.2.tar.gz">
unroff-1.0-mips-dec-ultrix4.2.tar.gz</a>
<li><a href="dist/unroff-1.0-mips-sgi-irix5.3.tar.gz">
unroff-1.0-mips-sgi-irix5.2.tar.gz</a>
<li><a href="dist/unroff-1.0-rs6000-ibm-aix3.2.tar.gz">
unroff-1.0-rs6000-ibm-aix3.2.tar.gz</a>
<li><a href="dist/unroff-1.0-sparc-sun-solaris2.tar.gz">
unroff-1.0-sparc-sun-solaris2.tar.gz</a>
<li><a href="dist/unroff-1.0-sparc-sun-sunos4.tar.gz">
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ä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>
<ul><li>Snoop around in the unroff 1.0 <a href="unroff-1.0">
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=patches>Official Patches</a></h2>
To determine whether your source or binary unroff distribution
needs any of the official patches,
check out the file <a href="unroff-1.0/PATCHLEVEL">PATCHLEVEL</a>
(a non-existent file indicates a patch level of zero).<tt> </tt>
The distributions offered here always have the highest patchlevel.<tt> </tt>
Patches marked with an asterisk (*) only affect the Scheme code can
therefore be applied to the binary distribution; all other patches
must be applied to the source distribution.
<ul>
<li>Currently available <b>Patches</b>
<ul>
<li><a href="unroff-1.0/patches/1">Patch #1</a>
<li><a href="unroff-1.0/patches/2">Patch #2</a>
</ul>
</ul>
<h2><a name=news>What's New?</a></h2>
<p>
<i>January 28, 1996:</i>&#160;<tt> </tt><b>Unofficial Patch
with -me support</b>
<dl><dt><dd>
George Helffrich (<a href="mailto:george@geology.bristol.ac.uk">
george@geology.bristol.ac.uk</a>)
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>
<a href="contrib/me-misc-patch"><b>me-misc-patch</b></a>
<i>(39 kbytes)</i> &#183;
<a href="contrib/me-misc-patch.gz"><b>me-misc-patch.gz</b></a>
<i>(11 kbytes)</i>
</dl>
<p>
<i>February 13, 1997:</i>&#160;<tt> </tt><b>Another Unofficial Patch</b>
<dl><dt><dd>
George Helffrich (<a href="mailto:george@geology.bristol.ac.uk">
george@geology.bristol.ac.uk</a>)
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"><b>misc-patch-2</b></a>
<i>(79 kbytes)</i> &#183;
<a href="contrib/misc-patch-2.gz"><b>misc-patch-2.gz</b></a>
<i>(20 kbytes)</i>
</dl>
<hr>
<i>Oliver Laumann</i> &#160;<tt> </tt>&#160;<tt> </tt>&#160;<tt> </tt>
<a href="mailto:net@informatik.uni-bremen.de">net@informatik.uni-bremen.de</a>
</body>
</html>