1738 lines
53 KiB
Plaintext
1738 lines
53 KiB
Plaintext
.\" $Revision: 1.12 $
|
|
.
|
|
.if !\n(.U .so tmac.hyper
|
|
.
|
|
.ds Ve 1.0
|
|
.ds Sc http://www-swiss.ai.mit.edu/scheme-home.html
|
|
.ds Md .
|
|
.
|
|
.fp 5 C
|
|
.pl 11i
|
|
.
|
|
.de Es
|
|
.ie n .DS I 3n
|
|
.el .DS
|
|
.nr sF \\n(.f
|
|
.ft 5
|
|
.ps -1
|
|
.vs -1
|
|
..
|
|
.
|
|
.de Ee
|
|
.ft \\n(sF
|
|
.ps
|
|
.vs
|
|
.DE
|
|
..
|
|
.
|
|
.de El
|
|
.sp .6
|
|
..
|
|
.
|
|
.nr P 0
|
|
.
|
|
.de Ps
|
|
.nr P 1 1
|
|
.SH
|
|
..
|
|
.de Pe
|
|
.nr P 0 0
|
|
..
|
|
.de Pr
|
|
.ds xx "
|
|
.if \\n(.$>=2 .as xx " \f2\\$2\fP
|
|
.if \\n(.$>=3 .as xx " \f2\\$3\fP
|
|
.if \\n(.$>=4 .as xx " \f2\\$4\fP
|
|
.if \\n(.$>=5 .as xx " \f2\\$5\fP
|
|
.if \\n(.$>=6 .as xx " \f2\\$6\fP
|
|
.if \\n(.$>=7 .as xx " \f2\\$7\fP
|
|
.if \\n(.$>=8 .as xx " \f2\\$8\fP
|
|
.if \\n(.$>=9 .as xx " \f2\\$9\fP
|
|
.if !\\nP .SH
|
|
.if \\n+P>2 .br
|
|
(\\$1\\*(xx)
|
|
..
|
|
.de Pa
|
|
.ds xx "
|
|
.if \\n(.$>=3 .as xx " \f2\\$3\fP
|
|
.if \\n(.$>=4 .as xx " \f2\\$4\fP
|
|
.if \\n(.$>=5 .as xx " \f2\\$5\fP
|
|
.if \\n(.$>=6 .as xx " \f2\\$6\fP
|
|
.if \\n(.$>=7 .as xx " \f2\\$7\fP
|
|
.if \\n(.$>=8 .as xx " \f2\\$8\fP
|
|
.if \\n(.$>=9 .as xx " \f2\\$9\fP
|
|
.if !\\nP .SH
|
|
.if \\n+P>2 .br
|
|
.Ha \\$1 "(\\$2\\*(xx)"
|
|
..
|
|
.
|
|
.TL
|
|
unroff \*(Ve Programmer's Manual
|
|
.AU
|
|
Oliver Laumann
|
|
.AB no
|
|
.I unroff
|
|
is a programmable, extensible troff translator that useful for
|
|
converting documents with embedded troff markup into another
|
|
format.
|
|
Although
|
|
.I unroff
|
|
has been designed with higher-level, structure-oriented target
|
|
languages (such as SGML) in mind, it fully supports all constructs
|
|
and idiosyncrasies of ordinary troff, so that even low-level
|
|
formatting requests can be handled correctly if desired.
|
|
.PP
|
|
Translation rules for a specific output format and knowledge about
|
|
existing troff macro packages are not hard-wired in
|
|
.I unroff ,
|
|
instead, the translation is controlled by a user-supplied set
|
|
of procedures written in the
|
|
.Hr -url \*(Sc "\f2Scheme\fP programming language" .
|
|
.Hr "\f2Scheme\fP programming language."
|
|
Interpretation of the procedures is facilitated by a full Scheme
|
|
interpreted embedded in
|
|
.I unroff .
|
|
This manual describes the Scheme primitives provided by
|
|
.I unroff
|
|
that can be used to customize the translation rules implemented
|
|
by existing back-ends and to write new ones for new output formats.
|
|
.AE
|
|
.NH
|
|
Additional Documentation
|
|
.PP
|
|
For a general overview of
|
|
.I unroff
|
|
and a description from the user's perspective, please read the
|
|
.Hr -url \*(Md/unroff.1.html "manual page"
|
|
.Hr "manual page"
|
|
.I unroff (1)
|
|
that accompanies the distribution.
|
|
In addition, there exists one manual page for each output format
|
|
for which a back-end is provided, and another one for each
|
|
combination of output format and troff macro package explaining
|
|
the translation rules associated with the individual macros.
|
|
For example, the back-end for the Hypertext Markup Language (HTML)
|
|
that is part of the distribution and that supports the
|
|
.B \-man
|
|
and
|
|
.B \-ms
|
|
macros comes with these manual pages:
|
|
.Es
|
|
.Hr -url \*(Md/unroff-html.1.html unroff-html(1)
|
|
.Hr -url \*(Md/unroff-html-man.1.html unroff-html-man(1)
|
|
.Hr -url \*(Md/unroff-html-ms.1.html unroff-html-ms(1)
|
|
.Hr unroff-html(1)
|
|
.Hr unroff-html-man(1)
|
|
.Hr unroff-html-ms(1)
|
|
.Ee
|
|
.PP
|
|
This text assumes familiarity with the basic troff and Scheme concepts.
|
|
For a troff manual, refer to the documentation provided by
|
|
your UNIX system's vendor.
|
|
As
|
|
.I unroff
|
|
supports a number of troff extensions introduced by the free
|
|
.I groff
|
|
formatter (which is part of the GNU project), you may want to read the
|
|
manual page
|
|
.I troff (1)
|
|
that is included in the groff distribution.
|
|
.PP
|
|
.I unroff
|
|
is centered around
|
|
.I Elk ,
|
|
the Scheme-based Extension Language Kit.
|
|
For a description of the Elk-specific Scheme language features
|
|
please refer to the documentation included in the Elk distribution
|
|
(which is freely available).
|
|
An overview of Elk can be found in:
|
|
Oliver Laumann and Carsten Bormann, Elk: The Extension Language Kit,
|
|
.I "USENIX Computing Systems" ,
|
|
vol. 7, no. 4, pp. 419\-449, 1994.
|
|
The Scheme language is described in several textbooks; and the
|
|
Revised^4 Report on the Algorithmic Language Scheme, on which
|
|
the IEEE Standard for Scheme is based, can be downloaded from
|
|
several major FTP sites.
|
|
.NH
|
|
Where to Place Scheme Code?\&
|
|
.PP
|
|
.I unroff
|
|
accepts Scheme code in a number of places.
|
|
First, a several Scheme files are loaded on startup:
|
|
.Es
|
|
scm/troff.scm
|
|
scm/\f2format\fP/common.scm
|
|
scm/\f2format\fP/\f2package\fP.scm
|
|
~/.unroff
|
|
.Ee
|
|
.PP
|
|
The first three path names are relative to a site-specific library
|
|
directory where the files have been installed by the system
|
|
administrator.
|
|
``troff.scm'' contains definitions that are independent of the
|
|
actual output format and troff macro-package; and the
|
|
file ``.unroff'' (loaded from the caller's home directory) typically
|
|
contains Scheme code to define user-preferences and to tailor
|
|
and extend the translation rules implemented by the files loaded
|
|
from a central location.
|
|
See the
|
|
.Hr -url \*(Md/unroff.1.html "manual page"
|
|
.Hr "manual page"
|
|
.I unroff (1)
|
|
for more information.
|
|
.PP
|
|
Additional files with user-supplied Scheme definitions
|
|
(e.\|g. translation rules for user-defined macros) can be passed to
|
|
.I unroff
|
|
by mentioning them in the command line.
|
|
In general, troff input files and Scheme source files can be mixed
|
|
arbitrarily when calling
|
|
.I unroff .
|
|
Finally, Scheme code can be embedded directly in the troff documents
|
|
by means of the new ``.##'' troff request and the corresponding
|
|
extension to the ``.ig'' request as explained in the
|
|
.Hr -url \*(Md/unroff.1.html "manual page" .
|
|
.Hr "manual page."
|
|
Such inline Scheme code is executed on-the-fly when it is encountered
|
|
by the parser while processing the document.
|
|
.NH
|
|
.Ha .events "Events and Event Handling"
|
|
.PP
|
|
.I 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
|
|
.if !\n(.U .RS
|
|
.IP \(bu
|
|
each troff request, including requests that perform intrinsic troff
|
|
functions, such as ``.de'' and ``.if''
|
|
.IP \(bu
|
|
each troff macro, whether user-defined or part of a macro
|
|
package
|
|
.IP \(bu
|
|
each troff string
|
|
.IP \(bu
|
|
each number register
|
|
.IP \(bu
|
|
each special character
|
|
.IP \(bu
|
|
each escape sequence
|
|
.IP \(bu
|
|
each character (to provide character translations)
|
|
.IP \(bu
|
|
each inline equation enclosed by the current
|
|
.I eqn (1)
|
|
delimiter characters
|
|
.IP \(bu
|
|
each end of sentence (defined as a period, exclamation mark, or
|
|
question mark, followed by a newline).
|
|
.if !\n(.U .RE
|
|
.PP
|
|
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 `\eh'
|
|
(horizontal space) is passed the name of the escape sequence
|
|
(the letter `h') as well as the argument to `\eh' (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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Predefined Scheme procedures are supplied for events such as the
|
|
requests ``.de'', ``.nr'', ``.ds'', and the corresponding escape
|
|
sequences `\en' and `\e*' 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
|
|
.I 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,
|
|
.I 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.
|
|
.NH
|
|
Defining Event Handlers
|
|
.PP
|
|
In the following list of Scheme primitives, the argument
|
|
.I name
|
|
denotes the name of a troff request, macro, escape sequence
|
|
etc. (without any initial period or escape character) and can be
|
|
supplied in form of a Scheme string, a Scheme symbol, or
|
|
a Scheme character:
|
|
.Es
|
|
(defrequest "ti" ...)
|
|
.El
|
|
(defrequest 'sp ...)
|
|
.El
|
|
(defescape #\eh ...)
|
|
.Ee
|
|
(the primitives
|
|
.I defrequest
|
|
and
|
|
.I defescape
|
|
will be introduced in a moment).
|
|
An argument named
|
|
.I handler
|
|
is either a procedure (usually a lambda expression) which returns
|
|
a string, a symbol, or a character; or
|
|
.I handler
|
|
can itself be specified as a string, symbol, or character.
|
|
In addition, the literal ``#f'' (false) can be supplied as a
|
|
.I handler
|
|
argument to remove any event handler that is currently associated with
|
|
that event.
|
|
Each of the ``def'' primitives listed below returns the handler
|
|
that was previously associated with the corresponding event,
|
|
or ``#f'' if the event was not handled.
|
|
.Pr defrequest name handler
|
|
.PP
|
|
Associates the given handler with the given troff request.
|
|
If
|
|
.I handler
|
|
is a procedure, it is passed the request's name and arguments
|
|
as strings when called later.
|
|
Passing the name of the request as the first argument aids in
|
|
associating the same procedure with several different requests.
|
|
.I unroff
|
|
does not limit the number of arguments to requests, thus,
|
|
an event handling procedure for a requests that takes a variable
|
|
number of arguments could be defined like this:
|
|
.Es
|
|
(defrequest 'rm
|
|
(lambda (rm . args) ...))
|
|
.Ee
|
|
.LP
|
|
If the request is invoked with fewer arguments than the procedure
|
|
has formal arguments, the remaining arguments are bound to
|
|
the empty string.
|
|
If the request is invoked with
|
|
.I more
|
|
arguments than the procedure has formal arguments, the last lambda
|
|
variable is assigned a string consisting of the (space-delimited)
|
|
arguments left over after the other formal arguments have been bound to
|
|
the other actual arguments.
|
|
However, if
|
|
.I handler
|
|
has only one formal argument, an error message is displayed when the
|
|
request is called with any arguments at all and the event is skipped.
|
|
For example, consider the following handler for the (non-existing)
|
|
request ``xx'':
|
|
.Es
|
|
(defrequest 'xx
|
|
(lambda (name a b) ...))
|
|
.Ee
|
|
The procedure's arguments
|
|
.I a
|
|
and
|
|
.I b
|
|
will be bound as follows when the request is invoked:
|
|
.Es
|
|
\&.xx foo name="xx" a="foo" b=""
|
|
.El
|
|
\&.xx foo bar baz name="xx" a="foo" b="bar baz"
|
|
.Ee
|
|
.Pr defmacro name handler
|
|
.PP
|
|
Associates
|
|
.I handler
|
|
with the given troff macro, superseding
|
|
any definition for this macro established by the ordinary ``.de''
|
|
request.
|
|
The only difference between
|
|
.I defrequest
|
|
and
|
|
.I defmacro
|
|
is the way arguments are bound in case
|
|
.I handler
|
|
is a procedure
|
|
(troff employs slightly different rules when parsing the call
|
|
to a request and a macro invocation).
|
|
The quote character can be used in the latter case to surround
|
|
arguments containing spaces, while quote characters are treated as
|
|
normal characters in requests, which allows for the following
|
|
remarkable troff idiom:
|
|
.Es
|
|
\&.ds xy "hello
|
|
.Ee
|
|
In contrast to event handlers defined for requests, the formal
|
|
arguments of a handler procedure associated with a macro must
|
|
match the actual arguments in the normal way, that is, as if
|
|
the procedure were invoked from within Scheme.
|
|
A warning message is displayed if the number of macro arguments
|
|
does not match the number of formal procedure arguments, and
|
|
the event is skipped.
|
|
.Pr defspecial name handler
|
|
.PP
|
|
Associates
|
|
.I handler
|
|
with the special character whose name is
|
|
.I name .
|
|
The name must have a length of 2.
|
|
In addition, an empty name can be specified to define a
|
|
``fallback'' handler that is called for special characters
|
|
for which no handler exists.
|
|
Like all event handler procedures,
|
|
.I handler
|
|
can have arbitrary side-effects in addition to returning a
|
|
result; for example, the procedure may display a warning message
|
|
if the special character cannot be represented in the target
|
|
language and an approximation must be rendered instead.
|
|
.Pr defstring name handler
|
|
.PP
|
|
Associates a handler with the specified troff string.
|
|
As
|
|
.I unroff
|
|
provides a default handler for the request ``.ds'' to implement
|
|
used-defined strings,
|
|
.I defstring
|
|
is primarily used to give definitions for strings exported by
|
|
troff macro packages.
|
|
.Pr defnumreg name handler
|
|
.PP
|
|
This request behaves like
|
|
.I defstring ,
|
|
except that it works on number registers.
|
|
Note that the Scheme primitive
|
|
.I number\(mi>string
|
|
may have to be used by
|
|
.I handler
|
|
(if it is a procedure) to convert a numeric result into a string
|
|
that can be returned from the handler.
|
|
.LP
|
|
In troff input, number registers as well as strings, special
|
|
characters, and escape sequences can be denoted using the groff
|
|
``long name'' syntax, unless troff compatibility has been enabled:
|
|
.Es
|
|
\en[numreg] \en[string] \ef[font] \e[em] ...
|
|
.Ee
|
|
.Pr defescape name handler
|
|
.PP
|
|
Associates an event handler with an escape sequence.
|
|
.I name
|
|
must have a length of 1, unless the empty string is
|
|
given to define a ``fallback'' event handler (as with
|
|
.I defspecial ).
|
|
Handlers defined for certain escape sequences are passed
|
|
a second argument in addition to the name of the escape sequence.
|
|
This is true for all escape sequences that have an argument
|
|
according to the troff specification:
|
|
.Es
|
|
\eb \ec \ef \eh \ek \el \en \eo \es \ev \ew \ex \ez
|
|
\e* \e$ \e"
|
|
.Ee
|
|
In addition, handlers for these groff escape sequences are passed an
|
|
additional argument unless troff compatibility is enabled:
|
|
.Es
|
|
\eA \eC \eL \eN \eR \eV \eY \eZ
|
|
.Ee
|
|
The form of an escape sequence argument is determined by the
|
|
troff specification and cannot be programmed; for example, the
|
|
handler for `\ez' is passed a character or a special character,
|
|
and the handler for `\e"' is invoked with the rest of the current
|
|
input line sans the terminating newline.
|
|
(The latter can be used to translate troff comments.)
|
|
.LP
|
|
Handlers registered for the escape sequences `\en' and '\es' are
|
|
passed an optional third argument, one of the Scheme characters
|
|
#\e+ and #\e\(mi, if the escape sequence argument begins with a sign.
|
|
The sign is then stripped from the actual argument.
|
|
.LP
|
|
As `\en' and `\e*' are treated as ordinary escape sequences,
|
|
handlers can be defined for them to achieve some form of fallback
|
|
for number register and strings.
|
|
.I unroff
|
|
provides suitable default handlers for `\en', `\e*', and '\e$' as part
|
|
of the implementation of user-defined number registers, strings,
|
|
and macros.
|
|
These handlers can be overridden if desired.
|
|
.Pr defchar name handler
|
|
.PP
|
|
Associates
|
|
.I handler
|
|
with a character.
|
|
.I name
|
|
must have a length of 1.
|
|
Each time the specified character is encountered in the troff
|
|
input, the result (or value) of
|
|
.I handler
|
|
is output in place of the character.
|
|
Character translations are not applied to the result of event
|
|
handlers; event procedures can use the Scheme primitive
|
|
.Hr -symbolic .translate \f2translate\fP
|
|
.Hr \f2translate\fP
|
|
(as described below) to execute the character translations
|
|
established by calls to
|
|
.I defchar
|
|
if desired.
|
|
.LP
|
|
.I defchar
|
|
currently has a number of weaknesses.
|
|
The argument cannot be a special character
|
|
(that is,
|
|
.I name
|
|
must be a plain character), and the mechanism cannot be used
|
|
to achieve true
|
|
.I output
|
|
translations as with the troff request ``.tr'' or the groff
|
|
request ``.char''.
|
|
.Pr defsentence handler
|
|
.PP
|
|
Defines a handler to be consulted on end of sentence.
|
|
If
|
|
.I handler
|
|
is a procedure, it is passed the punctuation mark ending the
|
|
sentence as its argument (in form of a Scheme character).
|
|
In any case, if an event handler has been specified, its result
|
|
(or value) is output in place of the end-of-sentence mark and
|
|
the newline character following it.
|
|
.Pr defequation handler
|
|
.PP
|
|
Defines a handler for
|
|
.I eqn
|
|
inline equations.
|
|
If
|
|
.I handler
|
|
is a procedure, it is passed the contents of the inline equation
|
|
(with the delimiters stripped) as an argument.
|
|
When an inline equation is encountered in the troff input and a handler
|
|
has been defined for inline equations, the handler's result (or value)
|
|
is output in place of the equation.
|
|
.LP
|
|
For inline equations to be recognized, delimiters must be defined first
|
|
by passing
|
|
.I eqn
|
|
input that includes a ``delim'' directive to the Scheme primitive
|
|
.Hr -symbolic .filter-eqn-line \f2filter-eqn-line\fP
|
|
.Hr \f2filter-eqn-line\fP
|
|
(explained below), as is usually done
|
|
by the event handler associated with the request ``.EQ''.
|
|
.NH
|
|
Querying Event Handlers
|
|
.PP
|
|
In addition to associating event handlers with events by means
|
|
of the ``def'' primitives, several primitives exist to query
|
|
the currently defined handler for a given event:
|
|
.Ps
|
|
.Pr requestdef name
|
|
.Pr macrodef name
|
|
.Pr specialdef name
|
|
.Pr stringdef name
|
|
.Pr numregdef name
|
|
.Pr escapedef name
|
|
.Pr chardef name
|
|
.Pr sentencedef
|
|
.Pr equationdef
|
|
.Pe
|
|
.PP
|
|
Observe that the name of each primitive is derived from the name
|
|
of the corresponding ``def'' primitive by exchanging the word
|
|
``def'' and the rest of the name.
|
|
Each
|
|
.I name
|
|
argument is subject to the constraints described under the
|
|
corresponding ``def'' primitive above.
|
|
Each primitive returns whatever object has been registered as
|
|
the event handler (procedure, string, symbol, character);
|
|
or #f if no handler has been defined for the event.
|
|
.NH
|
|
Event Procedures with Side-Effects
|
|
.PP
|
|
Besides the basic events described in the
|
|
.Hr -symbolic .events "preceding sections" ,
|
|
.Hr "preceding sections,"
|
|
another group of\*-slightly different\*-events exist and can
|
|
be handled by user-defined Scheme procedures.
|
|
These events are not related to troff functions, but to a number of
|
|
other conditions that are encountered when processing documents:
|
|
.if !\n(.U .RS
|
|
.IP \(bu
|
|
the end of an input line
|
|
.IP \(bu
|
|
the beginning of a troff input file processed by
|
|
.I unroff
|
|
.IP \(bu
|
|
the end of a troff input file
|
|
.IP \(bu
|
|
startup of the program
|
|
.IP \(bu
|
|
termination of the program
|
|
.IP \(bu
|
|
a keyword/value option encountered in the command line.
|
|
.if !\n(.U .RE
|
|
.PP
|
|
Among other tasks, these events can be used to generate a prologue and
|
|
epilogue for each input file.
|
|
In contrast to the events described in the previous section, handlers for
|
|
these events are called solely for their side-effects.
|
|
Each event handler must be a Scheme procedure.
|
|
Their results are ignored, thus the procedures must have side-effects
|
|
to be useful.
|
|
Another difference is that more than one event handler can be associated
|
|
with each request.
|
|
A numeric
|
|
.I level
|
|
(a small integer number) is specified together with each event handler,
|
|
and when the corresponding event is triggered, all procedures
|
|
defined for this event are executed in increasing order as indicated by
|
|
their levels.
|
|
.Pr defevent event level handler
|
|
.PP
|
|
Associates the procedure
|
|
.I handler
|
|
with an event and returns the previous event handler registered
|
|
for this combination of event and level.
|
|
.I level
|
|
is an integer between 0 and 99;
|
|
.I handler
|
|
is a procedure, or the literal #f to remove a previously defined handler.
|
|
.I event
|
|
indicates the type of event and is one of the following Scheme symbols:
|
|
.I line
|
|
(end of input line),
|
|
.I prolog
|
|
(beginning of input file),
|
|
.I epilog
|
|
(end of input file),
|
|
.I start
|
|
(program start),
|
|
.I exit
|
|
(program termination),
|
|
.I option
|
|
(keyword/value command line option).
|
|
.LP
|
|
Procedures defined for the events
|
|
.I prolog
|
|
and
|
|
.I epilog
|
|
are called with two string arguments:
|
|
the path name (as specified by the user) and the file name component of
|
|
the troff input file whose processing has just begun or finished,
|
|
or the string ``stdin'' if
|
|
.I unroff
|
|
is taking its input from standard input.
|
|
Procedures defined for the event
|
|
.I option
|
|
are passed the option's name and value as strings.
|
|
All other event procedures are invoked without arguments.
|
|
.I unroff
|
|
provides a default handler for
|
|
.I option
|
|
(see the
|
|
.Hr -symbolic .options "primitives for options"
|
|
.Hr "primitives for options"
|
|
below).
|
|
.LP
|
|
Example:
|
|
.Es
|
|
(defevent 'exit 50 ; cleanup on exit
|
|
(lambda ()
|
|
...))
|
|
.Ee
|
|
The handler defined in this way will be executed on termination,
|
|
after any handlers with levels 0\-49.
|
|
.Pr eventdef event level
|
|
.PP
|
|
Returns the procedure defined as a handler for
|
|
.I event
|
|
and
|
|
.I level ,
|
|
or #f if no such handler exists.
|
|
See
|
|
.I defevent
|
|
above for a description of the arguments.
|
|
.NH
|
|
How Troff Input is Processed
|
|
.PP
|
|
To be able to write non-trivial event handling procedures, it helps
|
|
to have a look at how troff input is processed, especially since
|
|
the parser of
|
|
.I unroff
|
|
works somewhat differently than ordinary troff.
|
|
In particular, the parser cannot blindly rescan the result of
|
|
handlers for escape sequences or special characters, as these
|
|
handlers will probably generate text in the
|
|
.I "target language"
|
|
that cannot be interpreted as troff input any longer.
|
|
Here is a brief overview of the parsing process.
|
|
.PP
|
|
Each input line is first scanned for references to troff strings and
|
|
number registers (this scanning pass will later be referred to as the
|
|
``expansion phase'').
|
|
For each `\e*' or `\en' sequence found in the input line,
|
|
.I unroff
|
|
checks whether a handler for the string or number register has
|
|
been defined with
|
|
.I defstring
|
|
or
|
|
.I defnumreg ,
|
|
and if this is the case, replaces the string or number register
|
|
reference by the result (or value) of the handler.
|
|
Otherwise, if a handler for the escape sequence `\e*' or `\en'
|
|
proper has been defined, that handler is called.
|
|
Otherwise the reference is left untouched and scanning resumes
|
|
behind it\**.
|
|
.FS
|
|
Although the result of specific event handlers defined for
|
|
strings is not rescanned, the handler for `\e*' that is supplied by
|
|
.I unroff
|
|
to implement user-defined strings does rescan the contents of
|
|
a string when it is expanded.
|
|
.FE
|
|
Comments are recognized in this phase, too, by calling the handler
|
|
for the `\e"' escape sequence if there is one.
|
|
.PP
|
|
Next, the parser checks whether the result of the first phase
|
|
is a request or macro invocation (that is, begins with a period
|
|
or an apostrophe).
|
|
If this is the case, the arguments are parsed mimicking the
|
|
behavior of ordinary troff.
|
|
The rules for macro arguments are employed if
|
|
a handler has been defined
|
|
for the token after the period with
|
|
.I defmacro ,
|
|
else the rules for requests are used.
|
|
The handler for the macro or request is then used, or applied
|
|
to the arguments if it is a procedure.
|
|
.PP
|
|
If the input line does not contain a request or macro invocation,
|
|
it is scanned a second time to take care of escape sequences
|
|
and special characters (for lack of a better term, we will call
|
|
this phase ``escape parsing'').
|
|
Every escape character reference, special character, and inline
|
|
equation is replaced by the result (or value) of the event
|
|
handler registered for it, or left in place if there is no handler.
|
|
Character translations defined by means of
|
|
.I defchar
|
|
are also executed in this phase.
|
|
.PP
|
|
Finally, the result of the escape parsing phase or of the request or
|
|
macro invocation is checked whether it constitutes the end of a
|
|
sentence, and if so, the handler for this event is called
|
|
(actually, in the former case, the check is applied before
|
|
.I and
|
|
after the escape parsing and must succeed both times).
|
|
As the final step the line is output, and any handlers for the
|
|
.I line
|
|
event are invoked.
|
|
.PP
|
|
An important thing to note is that the arguments passed to a handler
|
|
defined for a request or macro are not scanned for escape sequences
|
|
and special characters.
|
|
Therefore event procedures must explicitly parse their arguments if
|
|
desired by calling the Scheme primitive
|
|
.Hr -symbolic .parse \f2parse\fP
|
|
.Hr \f2parse\fP
|
|
(which will be described in the next section).
|
|
Consider, for example, an event procedure associated with a
|
|
macro ``IP'':
|
|
.Es
|
|
(defmacro 'IP
|
|
(lambda (IP tag . indent)
|
|
...))
|
|
.Ee
|
|
and a call to the macro with an argument containing a
|
|
special character:
|
|
.Es
|
|
\&.IP \e(bu
|
|
.Ee
|
|
As the argument to the event procedure is only scanned for
|
|
strings and number registers, the variable
|
|
.I tag
|
|
will be bound to the string ``\e(bu''.
|
|
Applying
|
|
.I parse
|
|
to the argument will turn it into whatever is the target language
|
|
representation for the special character ``\e(bu'' (that is, the
|
|
result of the event handler for the special character).
|
|
Whether or not arguments will have to be parsed depends on the
|
|
particular request or macro; the procedure implementing the request
|
|
``.tm'', for instance, will print its ``raw'' argument (a sample
|
|
event handler for the request ``.tm'' is supplied by
|
|
.I unroff ).
|
|
.NH
|
|
Calling the Parser
|
|
.PP
|
|
The following Scheme primitives are used by event procedures for
|
|
requests, macros, and escape characters to parse their arguments
|
|
or to parse lines of text that have been read from an input source.
|
|
Each of the primitives can be invoked with zero or more arguments
|
|
of type string, symbol, or character.
|
|
The arguments are concatenated to form a Scheme string which is then
|
|
passed to the parser, and the result is returned as a new string.
|
|
.Pa .parse parse . args
|
|
.PP
|
|
This primitive feeds its arguments to the ``escape parsing''
|
|
pass as described in the previous section.
|
|
It scans its arguments for special characters and escape
|
|
sequences and replaces them by the corresponding event values
|
|
(or results), and it executes character translations.
|
|
.Pa .translate translate . args
|
|
.PP
|
|
Like
|
|
.I parse
|
|
above, except that only output character translations (defined by calls to
|
|
.I defchar )
|
|
are executed.
|
|
.Pr parse-expand . args
|
|
.PP
|
|
This primitive applies the ``expansion parsing'' phase (as described in the
|
|
previous section) to its arguments.
|
|
Compared to
|
|
.I parse ,
|
|
.I parse-expand
|
|
is only used rarely, as input lines read in the normal way are
|
|
scanned for string and number register references anyway.
|
|
The sample implementation supplied by
|
|
.I unroff
|
|
for the requests ``.ds'', ``.as'', and '\e*' makes use of this primitive
|
|
to rescan the contents of user-defined strings upon interpolation.
|
|
.Pr parse-line . args
|
|
.PP
|
|
This primitive parses an entire input line, which may contain a call
|
|
to a request or macro, as described in the previous section.
|
|
The line made up by the primitive's arguments is treated exactly as
|
|
it if were read from an input file, although it need not have a
|
|
terminating newline.
|
|
Two places where this primitive is required are the handler for
|
|
the request ``.so'' and the code that expands user-defined macros.
|
|
.Pr parse-copy-mode . args
|
|
.PP
|
|
The primitive
|
|
.I parse-copy-mode
|
|
parses its arguments in a manner similar to troff ``copy mode''.
|
|
In this mode, escape sequences beginning with '\e$' are dealt
|
|
with (by calling their event procedures), the sequence `\e\e'
|
|
is replaced by a single `\e', and each occurrence of `\e.'
|
|
is replaced by a period.
|
|
Macro bodies are parsed in copy mode during macro definition and again
|
|
when the macros are expanded.
|
|
.PP
|
|
The sample implementation of user-defined macros supplied by
|
|
.I unroff
|
|
defines suitable event handlers for the usual
|
|
.Es
|
|
\e$1 \e$2 ...
|
|
.Ee
|
|
escape sequences (there is no limit to the number of arguments,
|
|
and the groff long name convention may be used to denote an
|
|
argument number), and in addition for the groff extensions
|
|
.Es
|
|
\e$0 \e$* \e$@
|
|
.Ee
|
|
as explained in the
|
|
.Hr -url \*(Md/unroff.1.html "manual page"
|
|
.Hr "manual page"
|
|
.I unroff (1).
|
|
.Ps
|
|
.Pr parse-expression expr fail scale
|
|
.Pr parse-expression-rest expr fail scale
|
|
.Pe
|
|
.PP
|
|
These primitives evaluate the numeric expression specified by
|
|
the string argument
|
|
.I expr
|
|
and return the result as an exact number.
|
|
The usual troff expression syntax, operators, and scale
|
|
indicators are supported.
|
|
If an error occurs during evaluation (for instance, if
|
|
.I expr
|
|
is not a syntactically valid expression),
|
|
a warning message is displayed and
|
|
.I fail
|
|
(which may be an arbitrary Scheme object) is returned.
|
|
The character argument
|
|
.I scale
|
|
is the default scale indicator, for example `#\em', or `#\eu'
|
|
for basic units.
|
|
.PP
|
|
The primitive
|
|
.I parse-expression-rest
|
|
is identical to
|
|
.I parse-expression ,
|
|
except that its return value is a cons cell whose car consists
|
|
of the result of the evaluation and whose cdr is the rest of
|
|
.I expr
|
|
starting at the character position where parsing of the
|
|
expression stopped.
|
|
In other words, the primitive evaluates the portion of
|
|
.I expr
|
|
that constitutes a valid expression, and it returns the result
|
|
and whatever is left over.
|
|
Warning messages are also suppressed, except if an overflow occurs
|
|
during evaluation.
|
|
.I parse-expression-rest
|
|
is useful for tasks like parsing the argument of the escape
|
|
sequences `\el' and `\eL' where an expression is immediately
|
|
followed by another character.
|
|
Examples:
|
|
.Es
|
|
(parse-expression "(2+8)/5" 0 #\eu) \(rh 2
|
|
(parse-expression "foo" #f #\eu) \(rh #f; prints warning
|
|
.El
|
|
(parse-expression-rest "1+1" #f #\eu) \(rh (2 . "")
|
|
(parse-expression-rest "(2+8)/5foo" 0 #\eu) \(rh (2 . "foo")
|
|
(parse-expression-rest "15\e&-" 0 #\eu) \(rh (15 . "\e&-")
|
|
.Ee
|
|
.Pr char-expression-delimiter? char
|
|
.PP
|
|
Returns #t if the character argument
|
|
.I char
|
|
is valid as the first character of a numeric expression (e.\|g. a digit),
|
|
otherwise #f.
|
|
.Ps
|
|
.Pr set-scaling! scale factor divisor
|
|
.Pr get-scaling scale
|
|
.Pe
|
|
.PP
|
|
These primitives set and read the scale factor and divisor for
|
|
the specified scale indicator.
|
|
.I scale
|
|
is the scale indicator (a character);
|
|
.I factor
|
|
and
|
|
.I divisor
|
|
are integers.
|
|
.I get-scaling
|
|
returns the scaling for the specified scale indicator as a pair
|
|
of integers.
|
|
The factors and divisors are initially set to 1 for all scale
|
|
indicators; they must be assigned useful values by each back-end.
|
|
.NH
|
|
Streams
|
|
.PP
|
|
Input, output, and storage of text lines in
|
|
.I unroff
|
|
are centered around a new Scheme data type named
|
|
.I stream
|
|
and a set of primitives that work on streams.
|
|
A stream can act as a source (input stream) or as a sink (output
|
|
stream) for lines of text.
|
|
Streams not only serve as the basis for input and output operations
|
|
and for the exchange of text with shell commands, but can also be used
|
|
to temporarily buffer lines of text (e.g. footnotes or tables of
|
|
contents) and to implement user-defined macros in a simple way.
|
|
Each input or output stream can be connected to one of the
|
|
following three types of
|
|
.I targets :
|
|
.if !\n(.U .RS
|
|
.IP \(bu
|
|
a file, or the program's standard input or standard output
|
|
.IP \(bu
|
|
a UNIX pipe connected to a shell running a shell command
|
|
.IP \(bu
|
|
an internal
|
|
.I buffer
|
|
whose lifetime is limited to that of the current invocation of
|
|
.I unroff .
|
|
.if !\n(.U .RE
|
|
.PP
|
|
Buffers act similar to (initially empty) files, except that
|
|
they are not visible from the outside and that they are destroyed
|
|
automatically on exit of the program.
|
|
Once a buffer has been filled with text through an output stream,
|
|
it can be reopened and read through an input stream multiple times.
|
|
However, if a buffer is currently written through an output stream,
|
|
no more streams may refer to the same buffer.
|
|
As the contents of buffers kept in memory, input and output operations
|
|
on buffers are fast.
|
|
The sample implementation of user-defined macros utilizes buffers
|
|
to store the macro bodies; a macro can then be expanded simply
|
|
by redirecting the current input source to the corresponding buffer
|
|
temporarily.
|
|
.PP
|
|
Both the parser and all input and output primitives operate on a
|
|
.I "current input stream"
|
|
and a
|
|
.I "current output stream" ;
|
|
input and output is always performed using these two streams.
|
|
On startup,
|
|
.I unroff
|
|
initializes the current output stream to either point to
|
|
standard output or to a newly created output file (usually depending on
|
|
the value of the
|
|
.B document
|
|
option).
|
|
If the current output stream is assigned the literal #f,
|
|
output is sent to standard output\**.
|
|
.FS
|
|
While #f indicates ``standard output'' when assigned to
|
|
the current output stream, it is an error to call an input primitive
|
|
after #f has been assigned to the current
|
|
.I input
|
|
stream.
|
|
This may be considered a mis-feature; the current input and
|
|
output streams should be treated similarly with respect to
|
|
standard input and standard output.
|
|
.FE
|
|
Likewise, for each input file mentioned in the command line,
|
|
a stream pointing to that file is created and assigned to
|
|
the current input stream before the parser starts processing
|
|
the file.
|
|
The rest of this section lists the Scheme primitives operating
|
|
on streams.
|
|
.Pr stream? obj
|
|
.PP
|
|
The type predicate for the new data type.
|
|
It returns #t if
|
|
.I obj
|
|
is a member of the type
|
|
.I stream ,
|
|
otherwise #f.
|
|
.Ps
|
|
.Pr input-stream
|
|
.Pr output-stream
|
|
.Pe
|
|
.PP
|
|
Returns the current input stream, or output stream respectively.
|
|
.Ps
|
|
.Pr open-input-stream target
|
|
.Pr open-output-stream target
|
|
.Pr append-output-stream target
|
|
.Pe
|
|
.PP
|
|
These primitives create a new input stream or output stream pointing
|
|
to the specified target.
|
|
The argument
|
|
.I target
|
|
is a string or a symbol.
|
|
If the target is enclosed in square brackets, it names a buffer;
|
|
if it begins with the pipe symbol `|', a pipe to a shell running
|
|
the rest of the target as a shell command is established; otherwise
|
|
.I target
|
|
is interpreted as a file name.
|
|
.I append-output-stream
|
|
rewinds to the end of the specified output buffer or file before
|
|
the first output operation; it acts like
|
|
.I open-output-stream
|
|
in case of a pipe.
|
|
Examples:
|
|
.Es
|
|
(let* ((buffer (open-output-stream '[temp]))
|
|
(pipe (open-input-stream "|ls -l /usr/lib/tmac"))
|
|
(file (open-input-stream "/etc/passwd")))
|
|
...)
|
|
.Ee
|
|
.Ps
|
|
.Pr set-input-stream! stream
|
|
.Pr set-output-stream! stream
|
|
.Pe
|
|
.PP
|
|
These primitives make the specified stream the
|
|
.I current
|
|
input stream (or output stream respectively).
|
|
.I stream
|
|
must be the result of a call to one of the three primitives that
|
|
open a stream, or #f.
|
|
An error is signaled if
|
|
.I set-input-stream!
|
|
is applied to an output stream or vice versa, or if the stream
|
|
has been closed in the meantime.
|
|
.Pr close-stream stream
|
|
.PP
|
|
Closes the specified stream.
|
|
An error is signaled if the stream is still the current input
|
|
stream or current output stream.
|
|
Once an output stream pointing to a buffer has been closed, the
|
|
buffer can be reopened for reading.
|
|
A stream that is no longer reachable is closed automatically
|
|
during the next run of the garbage collector.
|
|
.Ps
|
|
.Pr stream-buffer? stream
|
|
.Pr stream-file? stream
|
|
.Pr stream-pipe? stream
|
|
.Pe
|
|
.PP
|
|
These predicates return #t if the specified stream points to a
|
|
buffer, a file, or a pipe respectively, otherwise #f.
|
|
.Pr stream-target stream
|
|
.PP
|
|
This primitive returns the target to which the specified stream
|
|
points.
|
|
The return value is a string.
|
|
In case of a pipe, the target is truncated at the first space,
|
|
that is, only the command name is included.
|
|
The target of the current input stream (together with the current
|
|
line number) is displayed as a prefix of error messages and
|
|
can also be obtained through the primitive
|
|
.Hr -symbolic .substitute \f2substitute\fP
|
|
.Hr \f2substitute\fP
|
|
described below.
|
|
.Pr stream-position stream
|
|
.PP
|
|
Returns the current character position of the specified output stream,
|
|
that is, the offset at which the next character will be written.
|
|
The return value for input streams is currently always zero.
|
|
This primitive is useful in conjunction with
|
|
.Hr -symbolic .file-insertions \f2file-insertions\fP
|
|
.Hr \f2file-insertions\fP
|
|
(described below).
|
|
.Pr stream\(mistring target
|
|
.PP
|
|
This primitive opens an input string to the specified target,
|
|
reads from the stream until end-of-stream is reached, closes
|
|
the stream, and returns the concatenation of all the lines that
|
|
have been read as a string\**.
|
|
.FS
|
|
.I stream\(mi>string
|
|
is a misnomer, because the argument of the primitive is not
|
|
a stream, nor does the primitive actually
|
|
.I convert
|
|
a stream to a string as suggested by the `\(mi>' sign.
|
|
.FE
|
|
.NH
|
|
Input and Output Primitives
|
|
.PP
|
|
.I unroff
|
|
provides one new input primitive and one new output primitive that
|
|
work with the current input stream and current output stream (and a
|
|
third primitive which is just an optimization of the latter, as
|
|
well as a few auxiliary functions).
|
|
.Pr emit . args
|
|
.PP
|
|
.I emit
|
|
is the only stream-based output primitive.
|
|
It receives any number of strings, symbols, and characters,
|
|
concatenates its arguments, and sends the resulting string to
|
|
the current output stream (to standard output if the the current
|
|
output stream has been assigned #f).
|
|
.I emit
|
|
is primarily used in situations where text has to
|
|
be output without rescanning it and without applying any
|
|
character translations.
|
|
It is also used from within the event procedures that are called
|
|
for their side-effects, for example, by the
|
|
.I prolog
|
|
and
|
|
.I epilog
|
|
event procedures to generate a header and trailer for each
|
|
output file.
|
|
The primitive returns the empty symbol so that it can be called
|
|
as the last form in an event procedure whose result is used.
|
|
.PP
|
|
Example:
|
|
the new troff request for transparent output, as explained in the
|
|
.Hr -url \*(Md/unroff.1.html "manual page"
|
|
.Hr "manual page"
|
|
.I unroff (1),
|
|
can be implement like this:
|
|
.Es
|
|
(defrequest '>>
|
|
(lambda (>> code)
|
|
(emit code #\enewline)))
|
|
.Ee
|
|
.Pr read-line
|
|
.PP
|
|
This primitive reads the next input line from the current input
|
|
stream and returns it as a string.
|
|
An error is signaled if the current input stream has been bound
|
|
to #f, which is the case, for example, when
|
|
.I unroff
|
|
has been called with the option
|
|
.B \-t
|
|
to start an interactive top level.
|
|
If an incomplete last line (i.\|e. a line without a terminating
|
|
newline) is returned by the target pointed to by the current
|
|
input stream, a newline is appended.
|
|
Thus,
|
|
.I read-line
|
|
always returns at least a string containing a newline character.
|
|
.Pr read-line-expand
|
|
.PP
|
|
This primitive is nothing more than an optimization for
|
|
.Es
|
|
(parse-expand (read-line))
|
|
.Ee
|
|
which has been provided to speed up frequently used functions like
|
|
macro expansion.
|
|
.Pr unread-line string
|
|
.PP
|
|
This primitive pushes back an input line to the current input
|
|
stream, which will then be returned by the next call to
|
|
.I read-line
|
|
or
|
|
.I read-line-expand ,
|
|
or it will be read by the parser in the normal way when processing
|
|
the current input file.
|
|
.I string
|
|
need not have a terminating newline.
|
|
Strings pushed back by multiple calls to
|
|
.I unread-line
|
|
are coalesced and returned as a whole by the next input operation.
|
|
.Pr error-port
|
|
.PP
|
|
Returns a Scheme output port that is bound to the program's
|
|
standard error output.
|
|
This primitive is used by the default Scheme error handler provided
|
|
by
|
|
.I unroff
|
|
and by the
|
|
.I warn
|
|
utility function\**.
|
|
.FS
|
|
The primitive
|
|
.I error-port
|
|
should actually be provided by Elk proper to avoid having to
|
|
reinvent it for each extensible application.
|
|
.FE
|
|
Note that
|
|
.I error-port
|
|
returns an ordinary Scheme port, not a stream.
|
|
.NH
|
|
String Functions
|
|
.PP
|
|
Most of the string handling primitives described in this section
|
|
could as well have been implemented in Scheme based on the standard
|
|
Scheme string primitives.
|
|
They are provided as built-in primitives by
|
|
.I unroff
|
|
mainly as optimizations or because writing them as Scheme
|
|
procedures would have been significantly more cumbersome.
|
|
All the string functions return new strings, that is, they
|
|
do not modify their arguments.
|
|
.Pr concat . args
|
|
.PP
|
|
.I concat
|
|
can be called with any number of Scheme strings, symbols, and
|
|
characters.
|
|
The primitive concatenates its arguments and returns the result
|
|
as a string.
|
|
.Pr spread
|
|
.PP
|
|
This primitive is identical to
|
|
.I concat ,
|
|
except that it delimits its arguments by a space character.
|
|
For example, the event procedure for a macro that just
|
|
returns a line consisting of its arguments could be define like this:
|
|
.Es
|
|
(defmacro 'X
|
|
(lambda (X . words)
|
|
(parse (apply spread words) #\enewline)))
|
|
.Ee
|
|
.Pr repeat-string num string
|
|
.PP
|
|
Returns a string consisting of the string argument
|
|
.I string
|
|
repeated
|
|
.I num
|
|
times.
|
|
.Pr string-prune-left string prefix fail
|
|
.PP
|
|
This primitive checks whether
|
|
.I string
|
|
starts with the given string prefix, and if so, returns the rest of
|
|
.I string
|
|
beginning at the first character position after the initial prefix.
|
|
If the strings do not match,
|
|
.I fail
|
|
is returned (which may an arbitrary object).
|
|
Example:
|
|
.Es
|
|
(string-prune-left "+foo" "+" #f) \(rh "foo"
|
|
(string-prune-left "gulp" "+" #f) \(rh #f
|
|
.Ee
|
|
.Pr string-prune-right string suffix fail
|
|
.PP
|
|
This primitive is identical to
|
|
.I string-prune-left ,
|
|
except that it checks for a suffix rather than a prefix,
|
|
that is, whether
|
|
.I string
|
|
ends with
|
|
.I suffix .
|
|
.Pr string-compose string1 string2
|
|
.PP
|
|
If the argument
|
|
.I string2
|
|
begins with a plus sign,
|
|
.I string-compose
|
|
returns the concatenation of
|
|
.I string1
|
|
and
|
|
.I string2
|
|
with the initial plus sign stripped.
|
|
If
|
|
.I string2
|
|
begins with a minus sign,
|
|
it returns a string consisting of
|
|
.I string1
|
|
with all characters occurring in
|
|
.I string2
|
|
removed.
|
|
Otherwise,
|
|
.I string-compose
|
|
just returns
|
|
.I string2 .
|
|
This primitive is used for the implementation of the option type
|
|
.I dynstring .
|
|
.Pr parse-pair string
|
|
.PP
|
|
If
|
|
.I string
|
|
consists of two parts separated and enclosed by an arbitrary delimiter
|
|
character,
|
|
.I parse-pair
|
|
returns a cons cell holding the two substrings.
|
|
Otherwise, it returns #f.
|
|
Example:
|
|
.Es
|
|
(parse-pair "'foo'bar'") \(rh ("foo" . "bar")
|
|
(parse-pair "hello") \(rh #f
|
|
.Ee
|
|
.Pr parse-triple string
|
|
.PP
|
|
This primitive is identical to
|
|
.I parse-pair ,
|
|
except that it breaks up a three-part string rather than a
|
|
two-part string and returns an improper list whose car, cadr,
|
|
and cddr consist of the three substrings\**.
|
|
.FS
|
|
The primitive
|
|
.I parse-triple
|
|
should probably return a proper list rather than an improper list.
|
|
.FE
|
|
.I parse-pair
|
|
and
|
|
.I parse-triple
|
|
are useful mainly for parsing the arguments to troff requests such
|
|
as ``.if'' and ``.tl''.
|
|
.Pa .substitute substitute string . args
|
|
.PP
|
|
This primitive returns a copy of
|
|
.I string
|
|
in which each sequence of a percent sign, a
|
|
.I "substitution specifier" ,
|
|
and another percent sign is replaced by another string according
|
|
to the specifier.
|
|
Two adjacent percent signs are replaced by a single percent sign.
|
|
The following list describes all substitution specifiers together
|
|
with their respective replacements.
|
|
.IP \f3macros\fP
|
|
The name of the troff macro package whose macros are recognized,
|
|
that is, the argument to the option
|
|
.B \-m
|
|
(or the empty string if none was specified).
|
|
.IP \f3format\fP
|
|
The output format, that is, the argument to the option
|
|
.B \-f
|
|
(or the default output format if the option was omitted).
|
|
.IP \f3directory\fP
|
|
The name of the library directory from which
|
|
.I unroff
|
|
loads its Scheme files.
|
|
.IP \f3progname\fP
|
|
The name of the running program (this is used as a prefix in
|
|
error messages and warning messages).
|
|
.IP \f3filepos\fP
|
|
A space character followed by the target of the current input
|
|
stream, a colon, the number of the last input line read from
|
|
the stream, and another colon.
|
|
If the current input stream is bound to #f, the empty string
|
|
is substituted.
|
|
This specifier is useful for displaying error messages or warning messages.
|
|
.IP \f3tmpname\fP
|
|
A file name that can be used for a temporary file.
|
|
Each use of this specifier creates a new, unique file name.
|
|
.IP \f3version\fP
|
|
The program's major and minor version numbers separated by a period.
|
|
.IP \f3weekday\fP
|
|
The abbreviated weekday name.
|
|
.IP \f3weekday+\fP
|
|
The full weekday name.
|
|
.IP \f3weekdaynum\fP
|
|
The weekday (0\-6, Sunday is 0).
|
|
.IP \f3monthname\fP
|
|
The abbreviated month name.
|
|
.IP \f3monthname+\fP
|
|
The full monthname.
|
|
.IP \f3day\fP
|
|
The day of the month (01\-31).
|
|
.IP \f3month\fP
|
|
The month (01\-12).
|
|
.IP \f3year\fP
|
|
The year.
|
|
.IP \f3date\fP
|
|
The date (in the local environment's representation).
|
|
.IP \f3time\fP
|
|
The time (in the local environment's representation).
|
|
.IP "a positive number \f2n\fP"
|
|
The
|
|
.I n th
|
|
additional argument in the call to the
|
|
.I substitute
|
|
primitive, which must be a string.
|
|
.IP "a \f2string\fP"
|
|
.I string
|
|
is interpreted as the name of an environment variable,
|
|
and the value of this variable is substituted (or the empty
|
|
string if the environment variable is undefined).
|
|
.LP
|
|
Examples:
|
|
.Es
|
|
(substitute "%date% %HOME%") \(rh "04/09/95 /home/kbs/net"
|
|
.El
|
|
(substitute "%progname%:%filepos% %1%" "hello")
|
|
\(rh "unroff: manual.ms:21: hello"
|
|
.El
|
|
(load (substitute "%directory%/scm/%format%/m%macros%.scm"))
|
|
.Ee
|
|
.NH
|
|
Tables
|
|
.PP
|
|
.I unroff
|
|
provides simple hash tables as a new first class data type
|
|
.I table .
|
|
Each table entry associates an arbitrary Scheme object with
|
|
a key (a Scheme string or symbol).
|
|
Tables are useful for various purposes; for example, the Scheme code
|
|
delivered with
|
|
.I unroff
|
|
maintains hash tables to store information about number registers,
|
|
options, fonts, and for other bookkeeping tasks.
|
|
.Pr table? obj
|
|
.PP
|
|
The type predicate for the new type; it returns #t if
|
|
.I obj
|
|
is a member of the type
|
|
.I table ,
|
|
otherwise #f.
|
|
.Pr make-table size
|
|
.PP
|
|
Returns a new table of the specified size.
|
|
.I size
|
|
is a positive integer.
|
|
The smaller the size, the more collisions occur as entries
|
|
are added to the table.
|
|
However, the hash function employed by the table primitives
|
|
ensures that no collisions occur in tables of size
|
|
256^\c
|
|
.I n
|
|
if all keys have a length less than or equal to
|
|
.I n .
|
|
.Pr table-store! table key obj
|
|
.PP
|
|
This primitive stores the Scheme object
|
|
.I obj
|
|
under the given
|
|
.I key
|
|
in the given
|
|
.I table .
|
|
The key argument must be a string or a symbol.
|
|
.Pr table-lookup table key
|
|
.PP
|
|
This primitive checks whether an object is stored in the given
|
|
.I table
|
|
under the specified
|
|
.I key ,
|
|
and if so, returns the object.
|
|
If no object is stored under
|
|
.I key ,
|
|
.I table-lookup
|
|
returns #f.
|
|
.Pr table-remove! table key
|
|
.PP
|
|
Removes the entry selected by
|
|
.I key
|
|
from the specified table.
|
|
.NH
|
|
Miscellaneous Primitives
|
|
.PP
|
|
The first two primitives described in this section are not essential,
|
|
as the same function could be achieved with pipe streams,
|
|
although with greater overhead.
|
|
The remaining primitives perform a number of troff-specific operations
|
|
and are only useful in a few specialized contexts.
|
|
.Pr shell-command command
|
|
.PP
|
|
Runs the specified
|
|
.I command
|
|
(which must be a string) as a shell command by passing it to a call to
|
|
.I system (3).
|
|
The return value is that of
|
|
.I system()
|
|
(an integer).
|
|
.Pr remove-file filename
|
|
.PP
|
|
Removes the specified file;
|
|
.I filename
|
|
must be a string or a symbol.
|
|
.Pr troff-compatible?
|
|
.PP
|
|
This predicate returns #t if troff compatibility mode has been
|
|
enabled (i.\|e. if the option
|
|
.B \-C
|
|
has been given), otherwise #f.
|
|
.Pr set-escape! char
|
|
.PP
|
|
Sets the troff escape character (initially `\e') to the specified
|
|
character argument.
|
|
This primitive is used to implement the ``.ec'' request.
|
|
.Pa .filter-eqn-line filter-eqn-line string
|
|
.PP
|
|
This primitive scans the string argument (which is supposed to
|
|
be passed to the
|
|
.I eqn
|
|
preprocessor afterwards) for occurrences of the ``delim'' directive.
|
|
If a ``delim'' directive is found, the current inline equation
|
|
delimiters maintained by the parser are changed or disabled as specified by
|
|
the directive.
|
|
The primitive returns #f if
|
|
.I string
|
|
is empty or consists just of white space, or if it contains
|
|
a valid ``delim'' or ``define'' directive, otherwise #t.
|
|
The inline equation delimiters are disabled initially.
|
|
.PP
|
|
The primitive is supposed to be used by implementations of
|
|
the request ``.EQ'' and inline equation event handlers to intercept the
|
|
.I eqn
|
|
input.
|
|
In this case, the
|
|
.I eqn
|
|
preprocessor need only be invoked if
|
|
.I filter-eqn-line
|
|
returned #t at least once.
|
|
.Pr skip-group
|
|
.PP
|
|
This primitive reads input lines from the current input stream
|
|
and scans them for the escape sequences `\e{' and `\e}' until
|
|
the nesting level of conditional input is balanced (i.\|e. until
|
|
a matching closing brace for an initial opening brace has been found).
|
|
The primitive is only useful for the implementation of the
|
|
troff requests for conditional input.
|
|
.NH
|
|
File Insertions
|
|
.PP
|
|
The primitive
|
|
.I file-insertions
|
|
is a general-purpose utility for inserting strings into files
|
|
at specified locations in a fast and robust way.
|
|
One application is to resolve forward references of any kind among
|
|
a group of files when all files have been processed.
|
|
In this case, the insertions would be executed by an
|
|
.I exit
|
|
event handler.
|
|
.Pa .file-insertions file-insertions insertions
|
|
.PP
|
|
.I insertions
|
|
is a list specifying the parameters for the file insertions.
|
|
Each element of the list is itself a list consisting
|
|
of a file name (a string),
|
|
a file offset (an integer between zero and the size of the file),
|
|
and a string to be inserted in the given file at the given offset.
|
|
.I file-insertions
|
|
sorts the list to ensure that each file is only processed once
|
|
and that the offsets for each file are in increasing order.
|
|
Then each file is copied to a temporary file
|
|
.Es
|
|
\f2filename\fP.new
|
|
.Ee
|
|
(where
|
|
.I filename
|
|
is the original file name), and the specified insertions are
|
|
carried out as the file is copied.
|
|
When processing of a file is finished, the temporary file is
|
|
renamed to its original name.
|
|
If there exist links to a file, a warning is displayed and the
|
|
insertion is skipped.
|
|
.NH
|
|
Utilities for Back-Ends
|
|
.PP
|
|
Writers of new back-ends (either for new output formats or for new
|
|
troff macro packages) can benefit from a number of Scheme procedures
|
|
and macros that are exported by the file ``scm/troff.scm'' which is
|
|
loaded from the library directory on startup.
|
|
The first two,
|
|
.I eval-if-mode
|
|
and
|
|
.I set-option!
|
|
are exceptions in that they are typically used by the user's
|
|
initialization file ``~/.unroff'' to customize
|
|
.I unroff ,
|
|
rather than by programmers of
|
|
.I unroff .
|
|
.Pr set-option! name value
|
|
.PP
|
|
This procedure assigns
|
|
.I value
|
|
to the option
|
|
.I name .
|
|
The value must be appropriate for the option's type.
|
|
.Pr eval-if-mode mode . forms
|
|
.PP
|
|
This macro is typically used to evaluate a sequence of expressions,
|
|
.I forms ,
|
|
depending on the output format and macro package specified in
|
|
the command line.
|
|
.I mode
|
|
is a list of two symbols, an output format and a macro package
|
|
name; the wildcard `*' can be used for both elements.
|
|
The
|
|
.I forms
|
|
are evaluated if the first symbol matches the value of the option
|
|
.B \-f
|
|
and the second symbol matches the value of the option
|
|
.B \-m ;
|
|
in this case the result of the last sub-expression is returned.
|
|
Otherwise the forms are ignored and #f is returned.
|
|
Example:
|
|
.Es
|
|
(eval-if-mode (* html)
|
|
(set-option! 'mail-address "net@cs.tu-berlin.de"))
|
|
.Ee
|
|
.Ps
|
|
.Pr quit message . args
|
|
.Pr warn message . args
|
|
.Pe
|
|
.PP
|
|
These procedures print
|
|
.I message
|
|
and the optional
|
|
.I args
|
|
on the port returned by
|
|
.I error-port
|
|
using the primitive
|
|
.I format .
|
|
The message is prefixed by the program name, current input file
|
|
name and line number, and, in case of
|
|
.I warn ,
|
|
the word ``warning''.
|
|
A newline is appended.
|
|
.I quit
|
|
causes the program to exit with an exit code of 1, and
|
|
.I warn
|
|
returns the empty string (and can therefore be used as the last
|
|
form in event procedures).
|
|
.Pa .options option name
|
|
.PP
|
|
Returns the value of the specified option.
|
|
.Pr define-option name type initial
|
|
.PP
|
|
Defines a new option with the specified name, type, and initial
|
|
value.
|
|
.I name
|
|
and
|
|
.I type
|
|
are strings or symbols.
|
|
There exist a number of predefined, basic option types as
|
|
described in the
|
|
.Hr -url \*(Md/unroff.1.html "manual page"
|
|
.Hr "manual page"
|
|
.I unroff (1).
|
|
The initial value need not match the option's type; for example,
|
|
the following expression is valid:
|
|
.Es
|
|
(define-option 'author 'string #f)
|
|
.Ee
|
|
.Pr define-option-type name pre-check pre-msg converter post-check post-msg
|
|
.PP
|
|
This procedure defines a new option type named
|
|
.I name
|
|
which can then be used in calls to
|
|
.I define-option .
|
|
If an option of this type is specified in the command line,
|
|
the procedure
|
|
.I pre-check
|
|
is applied to the option's value (a string).
|
|
In this case, if
|
|
.I pre-check
|
|
returns #f,
|
|
.I quit
|
|
is called with an error message including the string
|
|
.I pre-msg ,
|
|
which should describe the expected option value format
|
|
(e.\|g. ``a character'').
|
|
If the check succeeds, the procedure
|
|
.I converter
|
|
is called with the option's current value and with the string as given
|
|
in the command line.
|
|
The job of the converter procedure is to convert the option value
|
|
from a string representation to a Scheme object matching the option's
|
|
actual Scheme type.
|
|
.PP
|
|
Finally, the predicate
|
|
.I post-check
|
|
is applied either to the result of
|
|
.I converter
|
|
or, if the option was set through a call to
|
|
.I set-option! ,
|
|
to this procedure's argument.
|
|
If the predicate returns #f, a error is signaled with an error
|
|
message including
|
|
.I post-msg
|
|
as described in the previous paragraph.
|
|
For example, the predefined option type ``boolean'' is defined as
|
|
follows:
|
|
.Es
|
|
(define-option-type 'boolean
|
|
(lambda (x) (member x '("0" "1"))) "0 or 1"
|
|
(lambda (old new) (string=? new "1"))
|
|
boolean? "a boolean")
|
|
.Ee
|
|
.Ps
|
|
.Pr with-input-from-stream target . forms
|
|
.Pr with-output-to-stream target . forms
|
|
.Pr with-output-appended-to-stream target . forms
|
|
.Pe
|
|
.PP
|
|
These macros open an input stream (first macro) or output stream to the
|
|
specified target and assign it to the current input stream (first
|
|
macro) or current output stream.
|
|
Then the specified
|
|
.I forms
|
|
are evaluated, the stream is reassigned its previous value, and
|
|
the result of the last sub-expression in
|
|
.I forms
|
|
is returned.
|
|
The macros recur on the primitives
|
|
.I open-input-stream ,
|
|
.I open-output-stream ,
|
|
and
|
|
.I append-output-stream ,
|
|
respectively.
|
|
.Pr skip-lines stop
|
|
.PP
|
|
Reads input lines using
|
|
.I read-line-expand
|
|
until either end-of-stream is reached (in this case a warning
|
|
is displayed) or a line matching the string argument
|
|
.I stop
|
|
is encountered.
|