From 5c3d43e78685ac1dfc7d4a8fdf464597b410b7e0 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 3 Aug 2019 16:48:53 +0100
Subject: [PATCH] doc/concepts.tex: Briefly explain translation-time
 metaobjects.

---
 doc/concepts.tex | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 67dc35b..e7a6c15 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -1259,9 +1259,35 @@ the minimal $M_j$.
 \subsection{Translation-time metaobjects}
 \label{sec:concepts.metaclasses.compile-time}
 
-
-
-\fixme{unwritten}
+Within the translator, modules, classes, slots and initializers, messages and
+methods are all represented as instances of classes.  Since the translator is
+written in Common Lisp, these translation-time metaobject classes are all
+CLOS classes.  Extensions can influence the translator's behaviour -- and
+hence the layout and behaviour of instances at runtime -- by subclassing the
+built-in metaobject classes and implementing methods on appropriate generic
+functions.
+
+Metaobject classes are chosen in a fairly standard way.
+\begin{itemize}
+\item All metaobject definitions support a symbol-valued property, usually
+  named @|@<thing>_class| (e.g., @|slot_class|, @|method_class|), which sets
+  the metaobject class explicitly.  (The class for a class metaobject is
+  taken from the @|lisp_class| property, because @|class_class| seems less
+  meaningful.)
+\item Failing that, the metaobject's parents choose a default metaobject
+  class, based on the new metaobject's properties; i.e., slots and messages
+  have their metaobject classes chosen by the defining class metaobject;
+  initializer and initarg classes are chosen by the defining class metaobject
+  and the direct slot metaobject; and method classes are chosen by the
+  defining class metaobject and the message metaobject.
+\item Classes have no parents; instead, the default is simply to use the
+  builtin metaobject class @|sod-class|.
+\item Modules are a special case because the property syntax is rather
+  awkward.  All modules are initially created as instances of the built-in
+  metaclass @|module|.  Once the module has been parsed completely, the
+  module metaobject's classes is changed, using @|change-class|, to the class
+  specified in the module's property set.
+\end{itemize}
 
 %%%--------------------------------------------------------------------------
 \section{Compatibility considerations} \label{sec:concepts.compatibility}
-- 
2.11.0

