unroff interprets a troff document as a sequence of chunks of normal text and interspersed ``events''. Plain text is usually just copied to the current output (a file or standard output). The output produced for an event is determined by an ``event handler'' (usually a Scheme procedure) that can be associated with each event. 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. 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. An event handling procedure can be defined for
When invoked, every Scheme procedure associated with one of the above events receives one or more arguments. 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). 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. The exact arguments passed to each type of event handler will be explained below.
A Scheme procedure associated with an event must return a string which is then output in place of whatever input triggered the event. Here, and in a number of other places, a Scheme symbol or a Scheme is accepted as an alternative to a string return value. Event handling procedures are free to directly produce output in addition to returning it as a result. 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.
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. In any case, specific event handlers registered for macros, strings, and number registers supersede any user-supplied definitions. 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 unroff. 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. 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. For this reason, unroff 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.