From ba375a80263cbbc155f66c6046e485d56935e5c6 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 27 Jul 2019 01:10:55 +0100
Subject: [PATCH] doc/*.tex: Prefer @|...| over @"..." for general
 typeset-as-code.

The latter is strictly for literal tokens, rather than general code.
---
 doc/syntax.tex   | 78 ++++++++++++++++++++++++++++----------------------------
 doc/tutorial.tex | 40 ++++++++++++++---------------
 2 files changed, 59 insertions(+), 59 deletions(-)

diff --git a/doc/syntax.tex b/doc/syntax.tex
index 73a353a..6dd5cf7 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -213,9 +213,9 @@ of definitions.
 \fixme{describe syntax; expand}
 Properties:
 \begin{description}
-\item[@"module_class"] A symbol naming the Lisp class to use to
+\item[@|module_class|] A symbol naming the Lisp class to use to
   represent the module.
-\item[@"guard"] An identifier to use as the guard symbol used to prevent
+\item[@|guard|] An identifier to use as the guard symbol used to prevent
   multiple inclusion in the header file.
 \end{description}
 
@@ -274,7 +274,7 @@ 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
+similar) and leave a dropping @|foo-extension.lisp| in the module path saying
 something like
 \begin{quote}
   \textsf{(asdf:load-system :foo-extension)}
@@ -331,7 +331,7 @@ declarations instead.
 The @<c-fragment> will be output unchanged to one of the output files.
 
 The first @<identifier> is the symbolic name of an output file.  Predefined
-output file names are @"c" and @"h", which are the implementation code and
+output file names are @|c| and @|h|, which are the implementation code and
 header file respectively; other output files can be defined by extensions.
 
 Output items are named with a sequence of identifiers, separated by
@@ -348,8 +348,8 @@ must appear in the order given -- though the translator is free to insert
 additional items in between them.  (The particular output items needn't be
 defined already -- indeed, they needn't be defined ever.)
 
-There is a predefined output item @"includes" in both the @"c" and @"h"
-output files which is a suitable place for inserting @"\#include"
+There is a predefined output item @|includes| in both the @|c| and @|h|
+output files which is a suitable place for inserting @|\#include|
 preprocessor directives in order to declare types and functions for use
 elsewhere in the generated output files.
 
@@ -591,18 +591,18 @@ language: you must use Lisp to do this, and it's quite involved.
 The @<properties> provide additional information.  The standard class
 properties are as follows.
 \begin{description}
-\item[@"lisp_class"] The name of the Lisp class to use within the translator
+\item[@|lisp_class|] The name of the Lisp class to use within the translator
   to represent this class.  The property value must be an identifier; the
-  default is @"sod_class".  Extensions may define classes with additional
+  default is @|sod_class|.  Extensions may define classes with additional
   behaviour, and may recognize additional class properties.
-\item[@"metaclass"] The name of the Sod metaclass for this class.  In the
+\item[@|metaclass|] The name of the Sod metaclass for this class.  In the
   generated code, a class is itself an instance of another class -- its
   \emph{metaclass}.  The metaclass defines which slots the class will have,
   which messages it will respond to, and what its behaviour will be when it
   receives them.  The property value must be an identifier naming a defined
-  subclass of @"SodClass".  The default metaclass is @"SodClass".
+  subclass of @|SodClass|.  The default metaclass is @|SodClass|.
   See \xref{sec:concepts.metaclasses} for more details.
-\item[@"nick"] A nickname for the class, to be used to distinguish it from
+\item[@|nick|] A nickname for the class, to be used to distinguish it from
   other classes in various limited contexts.  The property value must be an
   identifier; the default is constructed by forcing the class name to
   lower-case.
@@ -630,13 +630,13 @@ functions are fine.
 
 Properties:
 \begin{description}
-\item[@"slot_class"] A symbol naming the Lisp class to use to represent the
+\item[@|slot_class|] A symbol naming the Lisp class to use to represent the
   direct slot.
-\item[@"initarg"] An identifier naming an initialization argument which can
+\item[@|initarg|] An identifier naming an initialization argument which can
   be used to provide a value for the slot.  See
   \xref{sec:concepts.lifecycle.birth} for the details.
-\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
-  the initarg.  Only permitted if @"initarg" is also set.
+\item[@|initarg_class|] A symbol naming the Lisp class to use to represent
+  the initarg.  Only permitted if @|initarg| is also set.
 \end{description}
 
 An @<initializer>, if present, is treated as if a separate
@@ -667,7 +667,7 @@ class Example: Super \{                                         \\ \ind
 \end{grammar}
 
 An @<initializer-item> provides an initial value for one or more slots.  If
-prefixed by @"class", then the initial values are for class slots (i.e.,
+prefixed by @|class|, then the initial values are for class slots (i.e.,
 slots of the class object itself); otherwise they are for instance slots.
 
 The first component of the @<dotted-name> must be the nickname of one of the
@@ -676,15 +676,15 @@ slot defined in that superclass.
 
 Properties:
 \begin{description}
-\item[@"initializer_class"] A symbol naming the Lisp class to use to
+\item[@|initializer_class|] A symbol naming the Lisp class to use to
   represent the initializer.
-\item[@"initarg"] An identifier naming an initialization argument which can
+\item[@|initarg|] An identifier naming an initialization argument which can
   be used to provide a value for the slot.  See
   \xref{sec:concepts.lifecycle.birth} for the details.  An initializer item
   must have either an @|initarg| property, or an initializer expression, or
   both.
-\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
-  the initarg.  Only permitted if @"initarg" is also set.
+\item[@|initarg_class|] A symbol naming the Lisp class to use to represent
+  the initarg.  Only permitted if @|initarg| is also set.
 \end{description}
 
 Each class may define at most one initializer item with an explicit
@@ -699,7 +699,7 @@ initializer expression for a given slot.
 \end{grammar}
 Properties:
 \begin{description}
-\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
+\item[@|initarg_class|] A symbol naming the Lisp class to use to represent
   the initarg.
 \end{description}
 
@@ -719,44 +719,44 @@ Properties:
 \end{grammar}
 Properties:
 \begin{description}
-\item[@"message_class"] A symbol naming the Lisp class to use to represent
+\item[@|message_class|] A symbol naming the Lisp class to use to represent
   the message.
-\item[@"combination"] A keyword naming the aggregating method combination to
+\item[@|combination|] A keyword naming the aggregating method combination to
   use.
-\item[@"most_specific"] A keyword, either @`first' or @`last', according to
+\item[@|most_specific|] A keyword, either @`first' or @`last', according to
   whether the most specific applicable method should be invoked first or
   last.
 \end{description}
 
 Properties for the @|custom| aggregating method combination:
 \begin{description}
-\item[@"retvar"] An identifier for the return value from the effective
+\item[@|retvar|] An identifier for the return value from the effective
   method.  The default is @|sod__ret|.  Only permitted if the message return
   type is not @|void|.
-\item[@"valvar"] An identifier holding each return value from a direct method
+\item[@|valvar|] An identifier holding each return value from a direct method
   in the effective method.  The default is @|sod__val|.  Only permitted if
-  the method return type (see @"methty" below) is not @|void|.
-\item[@"methty"] A C type, which is the return type for direct methods of
+  the method return type (see @|methty| below) is not @|void|.
+\item[@|methty|] A C type, which is the return type for direct methods of
   this message.  The default is the return type of the message.
-\item[@"decls"] A code fragment containing declarations to be inserted at the
+\item[@|decls|] A code fragment containing declarations to be inserted at the
   head of the effective method body.  The default is to insert nothing.
-\item[@"before"] A code fragment containing initialization to be performed at
+\item[@|before|] A code fragment containing initialization to be performed at
   the beginning of the effective method body.  The default is to insert
   nothing.
-\item[@"empty"] A code fragment executed if there are no primary methods;
+\item[@|empty|] A code fragment executed if there are no primary methods;
   it should usually store a suitable (identity) value in @<retvar>.  The
   default is not to emit an effective method at all if there are no primary
   methods.
-\item[@"first"] A code fragment to set the return value after calling the
-  first applicable direct method.  The default is to use the @"each"
+\item[@|first|] A code fragment to set the return value after calling the
+  first applicable direct method.  The default is to use the @|each|
   fragment.
-\item[@"each"] A code fragment to set the return value after calling a direct
-  method.  If @"first" is also set, then it is used after the first direct
+\item[@|each|] A code fragment to set the return value after calling a direct
+  method.  If @|first| is also set, then it is used after the first direct
   method instead of this.  The default is to insert nothing, which is
   probably not what you want.
-\item[@"after"] A code fragment inserted at the end of the effective method
+\item[@|after|] A code fragment inserted at the end of the effective method
   body.  The default is to insert nothing.
-\item[@"count"] An identifier naming a variable to be declared in the
+\item[@|count|] An identifier naming a variable to be declared in the
   effective method body, of type @|size_t|, holding the number of applicable
   methods.  The default is not to provide such a variable.
 \end{description}
@@ -772,9 +772,9 @@ Properties for the @|custom| aggregating method combination:
 \end{grammar}
 Properties:
 \begin{description}
-\item[@"method_class"] A symbol naming the Lisp class to use to represent
+\item[@|method_class|] A symbol naming the Lisp class to use to represent
   the direct method.
-\item[@"role"] A keyword naming the direct method's rÃ´le.  For the built-in
+\item[@|role|] A keyword naming the direct method's rÃ´le.  For the built-in
   `simple' message classes, the acceptable rÃ´le names are @|before|,
   @|after|, and @|around|.  By default, a primary method is constructed.
 \end{description}
diff --git a/doc/tutorial.tex b/doc/tutorial.tex
index 3d90293..0e935f2 100644
--- a/doc/tutorial.tex
+++ b/doc/tutorial.tex
@@ -126,11 +126,11 @@ The following is a simple Sod input file.
     \}                                                        \-\\
   \}
 \end{prog}
-Save it as @"greeter.sod", and run
+Save it as @|greeter.sod|, and run
 \begin{prog}
   sod --gc --gh greeter
 \end{prog}
-This will create files @"greeter.c" and @"greeter.h" in the current
+This will create files @|greeter.c| and @|greeter.h| in the current
 directory.  Here's how we might use such a simple thing.
 \begin{prog}
   \#include "greeter.h"                                         \\+
@@ -153,12 +153,12 @@ Compare this to the traditional
 and I'm sure you'll appreciate the benefits of using Sod already -- mostly to
 do with finger exercise.  Trust me, it gets more useful.
 
-The @".sod" file was almost comprehensible.  There are two important parts to
+The @|.sod| file was almost comprehensible.  There are two important parts to
 it (after the comment which tells Emacs how to cope with it).
 
-The first part consists of the two @"code" stanzas.  Both of them define
-gobbets of raw C code to copy into output files.  The first one, @"code~:
-c"~\ldots, says that
+The first part consists of the two @|code| stanzas.  Both of them define
+gobbets of raw C code to copy into output files.  The first one, @|code~:
+c|~\ldots, says that
 \begin{prog}
   \#include "greeter.h"
 \end{prog}
@@ -168,24 +168,24 @@ needs to appear in the generated @|greeter.c| file; the second says that
   \#include <sod/sod.h>
 \end{prog}
 needs to appear in the header file @|greeter.h|.  The generated C files need
-to get declarations for external types and functions (e.g., @"FILE" and
-@"fputs") from somewhere, and the generated @".c" file will need the
-declarations from the corresponding @".h" file.  Sod takes a very simple
+to get declarations for external types and functions (e.g., @|FILE| and
+@|fputs|) from somewhere, and the generated @|.c| file will need the
+declarations from the corresponding @|.h| file.  Sod takes a very simple
 approach to all of this: it expects you, the programmer, to deal with it.
 
-The basic syntax for @"code" stanzas is
+The basic syntax for @|code| stanzas is
 \begin{prog}
   code @<file-label>: @<section> \{                             \\ \ind
     @<code>                                                   \-\\
   \}
 \end{prog}
-The @<file-label> is either @"c" or @"h", and says which output file the code
+The @<file-label> is either @|c| or @|h|, and says which output file the code
 wants to be written to.  The @<section> is a name which explains where in the
-output file to place the code.  The @"includes" section is the usual choice:
+output file to place the code.  The @|includes| section is the usual choice:
 it's the `right' place for @`\#include' directives and similar declarations.
 
 The remaining part, the `meat' of the file, defines a class called
-@"greeter".  The class can respond to a single message, named @"greet", and
+@|greeter|.  The class can respond to a single message, named @|greet|, and
 in response, it writes a traditional greeting to the file passed in with the
 message.
 
@@ -194,27 +194,27 @@ bizarre looking runes.  Let's take it one step at a time.
 \begin{prog}
   struct Greeter__ilayout g_obj;
 \end{prog}
-allocates space for an instance of class @"Greeter".  We're not going to use
+allocates space for an instance of class @|Greeter|.  We're not going to use
 this space directly.  Instead, we do this frightening looking thing.
 \begin{prog}
   Greeter *g = Greeter__class@->cls.init(\&g_obj);
 \end{prog}
-Taking it slowly: @"Greeter__class" is a pointer to the object that
-represents our class @"Greeter".  This object contains a member, named
-@"cls.init", which points to a function whose job is to turn uninitialized
+Taking it slowly: @|Greeter__class| is a pointer to the object that
+represents our class @|Greeter|.  This object contains a member, named
+@|cls.init|, which points to a function whose job is to turn uninitialized
 storage space into working instances of the class.  It returns a pointer to
 the instance, which we use in preference to grovelling about in the
-@"ilayout" structure.
+@|ilayout| structure.
 
 Having done this, we `send the instance a message':
 \begin{prog}
   g@->_vt@->greeter.greet(g, stdout);
 \end{prog}
 This looks horrific, and seems to repeat itself quite unnecessarily.  The
-first @"g" is the recipient of our `message'.  The second is indeed a copy of
+first @|g| is the recipient of our `message'.  The second is indeed a copy of
 the first: we have to tell it who it is.  (Sod doesn't extend C's syntax, so
 this is the sort of thing we just have to put up with.)  The lowercase
-@"greeter" is our class's `nickname': we didn't choose one explicitly, so Sod
+@|greeter| is our class's `nickname': we didn't choose one explicitly, so Sod
 picked one by forcing the classname to lowercase.
 
 %%%----- That's all, folks --------------------------------------------------
-- 
2.11.0

