%%%----- Licensing notice ---------------------------------------------------
%%%
-%%% This file is part of the Sensble Object Design, an object system for C.
+%%% This file is part of the Sensible Object Design, an object system for C.
%%%
%%% SOD is free software; you can redistribute it and/or modify
%%% it under the terms of the GNU General Public License as published by
\chapter{The output system} \label{ch:output}
+This chapter deals with actually generating output files. It will be of
+interest to programmers introducing new layout object classes, or new kinds
+of output files. An understanding of the material in
+\xref{sec:structures.layout} will prove valuable.
+
%%%--------------------------------------------------------------------------
+\section{Output sequencing} \label{sec:output.sequencer}
+
+C compilers are picky about the order in which things are presented to them
+in their input; but information about the structure of our classes is
+scattered among a variety of different layout objects. It's not the case
+that a layout object only contributes to a single localized portion of the
+output: for example, a @|vtmsgs| layout object is responsible for declaring
+both the appropriate @|struct $C$__vtmsgs_$a$| structure in the header file,
+populated with method entry pointers, but also declaring its member in the
+enclosing @|struct $C$__vt_$i$| structure.
+
+One approach would be to have the various layout objects just know how to
+call each other in the right order so as to have everything come out
+properly. That would make extending the translator, e.g., to add new kinds
+of layout objects, rather difficult. And it doesn't let users insert custom
+C fragments in flexible ways.
+
+Instead, there's a clear separation between which things need to be output,
+and the order in which they're produced.
+
+Ordering is handled by a \emph{sequencer} object. A sequencer doesn't know
+anything particular about output: its job is simply to do things in a
+particular order. It's described here because Sod only uses it for output
+scheduling.
+
+A sequencer maintains a collection of named \emph{items}, each of which has a
+name and a list of functions associated with it. A name can be any Lisp
+object. Names are compared using @|equal|, so lists can be used to construct
+a hierarchical namespace.
+
+The sequencer also maintains a collection of \emph{constraints}, which take
+the form of lists of item names. A constraint of the form @|($N_1$, $N_2$,
+$\ldots$, $N_k$)| requires that the item named $N_1$ must be scheduled before
+the item named $N_2$, and so on, all of which must be scheduled before the
+item named $N_k$. Items with these names do not need to exist or be known to
+the sequencer. An item name may appear in any number of constraints, all of
+which apply.
+
+It might be that a collection of constraints is impossible to satisfy: for
+example, the set
+\begin{center} \codeface
+ (alice bob) \qquad (bob carol) \qquad (carol alice)
+\end{center}
+can't be satisfied, since the first constraint requires that @|alice|
+precedes @|bob|, but the third says that @|alice| must come after @|carol|,
+and the second that @|carol| comes after @|bob|: it's not possible that
+@|alice| comes before @|bob| and after @|bob|. In this case, the sequencer
+fails and signals an error of type @|inconsistent-merge-error|.
+
+It is possible, but tedious, to explicitly order an entire collection of
+items by adding constraints. In the absence of explicit constraints to order
+them, items are ordered according to the order in which constraints naming
+them were first added to the sequencer. Items not named in any constraint
+are not processed at all.
+
+For example, suppose we have the following constraints.
+\begin{center} \codeface
+ (perl java) \qquad
+ (lisp java) \qquad
+ (python icon) \qquad
+ (icon perl)
+\end{center}
+The constraints give us that $@|python| < @|icon| < @|perl| < @|java|$, and
+also $@|lisp| < @|java|$. In this case, @|lisp| precedes @|python| because
+@|lisp| is mentioned in the second constraint while @|python| isn't mentioned
+until the third. So the final processing order is
+\begin{center}
+ @|lisp|, \quad
+ @|python|, \quad
+ @|icon|, \quad
+ @|perl|, \quad
+ @|java|
+\end{center}
+
\begin{describe}{cls}{sequencer-item}
+ An object of class @|sequencer-item| represents a sequencer item.
+ Sequencer items maintain a \emph{name} and a list of \emph{functions}.
+ Names are compared using @|equal|.
+
+ The functions are maintained in \emph{reverse order}, because it's
+ convenient to be able to add new functions using @|push|.
\end{describe}
\begin{describe}{fun}{sequencer-item-p @<object> @> @<generalized-boolean>}
+ Return non-nil if and only if @<object> is a @|sequencer-item|.
\end{describe}
-\begin{describe}{fun}{make-sequencer-item @<name> \&optional @<functions>}
+\begin{describe}{fun}
+ {make-sequencer-item @<name> \&optional @<functions> @> @<item>}
+ Create and return a new sequencer item with the given @<name> and list of
+ @<functions>; the list of functions defaults to nil if omitted.
\end{describe}
\begin{describe*}
{\dhead{fun}{sequencer-item-name @<item> @> @<name>}
\dhead{fun}{sequencer-item-functions @<item> @> @<list>}
\dhead{fun}{setf (sequencer-item-functions @<item>) @<list>}}
+ These functions read or modify the state of a sequencer @<item>, as
+ originally established by @|make-sequencer-item|.
+
+ It is an error to modify an item's list of functions during a call to
+ @|invoke-sequencer-items| on the item's owning sequencer.
\end{describe*}
\begin{describe}{cls}{sequencer () \&key :constraints}
\end{describe}
+\begin{describe*}
+ {\dhead{fun}{sequencer-constraints @<sequencer> @> @<list>}
+ \dhead{fun}{setf (sequencer-constraints @<sequencer>) @<list>}
+ \dhead{fun}{sequencer-table @<sequencer> @> @<hash-table>}}
+\end{describe*}
+
\begin{describe}{fun}{ensure-sequencer-item @<sequencer> @<name> @> @<item>}
\end{describe}
\end{describe}
\begin{describe}{fun}
+ {add-sequencer-item-function @<sequencer> @<name> @<function>}
+\end{describe}
+
+\begin{describe}{fun}
{invoke-sequencer-items @<sequencer> \&rest @<arguments>}
\end{describe}
\begin{describe}{gf}{hook-output @<object> @<reason> @<sequencer>}
+ \begin{describe}{meth}{t,t}
+ {hook-output (@<object> t) (@<reason> t) @<sequencer>}
+ \end{describe}
\end{describe}
\begin{describe}{mac}
- {sequence-output (@<stream-var> @<sequencer>) \\ \ind
- @{ :constraint (@<item-name>^*) @} \\
+ {sequence-output (@<stream-var> @<sequencer>) \\ \ind
+ @[ :constraint (@<item-name>^*) @] \\
@{ (@<item-name> @<form>^*) @}^*}
\end{describe}
+%%%--------------------------------------------------------------------------
+\section{Output structure} \label{output.structure}
+
+The structures of the header and implementation files produced by the
+translator are detailed in tables~\ref{tab:output.structure.header}
+and~\ref{tab:output.structure.impl}, respectively.
+
+The following notes may be helpful.
+\begin{itemize}
+\item The `specializers' shown in the tables identify the method of the
+ @|hook-output| function responsible for producing the corresponding
+ `contents'. Subclasses can extend or override the listed methods (with
+ appropriate care).
+\item A row showing an `item' but no `specializers' indicate that the
+ translator does not prodice output for that item. It may be present for
+ ordering purposes, or as a place for user output.
+\item A row showing `specializers' but (apparently) no `contents' indicates
+ that a blank line is emitted at that point.
+\end{itemize}
+
+\begingroup
+\LTleft=-\leftindent plus 1fil minus 1fil
+\LTright=0pt plus 1fil minus 1fil
+\small
+\def\banner#1{\hbox to\hsize{/*@-@-@-@-@- #1
+ \rlap{@-}\leaders\hbox{@-}\hfil\llap{@-}*/}}
+\def\fmtspecs#1, #2 {@|#1|, @|(eql #2)|}
+\def\slotlabel#1#2{\leavevmode\hbox to30mm{\kern#1em/* #2\hfil= */}}
+
+\clearpage
+\begin{longtable}{>{\codeface}p{41mm}>{\fmtspecs}l>{\codeface}p{65mm}}
+ \caption{Header file output structure}
+ \label{tab:output.structure.header} \\ \hlx{hv}
+ \thd{Sequencer item} & \thd{@|hook-output| specializers}
+ & \thd{Output} \\ \hlx{vhv}
+ \endfirsthead
+ \caption[]{Header file output structure \emph{(cont.)}} \\ \hlx{hv}
+ \thd{Sequencer item} & \thd{@|hook-output| specializers}
+ & \thd{Contents} \\ \hlx{vhv}
+ \endhead
+ \hlx{vh}
+ \endfoot
+ x & sod-class-effective-slot, 'class & x \kill
+ %
+ :prologue & module, :h
+ & \begin{nprog}
+ /\=* @-*@- mode: c; indent-tabs-mode: nil @-*@- \\
+ \>* \\
+ \>* Header file generated by SOD for @<module> \\
+ \>*/ \\
+ \end{nprog} \\ \hlx{v/}
+ (:guard :start) & module, :h
+ & \begin{nprog}
+ \#ifndef @<MODULE>{}_H \\
+ \#define @<MODULE>{}_H \\+
+ \#ifdef __cplusplus \\ \ind
+ extern "C" \{ \-\\
+ \#endif \\
+ \end{nprog} \\ \hlx{v/}
+ %
+ (:typedefs :start) & module, :h
+ & \begin{nprog} \banner{Forward type declarations} \\ \end{nprog}
+ \\*\hlx{v}
+ :typedefs & sod-class, :h
+ & typedef struct @<class>{}__ichain_@<cls> @<class>; \\*\hlx{v}
+ (:typedefs :end) & module, :h \\ \hlx{v/}
+ %
+ (:includes :start) & module, :h
+ & \begin{nprog} \banner{External header files} \\ \end{nprog}
+ \\*\hlx{v}
+ :includes \\*\hlx{v}
+ :early-decls & sod-class, :h
+ & SOD__VARARGS_MACRO_PREAMBLE \\*\hlx{v}
+ (:includes :end) & module, :h \\*\hlx{v}
+ %
+ (:early-user :start) \\*
+ :early \\*
+ (:early-user :end) \\ \hlx{v/}
+ %
+ (:classes :start) \\*\hlx{v}
+ %
+ (@<class> :banner) & sod-class, :h
+ & \begin{nprog} \banner{Class @<class>} \\ \end{nprog} \\*\hlx{v}
+ %
+ (@<class> :islots :start) & sod-class, :h
+ & \begin{nprog}
+ /* Instance slots. */ \\
+ struct @<class>{}__islots \{
+ \end{nprog} \\*\hlx{v}
+ (@<class> :islots :slots) & sod-slot, 'islots
+ & \quad @<type> @<slot-name>; \\*\hlx{v}
+ (@<class> :islots :end) & sod-class, :h
+ & \begin{nprog} \}; \\ \end{nprog} \\ \hlx{v/}
+ %
+ (@<class> :vtmsgs :start) \\*
+ (@<class> :vtmsgs @<super> :start) & vtmsgs, 'vtmsgs
+ & \begin{nprog}
+ /* Messages protocol from class @<super>. */ \\*
+ struct @<class>{}__vtmsgs_@<s> \{
+ \end{nprog} \\*\hlx{v}
+ (@<class> :vtmsgs @<super> :slots) & method-entry, 'vtmsgs
+ & \quad @<type> (*msg)(@<class> *, \dots); \\*\hlx{v}
+ (@<class> :vtmsgs @<super> :end) & vtmsgs, 'vtmsgs
+ & \begin{nprog} \}; \\ \end{nprog} \\*
+ (@<class> :vtmsgs :end) \\ \hlx{v/}
+ %
+ (@<class> :vtables :start) \\*
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :start)
+ \end{nprog} & vtable, :h
+ & \begin{nprog}
+ /* Vtable structure. */ \\*
+ struct @<class>{}__vt_@<h> \{
+ \end{nprog} \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :slots)
+ \end{nprog} & class-pointer, :h
+ & \quad const @<meta> *_class; \\*
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :slots)
+ \end{nprog} & class-pointer, :h
+ & \quad const @<meta> *_cls_@<n>; \\*
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :slots)
+ \end{nprog} & base-offset, :h
+ & \quad size_t _base; \\*
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :slots)
+ \end{nprog} & chain-offset, :h
+ & \quad ptrdiff_t _off_@<h>; \\*
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :slots)
+ \end{nprog} & vmsgs, :h
+ & \quad struct @<class>{}__vtmsgs_@<s> @<s>; \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:vtable \\
+ \>@<chain-head> :end)
+ \end{nprog} & vtable, :h
+ & \begin{nprog}
+ \}; \\+
+ /* Union of equivalent superclass vtables. */ \\
+ union @<class>{}__vtu_@<h> \{ \\ \ind
+ struct @<super>{}__vt_@<h> @<s>; \\
+ \quad $\vdots$ \-\\
+ \}; \\
+ \end{nprog} \\*
+ (@<class> :vtables :end) \\
+ %
+ (@<class> :vtable-externs) & sod-class, :h
+ & /* Vtable structures. */ \\*
+ (@<class> :vtable-externs) & vtable, :h
+ & extern const union @<class>{}__vtu_@<h> @<class>{}__vtable_@<h>;
+ \\*
+ (@<class> :vtable-externs-after) & sod-class, :h \\ \hlx{v/}
+ %
+ (@<class> :methods :start) & sod-class, :h
+ & /* Direct methods. */ \\*
+ (@<class> :methods :defs) & sod-method, :h
+ & \begin{nprog}
+ struct @<class>{}__@<role>{}_suppliedp_@<s>{}__@<msg> \{ \\ \ind
+ unsigned @<arg>: 1; \\
+ \quad $\vdots$ \-\\
+ \}; \\
+ \end{nprog} \\*\hlx{v}
+ (@<class> :methods) & sod-method, :h
+ & struct @<class>{}__@<role>{}_method_@<s>{}__@<msg>(\dots);
+ \\*\hlx{v}
+ (@<class> :methods :end) & sod-class, :h \\ \hlx{v/}
+ %
+ (@<class> :ichains :start) \\*
+ \begin{nprog}
+ (@<class> \=:ichains \\
+ \>@<chain-head> :start)
+ \end{nprog} & ichain, :h
+ & \begin{nprog}
+ /* Instance chain structure. */ \\
+ struct @<class>{}__ichain_@<h> \{
+ \end{nprog} \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:ichains \\
+ \>@<chain-head> :slots)
+ \end{nprog} & vtable-pointer, :h
+ & \quad const struct @<class>{}__vt_@<h> *_vt; \\*
+ \begin{nprog}
+ (@<class> \=:ichains \\
+ \>@<chain-head> :slots)
+ \end{nprog} & islots, :h
+ & \quad struct @<class>{}__islots @<c>; \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:ichains \\
+ \>@<chain-head> :end)
+ \end{nprog} & vtable, :h
+ & \begin{nprog}
+ \}; \\+
+ /* Union of equivalent superclass chains. */ \\
+ union @<class>{}__ichainu_@<h> \{ \\ \ind
+ struct @<super>{}__ichain_@<h> @<s>; \\
+ \quad $\vdots$ \-\\
+ \}; \\
+ \end{nprog} \\*
+ (@<class> :ichains :end) \\ \hlx{v/}
+ %
+ (@<class> :ilayout :start) & ilayout, :h
+ & \begin{nprog}
+ /* Instance layout. */ \\
+ struct @<class>{}__ilayout \{
+ \end{nprog} \\*\hlx{v}
+ (@<class> :ilayout :slots) & ichain, 'ilayout
+ & \quad union @<class>{}__ichainu_@<h>; \\*\hlx{v}
+ (@<class> :ilayout :end) & ilayout, :h
+ & \begin{nprog} \}; \\ \end{nprog} \\ \hlx{v/}
+ %
+ (@<class> :conversions) & sod-class, :h
+ & \begin{nprog}
+ /* Conversion macros. */ \\
+ \#define @<CLASS>{}__CONV_@<S>(_obj) \dots \\
+ \quad $\vdots$ \\
+ \end{nprog} \\ \hlx{v/}
+ %
+ (@<class> :message-macros) & sod-class, :h
+ & \begin{nprog}
+ /* Message invocation macros. */ \\
+ \#define @<class>{}_@<msg>(me, \dots) \dots \\
+ \quad $\vdots$ \\
+ \end{nprog} \\ \hlx{v/}
+ %
+ (@<class> :object) & sod-class, :h
+ & \begin{nprog}
+ /* The class object. */ \\
+ extern const struct @<meta>{}__ilayout @<class>{}__classobj; \\
+ \#define @<class>{}__class (\&\dots) \\
+ \#define @<class>{}__cls_@<n> (\&\dots) \\
+ \quad $\vdots$ \\
+ \end{nprog} \\*\hlx{v}
+ %
+ (:classes :end) \\ \hlx{v/}
+ %
+ (:user :start) \\*
+ :user \\*
+ (:user :end) \\ \hlx{v/}
+ %
+ (:guard :end) & module, :h
+ & \begin{nprog}
+ \banner{That's all, folks} \\+
+ \#ifdef __cplusplus \\ \ind
+ \} \-\\
+ \#endif \\+
+ \#endif
+ \end{nprog} \\*\hlx{v}
+ %
+ :epilogue \\
+\end{longtable}
+
+\clearpage
+\begin{longtable}{>{\codeface}p{41mm}>{\fmtspecs}l>{\codeface}p{65mm}}
+ \caption{Implementation file output structure}
+ \label{tab:output.structure.impl} \\ \hlx{hv}
+ \thd{Sequencer item} & \thd{@|hook-output| specializers}
+ & \thd{Contents} \\ \hlx{vhv}
+ \endfirsthead
+ \caption[]{Implementation file output structure \emph{(cont.)}}
+ \\ \hlx{hv}
+ \thd{Sequencer item} & \thd{@|hook-output| specializers}
+ & \thd{Contents} \\ \hlx{vhv}
+ \endhead
+ \hlx{vh}
+ \endfoot
+ %
+ :prologue & module, :c
+ & \begin{nprog}
+ /\=* @-*@- mode: c; indent-tabs-mode: nil @-*@- \\
+ \>* \\
+ \>* Implementation file generated by SOD for @<module> \\
+ \>*/ \\
+ \end{nprog} \\ \hlx{v/}
+ %
+ (:includes :start) & module, :c
+ & \begin{nprog}
+ \banner{External header files} \\
+ \end{nprog} \\*\hlx{v}
+ :includes \\*\hlx{v}
+ (:includes :end) & module, :c \\*\hlx{v}
+ %
+ (:early-user :start) \\*
+ :early \\*
+ (:early-user :end) \\ \hlx{v/}
+ %
+ (:classes :start) \\*\hlx{v}
+ %
+ (@<class> :banner) & sod-class, :c
+ & \begin{nprog} \banner{Class @<class>} \\ \end{nprog} \\*\hlx{v}
+ %
+ (@<class> :direct-methods :start) \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:direct-method \\
+ \>@<method> :banner)
+ \end{nprog} & sod-method, :c
+ & /* Direct @<role> method on `@<s>.@<msg>' defined by @<class>. */
+ \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:direct-method \\
+ \>@<method> :start)
+ \end{nprog} & delegating-direct-method, :c
+ & \#define CALL_NEXT_METHOD (next_method(\dots)) \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:direct-method \\
+ \>@<method> :body)
+ \end{nprog} & sod-method, :c
+ & \begin{nprog}
+ @<type> @<class>{}__@<role>{}_method_@<s>{}__@<msg>(\dots) \\
+ \{ \\ \ind
+ $\vdots$ \-\\
+ \}
+ \end{nprog} \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:direct-method \\
+ \>@<method> :end)
+ \end{nprog} & delegating-direct-method, :c
+ & \#undef CALL_NEXT_METHOD \\*
+ \begin{nprog}
+ (@<class> \=:direct-method \\
+ \>@<method> :end)
+ \end{nprog} & sod-method, :c \\*\hlx{v}
+ (@<class> :direct-methods :end) \\ \hlx{v/}
+ %
+ (@<class> :effective-methods) & basic-effective-method, :c
+ & \begin{nprog}
+ /\=* Keyword argument structure for `@<s>.@<msg>' defined \\
+ \>* on class @<class>. \\
+ \>*/ \\
+ struct @<class>{}__keywords_@<s>{}__@<msg> \{ \\ \ind
+ unsigned @<arg>{}__suppliedp: 1; \\
+ \quad $\vdots$ \\
+ @<type> @<arg>; \\
+ \quad $\vdots$ \-\\
+ \}; \\+
+ @<effective-method-functions> \\
+ \end{nprog} \\ \hlx{v/}
+ %
+ (@<class> :vtables :start) \\*\hlx{v}
+ (@<class> :vtable @<chain-head> :start) & vtable, :c
+ & \begin{nprog}
+ /* Vtable for @<chain-head> chain. */ \\
+ const union @<class>{}__vtu_@<h> @<class>{}__vtable_@<h> = \{
+ \end{nprog} \\*\hlx{v}
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:class-pointer @<meta>)
+ \end{nprog} & class-pointer, :c
+ & \slotlabel{1}{_class} \&@<cls>{}__classobj.@<n>.@<n>, \\*
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:class-pointer @<meta>)
+ \end{nprog} & class-pointer, :c
+ & \slotlabel{1}{_cls_@<n>} \&@<cls>{}__classobj.@<n>.@<n>, \\*
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:base-offset)
+ \end{nprog} & base-offset, :c
+ & \slotlabel{1}{_base} offsetof(\dots), \\*
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:chain-offset @<target-chain>)
+ \end{nprog} & chain-offset, :c
+ & \slotlabel{1}{_off_@<i>} SOD_OFFSETDIFF(\dots), \\*
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:vtmsgs @<super> :start)
+ \end{nprog} & vtmsgs, :c
+ & \quad \{ /* Method entries for @<super> messags. */ \\*
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:vtmsgs @<super> :slots)
+ \end{nprog} & method-entry, :c
+ & \slotlabel{2}{@<mentry>} @<mentry-func>, \\
+ \begin{nprog}
+ (@<class> \=:vtable @<chain-head> \\
+ \>:vtmsgs @<super> :end)
+ \end{nprog} & vtmsgs, :c
+ & \quad \}, \\*
+ (@<class> :vtable @<chain-head> :end) & vtable, :c
+ & \}; \\*\hlx{v}
+ (@<class> :vtables :end) \\ \hlx{v/}
+ %
+ (@<class> :object :prepare) & sod-class-effective-slot, 'class
+ & @<definitions> \\*\hlx{v}
+ %
+ (@<class> :object :start) & sod-class, :c
+ & \begin{nprog}
+ /* The class object. */ \\
+ const struct @<meta>{}__ilayout @<class>{}__classobj = \{
+ \end{nprog} \\*\hlx{v}
+ %
+ \begin{nprog}
+ (@<class> \=:object \\
+ \>@<meta-head> :ichain :start)
+ \end{nprog} & ichain, 'class
+ & \quad \{ \{ /* @<n> ichain */ \\*
+ \begin{nprog}
+ (@<class> \=:object \\
+ \>@<meta-head> :ichain :start)
+ \end{nprog} & vtable-pointer, 'class
+ & \slotlabel{3}{_vt} \&@<meta>{}__vtable_@<n>.@<m>, \\*
+ \begin{nprog}
+ (@<class> \=:object \\
+ \>@<meta> :slots :start)
+ \end{nprog} & islots, 'class
+ & \quad\quad\quad \{ /* Class @<meta> */ \\*
+ \begin{nprog}
+ (@<class> \=:object \\
+ \>@<meta> :slots)
+ \end{nprog} & effective-slot, 'class
+ & \slotlabel{4}{@<slot>} @<value> \\*
+ \begin{nprog}
+ (@<class> \=:object \\
+ \>@<meta> :slots :end)
+ \end{nprog} & islots, 'class
+ & \quad\quad\quad \} \\*
+ \begin{nprog}
+ (@<class> \=:object \\
+ \>@<meta-head> :ichain :end)
+ \end{nprog} & ichain, 'class
+ & \quad \} \}, \\*
+ (@<class> :object :end) & sod-class, :c
+ & \}; \\*\hlx{v}
+ %
+ (:classes :end) \\ \hlx{v/}
+ %
+ (:user :start) \\*
+ :user \\*
+ (:user :end) \\ \hlx{v/}
+ %
+ :epilogue & module, :c
+ & \banner{That's all, folks} \\
+\end{longtable}
+\endgroup
+
+%%%--------------------------------------------------------------------------
+\section{Module output} \label{output.module}
+
+\subsection{Producing output}
+
+\begin{describe}{gf}
+ {module-output-file @<module> @<output-type> @<output-dir>
+ @> @<pathname>}
+ \begin{describe*}
+ {\dhead{meth}{module,symbol}
+ {module-output-file \=(@<module> module) \\
+ \>(@<output-type> symbol) \\
+ \>@<output-dir>
+ \nlret @<pathname>}
+ \dhead{meth}{module,pathname}
+ {module-output-file \=(@<module> module) \\
+ \>(@<output-type> pathname) \\
+ \>@<output-dir>
+ \nlret @<pathname>}}
+ \end{describe*}
+\end{describe}
+
+\begin{describe}{gf}{write-dependency-file @<module> @<reason> @<output-dir>}
+\end{describe}
+
+\begin{describe}{fun}{output-module @<module> @<reason> @<stream>}
+\end{describe}
+
+
+\subsection{Managing output types} \label{output.module.manage}
+
+\begin{describe}{fun}{declare-output-type @<reason> @<pathname>}
+\end{describe}
+
+\begin{describe}{fun}{output-type-pathname @<reason> @> @<pathname>}
+\end{describe}
+
+
+\subsection{Utilities} \label{output.module.utilities}
+
+\begin{describe}{fun}{banner @<title> @<output> \&key :blank-line-p}
+\end{describe}
+
+\begin{describe}{fun}{guard-name @<filename> @> @<string>}
+\end{describe}
-%% output for `h' files
-%%
-%% prologue
-%% guard start
-%% typedefs start
-%% typedefs
-%% typedefs end
-%% includes start
-%% includes
-%% includes end
-%% classes start
-%% CLASS banner
-%% CLASS islots start
-%% CLASS islots slots
-%% CLASS islots end
-%% CLASS vtmsgs start
-%% CLASS vtmsgs CLASS start
-%% CLASS vtmsgs CLASS slots
-%% CLASS vtmsgs CLASS end
-%% CLASS vtmsgs end
-%% CLASS vtables start
-%% CLASS vtables CHAIN-HEAD start
-%% CLASS vtables CHAIN-HEAD slots
-%% CLASS vtables CHAIN-HEAD end
-%% CLASS vtables end
-%% CLASS vtable-externs
-%% CLASS vtable-externs-after
-%% CLASS methods start
-%% CLASS methods
-%% CLASS methods end
-%% CLASS ichains start
-%% CLASS ichains CHAIN-HEAD start
-%% CLASS ichains CHAIN-HEAD slots
-%% CLASS ichains CHAIN-HEAD end
-%% CLASS ichains end
-%% CLASS ilayout start
-%% CLASS ilayout slots
-%% CLASS ilayout end
-%% CLASS conversions
-%% CLASS object
-%% classes end
-%% guard end
-%% epilogue
-
-%% output for `c' files
-%%
-%% prologue
-%% includes start
-%% includes
-%% includes end
-%% classes start
-%% CLASS banner
-%% CLASS direct-methods start
-%% CLASS direct-methods METHOD start
-%% CLASS direct-methods METHOD body
-%% CLASS direct-methods METHOD end
-%% CLASS direct-methods end
-%% CLASS effective-methods
-%% CLASS vtables start
-%% CLASS vtables CHAIN-HEAD start
-%% CLASS vtables CHAIN-HEAD class-pointer METACLASS
-%% CLASS vtables CHAIN-HEAD base-offset
-%% CLASS vtables CHAIN-HEAD chain-offset TARGET-HEAD
-%% CLASS vtables CHAIN-HEAD vtmsgs CLASS start
-%% CLASS vtables CHAIN-HEAD vtmsgs CLASS slots
-%% CLASS vtables CHAIN-HEAD vtmsgs CLASS end
-%% CLASS vtables CHAIN-HEAD end
-%% CLASS vtables end
-%% CLASS object prepare
-%% CLASS object start
-%% CLASS object CHAIN-HEAD ichain start
-%% CLASS object SUPER slots start
-%% CLASS object SUPER slots
-%% CLASS object SUPER vtable
-%% CLASS object SUPER slots end
-%% CLASS object CHAIN-HEAD ichain end
-%% CLASS object end
-%% classes end
-%% epilogue
+\begin{describe}{fun}
+ {one-off-output @<token> @<sequencer> @<item-name> @<function>}
+\end{describe}
+
+%%%--------------------------------------------------------------------------
+\section{Class output} \label{output.class}
+
+\begin{describe}{var}{*instance-class*}
+\end{describe}
+
+\begin{describe}{gf}{emit-class-typedef @<class> @<stream>}
+\end{describe}
+
+\begin{describe}{gf}{emit-class-object-decl @<class> @<stream>}
+\end{describe}
+
+\begin{describe}{gf}{emit-class-conversion-macro @<class> @<super> @<stream>}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{gf}{emit-message-macro @<class> @<entry> @<stream>}
+ \dhead{gf}{emit-message-macro-defn
+ \=@<class> @<entry> @<varargsp> @<me> \\
+ \>@<in-names> @<out-names> @<stream>}}
+\end{describe*}
%%%----- That's all, folks --------------------------------------------------