From 58f9b4000fb24a363ba8843ce999e8b9a27c4052 Mon Sep 17 00:00:00 2001 Message-Id: <58f9b4000fb24a363ba8843ce999e8b9a27c4052.1717859746.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sat, 2 Jan 2016 15:33:19 +0000 Subject: [PATCH] doc/sod.sty, doc/*.tex: New command to reference `describe' environments. Organization: Straylight/Edgeware From: Mark Wooding --- doc/clang.tex | 24 ++++++++++++------------ doc/concepts.tex | 18 +++++++++--------- doc/sod.sty | 9 +++++++++ 3 files changed, 30 insertions(+), 21 deletions(-) diff --git a/doc/clang.tex b/doc/clang.tex index 99b6eb8..b38dc09 100644 --- a/doc/clang.tex +++ b/doc/clang.tex @@ -65,11 +65,12 @@ specified to return interned objects: programs may rely on receiving the same (@|eq|) type object for similar (possibly merely @|equal|) arguments. Where not specified, clients may still not rely on receiving fresh objects. -A convenient S-expression notation is provided by the @|c-type| macro. Use -of this macro is merely an abbreviation for corresponding use of the various -constructor functions, and therefore interns type objects in the same manner. -The syntax accepted by the macro can be extended in order to support new -classes: see @|defctype|, @|c-type-alias| and @|define-c-type-syntax|. +A convenient S-expression notation is provided by the +\descref{c-type}[macro]{mac}. Use of this macro is merely an abbreviation +for corresponding use of the various constructor functions, and therefore +interns type objects in the same manner. The syntax accepted by the macro +can be extended in order to support new classes: see \descref{defctype}{mac}, +\descref{c-type-alias}{mac} and \descref{define-c-type-syntax}{mac}. The descriptions of each of the various classes include descriptions of the initargs which may be passed to @|make-instance| when constructing a new @@ -80,10 +81,10 @@ syntax are strongly recommended over direct use of @|make-instance|. There are two protocols for printing C types. Unfortunately they have similar names. \begin{itemize} -\item The @|print-c-type| function prints a C type value using the - S-expression notation. It is mainly useful for diagnostic purposes. -\item The @|pprint-c-type| function prints a C type as a C-syntax - declaration. +\item The \descref{print-c-type}[function]{gf} prints a C type value using + the S-expression notation. It is mainly useful for diagnostic purposes. +\item The \descref{pprint-c-type}[function]{gf} prints a C type as a + C-syntax declaration. \end{itemize} Neither generic function defines a default primary method; subclasses of @|c-type| must define their own methods in order to print correctly. @@ -247,15 +248,14 @@ argument lists for methods. This is done by @|c-type-equal-p|. directly attached. If the @ function intends to provide its own additional declarator operators, it should check the @ in order to determine whether parentheses are necessary. See also the - @|maybe-in-parens| macro (page~\pageref{mac:maybe-in-parens}). + \descref{maybe-in-parens}[macro]{mac}. The @ argument indicates whether a space needs to be printed in order to separate the declarator from the declaration specifiers. A kernel which contains an identifier should insert a space before the identifier when @ is non-nil. An `empty' kernel, as found in an abstract declarator (one that specifies no name), looks more pleasing without a - trailing space. See also the @|c-type-space| function - (page~\pageref{fun:c-type-space}). + trailing space. See also the \descref{c-type-space}[function]{fun}. Every concrete subclass of @|c-type| is expected to provide a primary method on this function. There is no default primary method. diff --git a/doc/concepts.tex b/doc/concepts.tex index b8637e8..51cca98 100644 --- a/doc/concepts.tex +++ b/doc/concepts.tex @@ -349,9 +349,9 @@ interim approach is to specify slot initializers where appropriate and send class-specific messages for more complicated parametrized initialization. Automatic-duration instances can be conveniently constructed and initialized -using the @|SOD_DECL| macro (page~\pageref{mac:SOD-DECL}). No special -support is currently provided for dynamically allocated instances. A simple -function using @|malloc| might work as follows. +using the \descref{SOD_DECL}[macro]{mac}. No special support is currently +provided for dynamically allocated instances. A simple function using +@|malloc| might work as follows. \begin{prog} void *new_instance(const SodClass *c) \\ \{ \\ \ind @@ -366,8 +366,8 @@ function using @|malloc| might work as follows. There is currently no provided assistance for finalization or deallocation. It is the programmer's responsibility to decide and implement an appropriate protocol. Note that to free an instance allocated from the heap, one must -correctly find its base address: the @|SOD_INSTBASE| macro -(page~\pageref{mac:SOD-INSTBASE}) will do this for you. +correctly find its base address: the \descref{SOD_INSTBASE}[macro]{mac} will +do this for you. The following simple mixin class is suggested. \begin{prog} @@ -406,13 +406,13 @@ There are three main cases to distinguish. a lookup at runtime to find the appropriate offset by which to adjust the pointer. The conversion can be performed using the appropriate generated upcast macro (see below); the general case is handled by the macro - @|SOD_XCHAIN| (page~\pageref{mac:SOD-XCHAIN}). + \descref{SOD_XCHAIN}{mac}. \item If $B$ is a subclass of~$C$ then the conversion is an \emph{upcast}; otherwise the conversion is a~\emph{cross-cast}. In either case, the conversion can fail: the object in question might not be an instance of~$B$ - at all. The macro @|SOD_CONVERT| (page~\pageref{mac:SOD-CONVERT}) and the - function @|sod_convert| (page~\pageref{fun:sod-convert}) perform general - conversions. They return a null pointer if the conversion fails. + at all. The macro \descref{SOD_CONVERT}{mac} and the function + \descref{sod_convert}{fun} perform general conversions. They return a null + pointer if the conversion fails. \end{itemize} The Sod translator generates macros for performing both in-chain and cross-chain upcasts. For each class~$C$, and each proper superclass~$B$ diff --git a/doc/sod.sty b/doc/sod.sty index 9fffa17..28b6ccc 100644 --- a/doc/sod.sty +++ b/doc/sod.sty @@ -223,5 +223,14 @@ \def\desc@#1#2#3{\desc@begin{\dhead@{#1}{#2}{#3}}} \let\enddescribe\desc@end +\def\descref#1{\@ifnextchar[{\descref@i{#1}}{\descref@ii{#1}{}}} +\def\descref@i#1[#2]{\descref@ii{#1}{ #2}} +\def\descref@ii#1#2#3{% + \code{#1}#2 (page~% + {\let\protect\@empty% + \def\@uscore{-\@gobble}\edef\@tempa{\noexpand\pageref{#3:#1}}\@tempa}% + )% +} + %%%----- That's all, folks -------------------------------------------------- \endinput -- [mdw]