From d3dac74ac963e67beb87693ad965238c739b146c Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Tue, 22 Sep 2015 11:27:11 +0100
Subject: [PATCH] doc/output.tex: Start documenting the output machinery.

---
 doc/output.tex | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 107 insertions(+), 2 deletions(-)

diff --git a/doc/output.tex b/doc/output.tex
index 5247dc0..c4d080a 100644
--- a/doc/output.tex
+++ b/doc/output.tex
@@ -25,21 +25,115 @@
 
 \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}
@@ -55,7 +149,10 @@
     {invoke-sequencer-items @<sequencer> \&rest @<arguments>}
 \end{describe}
 
-\begin{describe}{gf}{hook-output @<object> @<reason> @<sequencer>}
+\begin{describe}{gf}{hook-output progn @<object> @<reason> @<sequencer>}
+  \begin{describe}{meth}
+    {hook-output progn (@<object> t) (@<reason> t) @<sequencer>}
+  \end{describe}
 \end{describe}
 
 \begin{describe}{mac}
@@ -64,6 +161,14 @@
       @{ (@<item-name> @<form>^*) @}^*}
 \end{describe}
 
+%%%--------------------------------------------------------------------------
+
+
+
+%%%--------------------------------------------------------------------------
+
+\begin{describe}{var}{*instance-class*}
+\end{describe}
 
 %% output for `h' files
 %%
-- 
2.11.0