105 lines
4.6 KiB
HTML
105 lines
4.6 KiB
HTML
<html>
|
|
<head>
|
|
<!-- This file has been generated by unroff 1.0, 03/21/96 19:29:41. -->
|
|
<!-- Do not edit! -->
|
|
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
|
|
<title>unroff Programmer's Manual, section 3.</title>
|
|
</head><body>
|
|
<h2><a name="section3">3.</a> <tt> </tt><a name=".events">Events and Event Handling</a>
|
|
</h2>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt><i>unroff
|
|
</i>interprets a troff document as a sequence of chunks of normal
|
|
text and interspersed ``events''.<tt> </tt>
|
|
Plain text is usually just copied to the current output (a file or
|
|
standard output).<tt> </tt>
|
|
The output produced for an event is determined by an ``event
|
|
handler'' (usually a Scheme procedure) that can be associated
|
|
with each event.<tt> </tt>
|
|
If no event handler can be found for an event encountered in the
|
|
currently processed document (with a few exceptions), a warning message
|
|
is displayed and the input that triggered the event is skipped
|
|
(in case of requests and macros) or treated like normal text.<tt> </tt>
|
|
For events such as troff requests, a separate Scheme procedure
|
|
can be defined for each request, and the name of the request that
|
|
triggered the event is then passed to the procedure as an argument.<tt> </tt>
|
|
An event handling procedure can be defined for
|
|
<ul>
|
|
<li>
|
|
each troff request, including requests that perform intrinsic troff
|
|
functions, such as ``.de'' and ``.if''
|
|
<li>
|
|
each troff macro, whether user-defined or part of a macro
|
|
package
|
|
<li>
|
|
each troff string
|
|
<li>
|
|
each number register
|
|
<li>
|
|
each special character
|
|
<li>
|
|
each escape sequence
|
|
<li>
|
|
each character (to provide character translations)
|
|
<li>
|
|
each inline equation enclosed by the current
|
|
<i>eqn</i>(1)
|
|
delimiter characters
|
|
<li>
|
|
each end of sentence (defined as a period, exclamation mark, or
|
|
question mark, followed by a newline).<tt> </tt>
|
|
</ul>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>When invoked, every Scheme procedure associated with one of
|
|
the above events receives one or more arguments.<tt> </tt>
|
|
For example, a procedure registered for the escape sequence `\h'
|
|
(horizontal space) is passed the name of the escape sequence
|
|
(the letter `h') as well as the argument to `\h' (i.e. the amount
|
|
of space).<tt> </tt>
|
|
Likewise, event handling procedures for requests and macros are
|
|
called with the name of the request or macro as well as any
|
|
arguments specified in the troff input.<tt> </tt>
|
|
The exact arguments passed to each type of event handler will be
|
|
explained below.<tt> </tt>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>A Scheme procedure associated with an event must return a string
|
|
which is then output in place of whatever input triggered the
|
|
event.<tt> </tt>
|
|
Here, and in a number of other places, a Scheme symbol or a Scheme
|
|
is accepted as an alternative to a string return value.<tt> </tt>
|
|
Event handling procedures are free to directly produce output
|
|
in addition to returning it as a result.<tt> </tt>
|
|
As procedures associated with events frequently just return a
|
|
fixed text, the text itself may be defined as the event handler
|
|
in place of the procedure to save the overhead of the procedure
|
|
call.<tt> </tt>
|
|
<p>
|
|
 <tt> </tt> <tt> </tt> <tt> </tt>Predefined Scheme procedures are supplied for events such as the
|
|
requests ``.de'', ``.nr'', ``.ds'', and the corresponding escape
|
|
sequences `\n' and `\*' to support user-defined macros, strings,
|
|
and number registers.<tt> </tt>
|
|
In any case, specific event handlers registered for macros,
|
|
strings, and number registers supersede any user-supplied
|
|
definitions.<tt> </tt>
|
|
Thus, the author of a document can attach a
|
|
special translation rule to a macro, string, or number register
|
|
defined in the document to take effect when the document is processed by
|
|
<i>unroff</i>.<tt> </tt>
|
|
This is particularly important for high-level, structure-oriented
|
|
target languages like SGML, as the the micro-formatting
|
|
used by typical, more complex troff macros and by many low-level requests
|
|
may not be expressible in such languages.<tt> </tt>
|
|
As a case in point, it would obviously be impossible to translate, for
|
|
example, the ``.IP'' macro defined by the ``ms'' package to a
|
|
language such as HTML just by looking at the definition of the macro.<tt> </tt>
|
|
For this reason,
|
|
<i>unroff
|
|
</i>does not really load the actual macro definitions for a troff macro
|
|
package selected via the ``-m'' option; instead, an event handler
|
|
is defined for each macro exported by the package to generate
|
|
whatever represents the corresponding macro's function in the
|
|
target language.<tt> </tt>
|
|
<p><hr>
|
|
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 21, 1996, <tt> </tt> <tt> </tt>net@informatik.uni-bremen.de</body>
|
|
</html>
|