+ If @<stream> is a pretty-printing stream, then print a mandatory newline,
+ and call @<func> on the underlying non-pretty-printing stream. If
+ @<stream> is not a pretty-printing stream, then simply call @<func> on
+ @<stream> directly.
+
+ The main purpose for this is to be able to access features of the
+ underlying stream which a pretty-printing stream can't proxy. Most
+ notably, this is used by C fragment output, which takes advantage of an
+ underlying \descref{cls}{position-aware-output-stream} to print @|\#line|
+ directives, so that a C~compiler will blame the original fragment in the
+ Sod module source rather than the generated C code.
+\end{describe}
+
+
+\subsection{Condition utilities}
+
+The following definitions are useful when working with conditions.
+
+\begin{describe}{cls}
+ {simple-control-error (control-error simple-error)
+ \&key :format-control :format-arguments}
+ This is the obvious multiply-inherited subclass of @|control-error| whose
+ print form is determined by a @<format-control> and a @<format-arguments>
+ list.
+\end{describe}
+
+\begin{describe}{fun}
+ {designated-condition
+ \=@<default-type> @<datum> @<arguments> \\
+ \>\&key :allow-pointless-arguments
+ \nlret @<condition>}
+ Creates and returns a condition object of @<default-type>, given a
+ condition designator @<datum> and @<arguments>.
+
+ The Common Lisp specification carefully explains how a `datum' and an
+ argument list together form a `condition designator', and how such a pair
+ are to be converted into a condition object with some default type, but
+ there's no mechanism provided to simply do this task. (Functions like
+ @|error| and @|signal| implicitly, but have possibly-undesirable
+ side-effects, and don't allow control over the default type.)
+
+ \begin{itemize}
+
+ \item If @<datum> is a condition object, then the designated condition is
+ simply @<datum>. In this case, if @<arguments> is not an empty list and
+ @<allow-pointless-arguments> is nil (the default), an error is signalled;
+ otherwise, the @<arguments> are ignored.
+
+ \item If @<datum> is a symbol, then the designated condition is constructed
+ by calling
+ \begin{prog}
+ (apply \#'make-condition @<datum> @<arguments>)
+ \end{prog}
+
+ \item If @<datum> is a string or function (i.e., a `format-control'), then
+ the designated condition is constructed by calling
+ \begin{prog}
+ (make-condition \=@<default-type> \\
+ \>:format-control @<datum> \\
+ \>:format-arguments @<arguments>)
+ \end{prog}
+
+ \item Otherwise the designator is malformed, and an error is signalled.
+ \end{itemize}
+\end{describe}
+
+\begin{describe}{fun}
+ {invoke-associated-restart @<restart> @<condition> \&rest @<arguments>}
+ Invoke the active restart named @<restart>, associated with the given
+ @<condition>, passing a list of @<arguments>.
+
+ The function attempts to find and invoke a restart with the given name. If
+ @<condition> is non-nil, then it searches among restarts associated with
+ that specific condition, and restarts associated with no condition; if
+ @<condition> is nil, then it searches among all restarts.
+
+ If a matching restart is found, it is invoked, passing the @<arguments>
+ list. Otherwise, an error (of class @|control-error|) is signalled.
+\end{describe}
+
+\begin{describe*}
+ {\dhead{cls}{enclosing-condition (condition) \&key :condition}
+ \dhead{gf}{enclosed-condition @<enclosing-condition> @> @<condition>}}
+ An @|enclosing condition| is a condition which contains another condition
+ within it. Objects of type @|enclosing-condition| are used to add
+ additional information to an existing condition, or to alter the type of a
+ condition without losing information.
+
+ When an @|enclosing-condition| is constructed, the @<condition> argument
+ names the existing condition to be enclosed. This enclosed condition can
+ be retrieved by calling @|enclosed-condition|.
+\end{describe*}
+
+\begin{describe}{cls}{information (condition) \&key}
+ A condition of class @|information| conveys information which might be of
+ interest, but does not of itself indicate that anything is wrong.
+
+ Within a compiler, @|information| conditions may be signalled in order to
+ present the user with additional diagnostic information about a recently
+ reported error.
+\end{describe}
+
+\begin{describe}{cls}
+ {simple-information (simple-condition information) \\ \ind
+ \&key :format-control :format-arguments}
+ This is the obvious multiply-inherited subclass of @|information|
+ whose print-representation is determined by a @<format-control> and a
+ @<format-arguments> list.
+\end{describe}
+
+\begin{describe*}
+ {\dhead{fun}{info @<datum> \&rest @<arguments> @> @<flag>}
+ \dhead{rst}{noted}
+ \dhead{fun}{noted \&optional @<condition>}}
+ The @|info| function establishes a restart named @|noted| and signals a
+ condition of default type @|simple-information|, designated by the @<datum>
+ and @<arguments>. The @|info| function returns non-nil if and only if the
+ associated @|noted| restart was invoked.
+
+ The @|noted| restart accepts no arguments.
+
+ The @|noted| function finds and invokes a @|noted| restart: if @<condition>
+ is non-nil, then only the restart associated with that condition (and those
+ not associated with any condition) are considered; otherwise, all
+ conditions are considered.
+\end{describe*}
+
+\begin{describe}{fun}
+ {promiscuous-cerror @<continue-string> @<datum> \&rest @<arguments>}
+ Establish a @|continue| restart and signal an error of default type
+ @|simple-error|, designated by @<datum> and @<arguments>. The restart's
+ report format is determined by @<continue-string> and the @<arguments>.
+
+ Some implementations of @|cerror| associate the @|continue| restart which
+ they establish with the condition they signal. This interferes with
+ special effects -- specifically, enclosing the signalled condition and
+ resignalling it. The @|promiscuous-cerror| function carefully avoids
+ associating its restart with the condition.
+\end{describe}
+
+\begin{describe}{fun}{cerror* @<datum> \&rest @<arguments>}
+ A simplified version of \descref{fun}{promiscuous-cerror} which uses the
+ hardcoded string @|Continue| for the restart. This makes calling the
+ function more similar to other condition-signalling functions, at the
+ expense of some usability in environments which don't continue after
+ continuable errors automatically.
+\end{describe}
+
+
+\subsection{Very miscellaneous utilities}
+
+\begin{describe}{fun}
+ {whitespace-char-p @<character> @> @<generalized-boolean>}
+ Return non-nil if and only if @<character> is a whitespace character.
+
+ A character is whitespace if @|(peek-char t @<stream>)| would skip it.
+\end{describe}
+
+\begin{describe}{fun}
+ {frob-identifier @<string> \&key :swap-case :swap-hyphen
+ @> @<frobbed-string>}
+ Return a `frobbed' version of the identifier @<string>. Two different
+ transformations can be applied.
+
+ \begin{itemize}
+
+ \item If @<swap-case> is non-nil (the default), and the letters in
+ @<string> are either all uppercase or all lowercase, then switch the case
+ of all of the letters.
+
+ \item If @<swap-hyphen> is non-nil (the default), and @<string> contains
+ either hyphens @`--' or underscores @`_', but not both, then replace the
+ hyphens by underscores or \emph{vice-versa}.
+
+ \end{itemize}
+
+ (These are the `obvious' transformations to convert a C identifier into a
+ Lisp symbol.)
+
+ Some examples:
+ \begin{itemize}
+ \item @|(frob-identifier "foo")| $\Longrightarrow$ @|"FOO"|
+ \item @|(frob-identifier "FOO")| $\Longrightarrow$ @|"foo"|
+ \item @|(frob-identifier "FooBar")| $\Longrightarrow$ @|"FooBar"|
+ \item @|(frob-identifier "Foo-Bar")| $\Longrightarrow$ @|"Foo_Bar"|
+ \item @|(frob-identifier "Foo_Bar")| $\Longrightarrow$ @|"Foo-Bar"|
+ \item @|(frob-identifier "foo_bar")| $\Longrightarrow$ @|"FOO-BAR"|
+ \item @|(frob-identifier "foo_bar" :swap-hyphen nil)| $\Longrightarrow$
+ @|"FOO_BAR"|
+ \item @|(frob-identifier "foo_bar" :swap-case nil)| $\Longrightarrow$
+ @|"foo-bar"|
+ \item @|(frob-identifier "foo_bar" :swap-case nil :swap-hyphen nil)|
+ $\Longrightarrow$ @|"foo_bar"|
+ \end{itemize}
+\end{describe}
+
+\begin{describe}{fun}
+ {compose @<functions> @> @<function>}
+ Return the left-to-right composition zero or more @<functions>.
+
+ Let $f_1$, $f_2$, \ldots, $f_n$ be functions, and let $g = @|(compose $f_1$
+ $f_2$ $\cdots$ $f_n$)|$ is their composition. If $g$ is applied to
+ arguments, the effect is as follows: first, $f_1$ is applied to the
+ arguments, yielding some value; $f_2$ is applied to this value, yielding a
+ second value; and so on, until finally the value yielded by $f_n$ is
+ returned as the result of $g$. Note that this is the reverse of the usual
+ mathematician's convention, but the author finds this ordering
+ significantly easier to work with:
+ \[ g = f_n \circ \cdots \circ f_2 \circ f_1 \]
+
+ If any of the input functions return multiple values then \emph{all} of the
+ values are passed on to the next function in the list. (If the last
+ function returns multiple values then all of the values are returned from
+ the composition.
+
+ The result of composing no functions is a function which simply returns all
+ of its arguments as values; essentially, $@|(compose)| \equiv
+ @|\#'values|$.
+\end{describe}
+
+\begin{describe}{mac}{defvar-unbound @<name> @<documentation> @> @<name>}
+ Define a variable called @<name>, with a @<documentation> string.
+
+ The Common Lisp @|defvar| macro accepts both an initial value and a
+ doc-string as optional arguments, in that order, with the result that it's
+ not possible to define a variable and establish a documentation string for
+ it without also giving it an initial value. The @|defvar-unbound| macro,
+ on the other hand, never changes the symbol's variable-value.