X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/1818107e8198734df843841a51bca3713bd37596..00d59354c311fb28730b7c9b117b0d91aac092cc:/doc/output.tex

diff --git a/doc/output.tex b/doc/output.tex
index 29a8b4d..1615119 100644
--- a/doc/output.tex
+++ b/doc/output.tex
@@ -7,7 +7,7 @@
 
 %%%----- 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
@@ -25,87 +25,722 @@
 
 \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> @> @<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}
+
+\begin{describe}{fun}{add-sequencer-constraint @<sequencer> @<constraint>}
+\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>^*) @]                        \\
+      @{ (@<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/}
+  %
+  (:static-instances :start)    & static-instance, :h
+        & \begin{nprog} \banner{Public static instances} \\ \end{nprog}
+                                                                \\*\hlx{v}
+  :static-instances             & static-instance, :h
+        & \begin{nprog}
+            extern $[@"const"]$ struct @<class>{}__ilayout
+              @<inst>{}__instance;                              \\
+            \#define @<inst> (\&@<inst>{}__instance.@<h>.@<c>)
+          \end{nprog}                                           \\*
+  (:static-instances :end)      & static-instance, :h
+        &                                                       \\ \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/}
+  %
+  (:static-instances :start)    & static-instance, :c
+        & \begin{nprog} \banner{Static instance definitions} \\ \end{nprog}
+                                                                \\*\hlx{v}
+  (:static-instances :decls)    & static-instance, :c
+        & \begin{nprog}
+            /* Forward declarations. */                         \\+
+            static $[@"const"]$ struct @<class>{}__ilayout
+              @<inst>{}__instance;                              \\
+            \#define @<inst> (\&@<inst>{}__instance.@<h>.@<c>)
+          \end{nprog}                                           \\*
+  (:static-instances :gap)      & static-instance, :c
+        &                                                       \\
+  (@<inst> :start)              & sod-class, 'static-instance
+        & \begin{nprog}
+            /* Static instance `@<inst>'. */                    \\
+            $[@"static"]$ $[@"const"]$ struct @<inst>{}__ilayout
+              @<inst>{}__instance = \{
+          \end{nprog}                                           \\*\hlx{v}
+  (@<inst> :chain @<chain-head> :start) & ichain, 'static-instance
+        & \quad \{ \{ /* @<n> ichain */                         \\*
+  (@<inst> :vtable @<chain-head>) & vtable-pointer, 'static-instance
+        & \slotlabel{3}{_vt} \&@<class>{}__vtable_@<h>.@<c>,    \\*
+  (@<inst> :slots @<super> :start) & islots, 'static-instance
+        & \quad\quad \{ /* Class @<super> */                    \\*
+  (@<inst> :slots @<super>)     & effective-slot, 'static-instance
+        & \slotlabel{4}{@<slot>} @<value>,                      \\*
+  (@<inst> :slots @<super> :end) & islots, 'static-instance
+        & \quad\quad \},                                        \\*
+  (@<inst> :chain @<chain-head> :end) & ichain, 'static-instance
+        & \quad \} \},                                          \\*
+  (@<inst> :end)                & sod-class, 'static-instance
+        & \begin{nprog} \}; \\ \end{nprog}                      \\ \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}
+
+\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*}
+
+\begin{describe}{var}{*static-instance*}
+\end{describe}
+
+\begin{describe}{gf}{declare-static-instance @<static-instance> @<stream>}
+\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}{gf}
+    {output-static-instance-initializer @<static-instance> @<effective-slot>
+                                        @<stream>}
+\end{describe}
 
 %%%----- That's all, folks --------------------------------------------------