From: Mark Wooding <mdw@distorted.org.uk>
Date: Fri, 23 Aug 2019 12:01:41 +0000 (+0100)
Subject: doc/output.tex: Replace the old output-item comments with big tables.
X-Git-Url: https://git.distorted.org.uk/~mdw/sod/commitdiff_plain/a2a31a5d46c651d36ee2be58fa31588fca4840bd

doc/output.tex: Replace the old output-item comments with big tables.

Now the output structure is actually documented (somewhat) properly.
All I have to do is keep the tables up-to-date somehow.
---

diff --git a/doc/output.tex b/doc/output.tex
index 456554c..b7bfa74 100644
--- a/doc/output.tex
+++ b/doc/output.tex
@@ -172,6 +172,449 @@ until the third.  So the final processing order is
 \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>,          \\*
+  \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}
@@ -243,98 +686,6 @@ until the third.  So the final processing order is
                   \>@<in-names> @<out-names> @<stream>}}
 \end{describe*}
 
-%% output for `h' files
-%%
-%% prologue
-%% guard start
-%% typedefs start
-%% typedefs
-%% typedefs end
-%% includes start
-%% includes
-%% includes end
-%% classes start
-%% early-user start
-%% early-user
-%% early-user end
-%% 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
-%% user start
-%% user
-%% user end
-%% guard end
-%% epilogue
-
-%% output for `c' files
-%%
-%% prologue
-%% includes start
-%% includes
-%% includes end
-%% early-user start
-%% early-user
-%% early-user 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
-%% user start
-%% user
-%% user end
-%% epilogue
-
 %%%----- That's all, folks --------------------------------------------------
 
 %%% Local variables: