src/: Write dependency-tracking Makefile fragments.

[sod] / doc / syntax.tex

diff --git a/doc/syntax.tex b/doc/syntax.tex
index 5e17ff3..75aa36e 100644 (file)
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -63,8 +63,8 @@ could be a token.
 \end{grammar}
 
 The precise definition of @<alpha-char> is left to the function
 \end{grammar}
 
 The precise definition of @<alpha-char> is left to the function

-\textsf{alpha-char-p} in the hosting Lisp system.  For portability,
-programmers are encouraged to limit themselves to the standard ASCII letters.
+@|alpha-char-p| in the hosting Lisp system.  For portability, programmers are
+encouraged to limit themselves to the standard ASCII letters.

 
 There are no reserved words at the lexical level, but the higher-level syntax
 recognizes certain identifiers as \emph{keywords} in some contexts.  There is
 
 There are no reserved words at the lexical level, but the higher-level syntax
 recognizes certain identifiers as \emph{keywords} in some contexts.  There is


@@ -190,9 +190,9 @@ during translation.  They are read using a simple scanner which nonetheless
 understands C comments and string and character literals.
 
 A C fragment is terminated by one of a small number of delimiter characters
 understands C comments and string and character literals.
 
 A C fragment is terminated by one of a small number of delimiter characters

-determined by the immediately surrounding context -- usually a closing brace
-or bracket.  The first such delimiter character which is not enclosed in
-brackets, braces or parenthesis ends the fragment.
+determined by the immediately surrounding context -- usually some kind of
+bracket.  The first such delimiter character which is not enclosed in
+brackets, braces or parentheses ends the fragment.

 
 %%%--------------------------------------------------------------------------
 \section{C types} \label{sec:syntax.type}
 
 %%%--------------------------------------------------------------------------
 \section{C types} \label{sec:syntax.type}


@@ -431,8 +431,8 @@ operators.
 Finally, an S-expression preceded by @|?| causes the expression to be read in
 the current package (which is always @|sod-user| at the start of a module)
 and immediately evaluated (using @|eval|); the resulting value is converted
 Finally, an S-expression preceded by @|?| causes the expression to be read in
 the current package (which is always @|sod-user| at the start of a module)
 and immediately evaluated (using @|eval|); the resulting value is converted

-into a property value using the \descref{decode-property}[generic
-function]{gf}.
+into a property value using the \descref{gf}{decode-property}[generic
+function].

 
 
 \subsection{Property output types and coercions}
 
 
 \subsection{Property output types and coercions}


@@ -440,8 +440,8 @@ function]{gf}.
 
 When a property value is inspected by the Sod translator, or an extension, it
 is \emph{coerced} so as to conform to a requested output type.  This coercion
 
 When a property value is inspected by the Sod translator, or an extension, it
 is \emph{coerced} so as to conform to a requested output type.  This coercion

-process is performed by the \descref{coerce-property-value}[generic
-function]{gf}, and additional output types and coercions can be defined by
+process is performed by the \descref{gf}{coerce-property-value}[generic
+function], and additional output types and coercions can be defined by

 extensions.  The built-in output types coercions, from the value types listed
 above, are as follows.
 
 extensions.  The built-in output types coercions, from the value types listed
 above, are as follows.
 


@@ -512,7 +512,8 @@ above, are as follows.
 \begin{grammar}
 <module> ::= @<definition>^*
 
 \begin{grammar}
 <module> ::= @<definition>^*
 

-<definition> ::= <import-definition>
+<definition> ::= <property-definition> \fixme{undefined}
+\alt <import-definition>

 \alt <load-definition>
 \alt <lisp-definition>
 \alt <code-definition>
 \alt <load-definition>
 \alt <lisp-definition>
 \alt <code-definition>


@@ -549,9 +550,9 @@ A search is made for a module source file as follows.
 \begin{itemize}
 \item The module name @<string> is converted into a filename by appending
   @`.sod', if it has no extension already.\footnote{%
 \begin{itemize}
 \item The module name @<string> is converted into a filename by appending
   @`.sod', if it has no extension already.\footnote{%

-    Technically, what happens is \textsf{(merge-pathnames name (make-pathname
-    :type "SOD" :case :common))}, so exactly what this means varies
-    according to the host system.} %
+    Technically, what happens is @|(merge-pathnames name (make-pathname :type
+    "SOD" :case :common))|, so exactly what this means varies according to
+    the host system.} %

 \item The file is looked for relative to the directory containing the
   importing module.
 \item If that fails, then the file is looked for in each directory on the
 \item The file is looked for relative to the directory containing the
   importing module.
 \item If that fails, then the file is looked for in each directory on the


@@ -561,7 +562,7 @@ A search is made for a module source file as follows.
 \end{itemize}
 At this point, if the file has previously been imported, nothing further
 happens.\footnote{%
 \end{itemize}
 At this point, if the file has previously been imported, nothing further
 happens.\footnote{%

-  This check is done using \textsf{truename}, so it should see through simple
+  This check is done using @|truename|, so it should see through simple

   tricks like symbolic links.  However, it may be confused by fancy things
   like bind mounts and so on.} %
 
   tricks like symbolic links.  However, it may be confused by fancy things
   like bind mounts and so on.} %
 


@@ -578,23 +579,22 @@ A search is made for a Lisp source file as follows.
 \begin{itemize}
 \item The name @<string> is converted into a filename by appending @`.lisp',
   if it has no extension already.\footnote{%
 \begin{itemize}
 \item The name @<string> is converted into a filename by appending @`.lisp',
   if it has no extension already.\footnote{%

-    Technically, what happens is \textsf{(merge-pathnames name (make-pathname
-    :type "LISP" :case :common))}, so exactly what this means varies
-    according to the host system.} %
+    Technically, what happens is @|(merge-pathnames name (make-pathname :type
+    "LISP" :case :common))|, so exactly what this means varies according to
+    the host system.} %

 \item A search is then made in the same manner as for module imports
   (\xref{sec:syntax-module}).
 \end{itemize}
 \item A search is then made in the same manner as for module imports
   (\xref{sec:syntax-module}).
 \end{itemize}

-If the file is found, it is loaded using the host Lisp's \textsf{load}
-function.
+If the file is found, it is loaded using the host Lisp's @|load| function.

 
 Note that Sod doesn't attempt to compile Lisp files, or even to look for
 existing compiled files.  The right way to package a substantial extension to
 the Sod translator is to provide the extension as a standard ASDF system (or
 similar) and leave a dropping @|foo-extension.lisp| in the module path saying
 something like
 
 Note that Sod doesn't attempt to compile Lisp files, or even to look for
 existing compiled files.  The right way to package a substantial extension to
 the Sod translator is to provide the extension as a standard ASDF system (or
 similar) and leave a dropping @|foo-extension.lisp| in the module path saying
 something like

-\begin{quote}
-  \textsf{(asdf:load-system :foo-extension)}
-\end{quote}
+\begin{prog}
+  (asdf:load-system :foo-extension)
+\end{prog}

 which will arrange for the extension to be compiled if necessary.
 
 (This approach means that the language doesn't need to depend on any
 which will arrange for the extension to be compiled if necessary.
 
 (This approach means that the language doesn't need to depend on any