Kill smart quotes and emdashes beloved by MS Word and despised by the rest of the...
[Evergreen.git] / docs / TechRef / JSONTutorial.xml
index afc0cf3..068a13a 100644 (file)
@@ -41,7 +41,7 @@
                        doesn't have to. </para>
                <para> Nevertheless, the need to encode a query in a JSON string adds complications,
                        because the client needs to know how to build the right JSON.  JSON queries are also
-                       somewhat limiting  they can't do all of the things that you can do with raw SQL. </para>
+                       somewhat limiting -- they can't do all of the things that you can do with raw SQL. </para>
                <para> This tutorial explains what you can do with a JSON query, and how you can do it. </para>
 
                <sect3>
@@ -63,7 +63,7 @@
 
                <sect3>
                        <title>Definitions</title>
-                       <para> References to “SQL” refer to the dialect implemented by PostgreSQL.  This tutorial
+                       <para> References to "SQL" refer to the dialect implemented by PostgreSQL.  This tutorial
                                assumes that you are already familiar with SQL. </para>
                        <para> You should also be familiar with JSON.  However it is worth defining a couple of terms
                                that have other meanings in other contexts: </para>
                        <itemizedlist>
 
                                <listitem>
-                                       <para> An “object” is a JSON object, i.e. a comma-separated list of name:value pairs,
+                                       <para> An "object" is a JSON object, i.e. a comma-separated list of name:value pairs,
                                                enclosed in curly braces, like this:
                                                <informalexample>
                                                        <programlisting>
-       { “a”:”frobozz”, “b”:24, “c”:null }
+       { "a":"frobozz", "b":24, "c":null }
                                                        </programlisting>
                                                </informalexample>
                                        </para>
                                </listitem>
 
                                <listitem>
-                                       <para> An “array” is a JSON array, i.e. a comma-separated list of values, enclosed
+                                       <para> An "array" is a JSON array, i.e. a comma-separated list of values, enclosed
                                                in square brackets, like this:
                                                <informalexample>
                                                        <programlisting>
-       [ “Goober”, 629, null, false, “glub” ]
+       [ "Goober", 629, null, false, "glub" ]
                                                        </programlisting>
                                                </informalexample>
                                        </para>
                                few related tables.  The queries themselves are designed to illustrate the syntax, not
                                to do anything useful at the application level.  For example, it's not meaningful to
                                take the square root of an org_unit id, except to illustrate how to code a function call.
-                               The examples are like department store mannequins  they have no brains, they're only
+                               The examples are like department store mannequins -- they have no brains, they're only
                                for display. </para>
                </sect3>
 
                                the default SELECT clause. </para>
                        <para> If the FROM clause joins two or more tables, the default SELECT clause includes
                                columns only from the core table, not from any of the joined tables. </para>
-                       <para> The default SELECT clause has almost the same effect as “<literal>SELECT *</literal>”,
-                               but not exactly.  If you were to <literal>SELECT * from actor.org_unit_type</literal>
+                       <para> The default SELECT clause has almost the same effect as "<literal>SELECT *</literal>",
+                               but not exactly.  If you were to "<literal>SELECT * from actor.org_unit_type</literal>
                                in psql, the output would include all the same columns as in the example above, but not in
                                the same order.  A default SELECT clause includes the columns in the order in which the IDL
                                defines them, which may be different from the order in which the database defines them. </para>
                        <para> There are other ways to get a default SELECT clause.  However, default SELECT clauses
                                are a distraction at this point, because most of the time you'll specify your own SELECT
                                clause explicitly, as we will discuss later. </para>
-                       <para> Let's consider some more important aspects of this simple example  more important
+                       <para> Let's consider some more important aspects of this simple example -- more important
                                because they apply to more complex queries as well. </para>
 
                        <itemizedlist>
 
                <para> While this syntax may not be terribly useful, it does illustrate the minimal structure
                        of a SELECT clause in a JSON query: an entry in the outermost JSON object, with a key of
-                       <literal>“select”</literal>.  The value associated with this key is another JSON object,
+                       <literal>"select"</literal>.  The value associated with this key is another JSON object,
                        whose keys are class names. </para>
                <para> (These two examples also illustrate another point: unlike SQL, a JSON query doesn't care
                        whether the FROM clause or the SELECT clause comes first.) </para>
                        <itemizedlist>
 
                                <listitem>
-                                       <para> <literal>“column”</literal> -- the column name (required). </para>
+                                       <para> <literal>"column"</literal> -- the column name (required). </para>
                                </listitem>
 
                                <listitem>
-                                       <para> <literal>“alias”</literal> -- used to define a column alias, which
+                                       <para> <literal>"alias"</literal> -- used to define a column alias, which
                                                otherwise defaults to the column name. </para>
                                </listitem>
 
                                <listitem>
-                                       <para> <literal>“aggregate”</literal> -- takes a value of
+                                       <para> <literal>"aggregate"</literal> -- takes a value of
                                                <literal>true</literal> or <literal>false.</literal>  Don't worry about
                                                this one yet.  It concerns the use of GROUP BY clauses, which we will
                                                examine later. </para>
                                </listitem>
 
                                <listitem>
-                                       <para> <literal>“transform”</literal> -- the name of an SQL function to be
+                                       <para> <literal>"transform"</literal> -- the name of an SQL function to be
                                                called. </para>
                                </listitem>
 
                                <listitem>
-                                       <para> <literal>“result_field”</literal> -- used with
-                                               <literal>“transform”</literal>; specifies an output column of a function that
+                                       <para> <literal>"result_field"</literal> -- used with
+                                               <literal>"transform"</literal>; specifies an output column of a function that
                                                returns multiple columns at a time. </para>
                                </listitem>
 
                                <listitem>
-                                       <para> <literal>“params”</literal> -- used with <literal>“transform”</literal>;
+                                       <para> <literal>"params"</literal> -- used with <literal>"transform"</literal>;
                                                provides a list of parameters for the function.  They may be strings, numbers,
                                                or nulls. </para>
                                </listitem>
                        </informalexample>
 
                        <para> In this case, changing the column alias doesn't accomplish much.  But if we
-                               were joining to the actor.org_unit_type table, which also has a “name” column,
+                               were joining to the actor.org_unit_type table, which also has a "name" column,
                                we could use different aliases to distinguish them. </para>
                        <para> The following example uses a function to raise a column to upper case: </para>
 
                                </programlisting>
                        </informalexample>
 
-                       <para> Here we take a substring of the name, using the <literal>“params”</literal>
+                       <para> Here we take a substring of the name, using the <literal>"params"</literal>
                                element to pass parameters: </para>
 
                        <informalexample>
                                </programlisting>
                        </informalexample>
 
-                       <para> The parameters specified with <literal>“params”</literal> are inserted
-                               <emphasis>after</emphasis> the applicable column (<literal>“name”</literal> in this
+                       <para> The parameters specified with <literal>"params"</literal> are inserted
+                               <emphasis>after</emphasis> the applicable column (<literal>"name"</literal> in this
                                case), which is always the first parameter.  They are always passed as strings,
                                i.e. enclosed in quotes, even if the JSON expresses them as numbers.  PostgreSQL
                                will ordinarily coerce them to the right type.  However if the function name is
                                overloaded to accept different types, PostgreSQL may invoke a function other than
                                the one intended. </para>
-                       <para> Finally we call a fictitious function <literal>“frobozz”</literal> that returns
+                       <para> Finally we call a fictitious function <literal>"frobozz"</literal> that returns
                                multiple columns, where we want only one of them: </para>
 
                        <informalexample>
                                </programlisting>
                        </informalexample>
 
-                       <para> The “frobozz” function doesn't actually exist, but json_query doesn't know
+                       <para> The "frobozz" function doesn't actually exist, but json_query doesn't know
                                that.  The query won't fail until json_query tries to execute it in the database. </para>
                </sect3>
 
                                This limitation doesn't matter.  The results are returned in the form of a data
                                structure, which the client program can navigate however it likes. </para>
                        <para> You can't select an arbitrary expression, such as
-                               <literal>“percentage / 100”</literal> or <literal>“last_name || ', ' || first_name”</literal>.
+                               <literal>"percentage / 100"</literal> or <literal>"last_name || ', ' || first_name"</literal>.
                                Most of the time this limitation doesn't matter either, because the client program
                                can do these kinds of manipulations for itself.  However, function calls may be a problem.
                                You can't nest them, and you can't pass more than one column value to them (and it has
                </informalexample>
 
                <para> Like the SELECT clause, the WHERE clause gets its own entry in the top-level object
-                       of a JSON query.  The key is <literal>“where”</literal>, and the associated value is
+                       of a JSON query.  The key is <literal>"where"</literal>, and the associated value is
                        either an object (as shown here) or an array (to be discussed a bit later).  Each entry
                        in the object is a separate condition. </para>
                <para> In this case, we use a special shortcut for expressing an equality condition.  The
 
                <para> Like the SELECT clause, the generated WHERE clause qualifies each column name with
                        the alias of the relevant table. </para>
-               <para> If you want to compare a column to NULL, put “<literal>null</literal>” (without
+               <para> If you want to compare a column to NULL, put "<literal>null</literal>" (without
                        quotation marks) to the right of the colon instead of a literal value.  The resulting
-                       SQL will include <literal>“IS NULL”</literal> instead of an equals sign. </para>
+                       SQL will include <literal>"IS NULL"</literal> instead of an equals sign. </para>
 
                <sect3>
                        <title>Other Kinds of Comparisons</title>
                                </programlisting>
                        </informalexample>
 
-                       <para> The condition '<literal>“=”:null</literal>' turns into IS NULL.  Any other
-                               operator used with <literal>“null”</literal> turns into IS NOT NULL. </para>
+                       <para> The condition '<literal>"=":null</literal>' turns into IS NULL.  Any other
+                               operator used with <literal>"null"</literal> turns into IS NOT NULL. </para>
                        <para> You can use most of the comparison operators recognized by PostgreSQL: </para>
 
                        <programlisting language="SQL">
        similar to
                        </programlisting>
 
-                       <para> The only ones you can't use are <literal>“is distinct from”</literal> and
-                               <literal>“is not distinct from”</literal>. </para>
+                       <para> The only ones you can't use are <literal>"is distinct from"</literal> and
+                               <literal>"is not distinct from"</literal>. </para>
                </sect3>
 
                <sect3>
                        <para> Here's a dirty little secret: json_query doesn't really pay much attention to the
                                operator you supply.  It merely checks to make sure that the operator doesn't contain
                                any semicolons or white space, in order to prevent certain kinds of SQL injection.
-                               It also allows <literal>“similar to”</literal> as a special exception. </para>
+                               It also allows <literal>"similar to"</literal> as a special exception. </para>
                        <para> As a result, you can slip an operator of your own devising into the SQL, so long as
                                it doesn't contain any semicolons or white space, and doesn't create invalid syntax.
                                Here's a contrived and rather silly example: </para>
                                </programlisting>
                        </informalexample>
 
-                       <para> In a JSON query this approach doesn't work.  If you try it, the “= true” test will
+                       <para> In a JSON query this approach doesn't work.  If you try it, the "= true" test will
                                turn into IS NULL.  Don't do that.  Instead, use a leading plus sign, as described in
                                the preceding section, to treat the boolean column as a stand-alone condition: </para>
 
                        </informalexample>
 
                        <para> If you need to test for falsity, then write a test for truth and negate it with the
-                               <literal>“-not”</literal> operator.  We will discuss the “-not” operator later, but
+                               <literal>"-not"</literal> operator.  We will discuss the "-not" operator later, but
                                here's a preview: </para>
 
                        <informalexample>
                        </informalexample>
 
                        <para> In this case we compare the boolean column to a single simple condition.  However you
-                               can include additional complications  multiple conditions, IN lists, BETWEEN clauses,
+                               can include additional complications -- multiple conditions, IN lists, BETWEEN clauses,
                                and other features as described below. </para>
                </sect3>
 
                <sect3>
                        <title>Multiple Conditions</title>
-                       <para> If you need multiple conditions, just add them to the <literal>“where”</literal>
+                       <para> If you need multiple conditions, just add them to the <literal>"where"</literal>
                                object, separated by commas: </para>
 
                        <informalexample>
 
                        <informalexample>
                                <programlisting language="JSON">
-           “where”: {
-               “parent_ou”:{ “&gt;”:3 },
-               “parent_ou”:{ “&lt;&gt;”:7 }
+           "where": {
+               "parent_ou":{ "&gt;":3 },
+               "parent_ou":{ "&lt;&gt;":7 }
            }
                                </programlisting>
                        </informalexample>
 
                        <informalexample>
                                <programlisting language="JSON">
-           “where”: {
-               “parent_ou”: {
-                   “&gt;”:3,
-                   “&lt;&gt;”:7
+           "where": {
+               "parent_ou": {
+                   "&gt;":3,
+                   "&lt;&gt;":7
                }
            }
                                </programlisting>
                        </informalexample>
 
-                       <para> Nice try, but that doesn't work either.  Maybe it ought to work  at least it's
-                               legal JSON  but, no. </para>
+                       <para> Nice try, but that doesn't work either.  Maybe it ought to work -- at least it's
+                               legal JSON -- but, no. </para>
                        <para> Here's what works: </para>
 
                        <informalexample>
                                </programlisting>
                        </informalexample>
 
-                       <para> We use <literal>“-or”</literal> as the key, with the conditions to be ORed in an
+                       <para> We use <literal>"-or"</literal> as the key, with the conditions to be ORed in an
                                associated object.  The leading minus sign is there to make sure that the operator
                                isn't confused with a column name.  Later we'll see some other operators with leading
                                minus signs.  In a couple of spots we even use plus signs. </para>
                                </programlisting>
                        </informalexample>
 
-                       <para> The conditions paired with <literal>“-or”</literal> are linked by OR and enclosed
+                       <para> The conditions paired with <literal>"-or"</literal> are linked by OR and enclosed
                                in parentheses, </para>
                        <para> Here's how to do the same thing using an array, except that it produces an extra
                                layer of parentheses: </para>
                        </informalexample>
 
                        <para> It's possible, though not very useful, to have only a single condition subject to
-                               the <literal>“-or”</literal> operator.  In that case, the condition appears by itself,
+                               the <literal>"-or"</literal> operator.  In that case, the condition appears by itself,
                                since there's nothing to OR it to.  This trick is another way to add an extraneous
                                layer of parentheses, </para>
                </sect3>
 
                <sect3>
                        <title>Another way to AND</title>
-                       <para> You can also use the <literal>“-and”</literal> operator.  It works just like
-                               <literal>“-or”</literal>, except that it combines conditions with AND instead of OR.
+                       <para> You can also use the <literal>"-and"</literal> operator.  It works just like
+                               <literal>"-or"</literal>, except that it combines conditions with AND instead of OR.
                                Since AND is the default, we don't usually need a separate operator for it, but it's
                                available.
                        </para>
                        <para>
-                               In rare cases, nothing else will do  you can't include two conditions in the same
+                               In rare cases, nothing else will do -- you can't include two conditions in the same
                                list because of the duplicate key problem, but you can't combine them with arrays
                                either.  In particular, you might need to combine them within an expression that
                                you're comparing to a boolean column (see the subsection above on Testing Boolean
 
                <sect3>
                        <title>Negation with NOT</title>
-                       <para> The <literal>“-not”</literal> operator negates a condition or set of conditions.
+                       <para> The <literal>"-not"</literal> operator negates a condition or set of conditions.
                                For example: </para>
 
                        <informalexample>
 
                        <para> In this example we merely negate a combination of two comparisons.  However the
                                condition to be negated may be as complicated as it needs to be.  Anything that can
-                               be subject to <literal>“where”</literal> can be subject to
-                               <literal>“-not”</literal>. </para>
+                               be subject to <literal>"where"</literal> can be subject to
+                               <literal>"-not"</literal>. </para>
                        <para> In most cases you can achieve the same result by other means.  However the
-                               <literal>“-not”</literal> operator is the only way to represent NOT BETWEEN
+                               <literal>"-not"</literal> operator is the only way to represent NOT BETWEEN
                                (to be discussed later). </para>
                </sect3>
 
                <sect3>
                        <title>EXISTS with Subqueries</title>
-                       <para> Two other operators carry a leading minus sign: <literal>“-exists”</literal>
-                               and its negation <literal>“-not-exists”</literal>.  These operators apply to
+                       <para> Two other operators carry a leading minus sign: <literal>"-exists"</literal>
+                               and its negation <literal>"-not-exists"</literal>.  These operators apply to
                                subqueries, which have the same format as a full query.  For example: </para>
 
                        <informalexample>
                                </programlisting>
                        </informalexample>
 
-                       <para> Note the use of <literal>“+aou”</literal> to qualify the id column in the
+                       <para> Note the use of <literal>"+aou"</literal> to qualify the id column in the
                                inner WHERE clause. </para>
 
                        <informalexample>
                        </informalexample>
 
                        <para> The value associated with the column name is an object with a single
-                               entry, whose key is <literal>“between”</literal>.  The corresponding
+                               entry, whose key is <literal>"between"</literal>.  The corresponding
                                value is an array with exactly two values, defining the range to be
                                tested. </para>
                        <para> The range bounds must be either numbers or string literals.  Although
 
                        <para> This version results in the same SQL as the first one. </para>
                        <para> For a NOT IN list, you can use the latter format, using the
-                               <literal>“not in”</literal> operator instead of <literal>“in”</literal>.
+                               <literal>"not in"</literal> operator instead of <literal>"in"</literal>.
                                Alternatively, you can use either format together with the
-                               <literal>“-not”</literal> operator. </para>
+                               <literal>"-not"</literal> operator. </para>
                </sect3>
 
                <sect3>
                        <title>IN and NOT IN Clauses with Subqueries</title>
                        <para> For an IN clause with a subquery, the syntax is similar to the second
                                of the two formats for an IN list (see the previous subsection).  The
-                               <literal>“in”</literal> or <literal>“not in”</literal> operator is paired,
+                               <literal>"in"</literal> or <literal>"not in"</literal> operator is paired,
                                not with an array of values, but with an object representing the subquery.
                                For example: </para>
 
 
                        <para> In SQL the subquery may select multiple columns, but in a JSON query it
                                can select only a single column. </para>
-                       <para> For a NOT IN clause with a subquery, use the <literal>“not in”</literal>
-                               operator instead of <literal>“in”</literal>. </para>
+                       <para> For a NOT IN clause with a subquery, use the <literal>"not in"</literal>
+                               operator instead of <literal>"in"</literal>. </para>
                </sect3>
 
                <sect3>
                                </programlisting>
                        </informalexample>
 
-                       <para> A comparison operator (<literal>“&gt;”</literal> in this case) is paired
+                       <para> A comparison operator (<literal>"&gt;"</literal> in this case) is paired
                                with an array.  The first entry in the array must be a string giving the name
                                of the function.  The remaining parameters, if any, are the parameters.  They
                                may be strings, numbers, or nulls.  The resulting SQL for this example: </para>
                                </programlisting>
                        </informalexample>
 
-                       <para> The <literal>“transform”</literal> entry gives the name of the function that we
-                               will use on the left side of the comparison.  The <literal>“value”</literal> entry
+                       <para> The <literal>"transform"</literal> entry gives the name of the function that we
+                               will use on the left side of the comparison.  The <literal>"value"</literal> entry
                                designates the value on the right side of the comparison. </para>
 
                        <informalexample>
 
                        <para> As in the SELECT clause, you can pass literal values or nulls to the  function
                                as additional parameters by using an array tagged as
-                               <literal>“params”</literal>: </para>
+                               <literal>"params"</literal>: </para>
 
                        <informalexample>
                                <programlisting language="JSON">
                                followed by any additional parameters (which are always enclosed in quotes even
                                if they are numeric). </para>
                        <para> As in the SELECT clause: if the function returns multiple columns, you can specify
-                               the one you want by using a <literal>“result_field”</literal> entry (not shown
+                               the one you want by using a <literal>"result_field"</literal> entry (not shown
                                here). </para>
-                       <para> If you leave out the <literal>“transform”</literal> entry (or misspell it), the
+                       <para> If you leave out the <literal>"transform"</literal> entry (or misspell it), the
                                column name will appear on the left without any function call.  This syntax works,
                                but it's more complicated than it needs to be. </para>
                </sect3>
                <sect3>
                        <title>Putting Function Calls on Both Sides</title>
                        <para> If you want to compare one function call to another, you can use the same syntax
-                               shown in the previous subsection – except that the <literal>“value”</literal> entry
+                               shown in the previous subsection -- except that the <literal>"value"</literal> entry
                                carries an array instead of a literal value.  For example: </para>
 
                        <informalexample>
 
                                <listitem>
                                        <para> For a function call to the left of the comparison, the function name is
-                                               tagged as <literal>“transform”</literal>.  The first parameter is always the
+                                               tagged as <literal>"transform"</literal>.  The first parameter is always the
                                                relevant column name; additional parameters, if any, are in an array tagged
-                                               as <literal>“params”</literal>.  The entry for
-                                               <literal>“result_field”</literal>, if present, specifies a subcolumn. </para>
+                                               as <literal>"params"</literal>.  The entry for
+                                               <literal>"result_field"</literal>, if present, specifies a subcolumn. </para>
                                </listitem>
 
                                <listitem>
 
                <sect3>
                        <title>Comparing a Function to a Condition</title>
-                       <para> So far we have seen two kinds of data for the <literal>“value”</literal> tag.  A
+                       <para> So far we have seen two kinds of data for the <literal>"value"</literal> tag.  A
                                string or number translates to a literal value, and an array translates to a function
                                call.  The third possibility is a JSON object, which translates to a condition.  For
                                example: </para>
                                </programlisting>
                        </informalexample>
 
-                       <para> The function tagged as <literal>“transform”</literal> must return boolean, or else
+                       <para> The function tagged as <literal>"transform"</literal> must return boolean, or else
                                json_query will generate invalid SQL.  The function used here,
-                               <literal>“is_prime”</literal>, is fictitious. </para>
+                               <literal>"is_prime"</literal>, is fictitious. </para>
 
                        <informalexample>
                                <programlisting language="SQL">
                                </programlisting>
                        </informalexample>
 
-                       <para> If we left out the <literal>“transform”</literal> entry, json_query would compare
+                       <para> If we left out the <literal>"transform"</literal> entry, json_query would compare
                                the column on the left (which would to be boolean) to the condition on the right.
                                The results are similar to those for a simpler format described earlier (see the
                                subsection Testing Boolean Columns). </para>
                                However, in the WHERE clause these limitations are more limiting, because the client
                                program can't compensate by doing some of the work for itself. </para>
                        <para> You can't use arbitrary expressions in a WHERE condition, such as
-                               <literal>“WHERE id > parent_ou – 3”</literal>.  In some cases you may be able to
+                               <literal>"WHERE id > parent_ou -- 3"</literal>.  In some cases you may be able to
                                contrive a custom operator in order to fake such an expression.  However this mechanism
                                is neither very general nor very aesthetic. </para>
                        <para> To the right of a comparison operator, all function parameters must be literals or
                        <para> You can't include null values in an IN list or a BETWEEN list, not that you should
                                ever want to. </para>
                        <para> As noted earlier: you can't use the comparison operators
-                               <literal>“is distinct from”</literal> or <literal>“is not distinct from”</literal>. </para>
+                               <literal>"is distinct from"</literal> or <literal>"is not distinct from"</literal>. </para>
                        <para> Also as noted earlier: a subquery in an IN clause cannot select more than one
                                column. </para>
                </sect3>
        <sect2>
                <title>JOIN clauses</title>
                <para> Until now, our examples have selected from only one table at a time.  As a result,
-                       the FROM clause has been very simple  just a single string containing the class name of
+                       the FROM clause has been very simple -- just a single string containing the class name of
                        the relevant table. </para>
                <para> When the FROM clause joins multiple tables, the corresponding JSON naturally gets more
                        complicated. </para>
                </informalexample>
 
                <para> First, let's review the SELECT clause.  Since it selects rows from two different tables,
-                       the data for <literal>“select”</literal> includes two entries, one for each table. </para>
+                       the data for <literal>"select"</literal> includes two entries, one for each table. </para>
                <para> As for the FROM clause, it's no longer just a string.  It's a JSON object, with exactly
                        one entry.  The key of this entry is the class name of the core table, i.e. the table
                        named immediately after the FROM keyword.  The data associated with this key contains the
                                the attributes of the join. </para>
                        <para> Later we'll encounter other kinds of join attributes.  For now, the only
                                attributes that we're looking at are the ones that identify the join columns:
-                               <literal>“fkey”</literal> and <literal>“field”</literal>.  The hard part is
+                               <literal>"fkey"</literal> and <literal>"field"</literal>.  The hard part is
                                remembering which is which: </para>
 
                        <itemizedlist>
 
                                <listitem>
-                                       <para> <literal>“fkey”</literal> identifies the join column from the
+                                       <para> <literal>"fkey"</literal> identifies the join column from the
                                                <emphasis>left</emphasis> table; </para>
                                </listitem>
 
                                <listitem>
-                                       <para> <literal>“field”</literal> identifies the join column from the
+                                       <para> <literal>"field"</literal> identifies the join column from the
                                                <emphasis>right</emphasis> table. </para>
                                </listitem>
 
                <sect3>
                        <title>Specifying Only One Join Column</title>
                        <para> We just saw how to specify both ends of a join.  It turns out that there's a
-                               shortcut  most of the time you only need to specify one end.  Consider the
+                               shortcut -- most of the time you only need to specify one end.  Consider the
                                following variation on the previous example: </para>
 
                        <informalexample>
                                </programlisting>
                        </informalexample>
 
-                       <para> The <literal>“join”</literal> attribute introduces another level of join.  In this
-                               case <literal>“aou”</literal> is the left table for the nested join, and the right table
+                       <para> The <literal>"join"</literal> attribute introduces another level of join.  In this
+                               case <literal>"aou"</literal> is the left table for the nested join, and the right table
                                for the original join.  Here are the results: </para>
 
                        <informalexample>
                        </informalexample>
 
                        <para> Here we asked for a left outer join.  For a right outer join, code
-                               <literal>“type”:”right”</literal>.  For a full outer join, code
-                               <literal>“type”:”full”</literal>.  Any other value for “type” results in an inner
-                               join, so watch out for typos.  A type of <literal>“rihgt”</literal> will give you
+                               <literal>"type":"right"</literal>.  For a full outer join, code
+                               <literal>"type":"full"</literal>.  Any other value for "type" results in an inner
+                               join, so watch out for typos.  A type of <literal>"rihgt"</literal> will give you
                                a wrong join instead of a right one. </para>
                        <para> Here is the resulting SQL for this example: </para>
 
                                </programlisting>
                        </informalexample>
 
-                       <para> Note the peculiar operator <literal>“+aou”</literal> -- a plus sign followed
+                       <para> Note the peculiar operator <literal>"+aou"</literal> -- a plus sign followed
                                by the relevant class name.  This operator tells json_query to apply the specified
                                class to the condition that follows.  The result: </para>
 
                        </programlisting>
                        </informalexample>
 
-                       <para> By default, json_query uses AND to combine the <literal>“filter”</literal>
+                       <para> By default, json_query uses AND to combine the <literal>"filter"</literal>
                                condition with the original join condition.  If you need OR, you can use the
-                               <literal>“filter_op”</literal> attribute to say so: </para>
+                               <literal>"filter_op"</literal> attribute to say so: </para>
 
                        <informalexample>
                                <programlisting language="JSON">
                                </programlisting>
                        </informalexample>
 
-                       <para> If the data tagged by <literal>“filter_op”</literal> is anything but
-                               <literal>“or”</literal> (in upper, lower, or mixed case), json_query uses AND
+                       <para> If the data tagged by <literal>"filter_op"</literal> is anything but
+                               <literal>"or"</literal> (in upper, lower, or mixed case), json_query uses AND
                                instead of OR. </para>
-                       <para> The condition tagged by <literal>“filter”</literal> may be much more complicated.
+                       <para> The condition tagged by <literal>"filter"</literal> may be much more complicated.
                                In fact it accepts all the same syntax as the WHERE clause. </para>
                        <para> Remember, though, that it all gets combined with the the original join condition
                                with an AND, or with an OR if you so specify.  If you're not careful, the result
                                </programlisting>
                        </informalexample>
 
-                       <para> The <literal>“iatc”</literal> class is like a view, except that it's defined in the
+                       <para> The <literal>"iatc"</literal> class is like a view, except that it's defined in the
                                IDL instead of the database.  In this case it provides a way to do a join that would
                                otherwise be impossible through a JSON query, because it joins the same table in two
                                different ways (see the next subsection). </para>
                        </programlisting>
                </informalexample>
 
-               <para> The data associated with <literal>“from”</literal> is an array instead of a string
+               <para> The data associated with <literal>"from"</literal> is an array instead of a string
                                or an object.  The first element in the array specifies the name of the function.
                                Subsequent elements, if any, supply the parameters of the function; they must be
                                literal values or nulls. </para>
                        <itemizedlist>
 
                                <listitem>
-                                       <para> The <literal>“class”</literal> tag provides the name of the class,
+                                       <para> The <literal>"class"</literal> tag provides the name of the class,
                                                which must be either the core class or a joined class. </para>
                                </listitem>
 
                                <listitem>
-                                       <para> The <literal>“field”</literal> tag provides the field name, corresponding
+                                       <para> The <literal>"field"</literal> tag provides the field name, corresponding
                                                to one of the columns of the class. </para>
                                </listitem>
 
                        <para> If you want to sort by multiple fields, just include a separate object for each
                                field. </para>
                        <para> If you want to sort a field in descending order, add a
-                               <literal>“direction”</literal> tag: </para>
+                               <literal>"direction"</literal> tag: </para>
 
                        <informalexample>
                                <programlisting language="JSON">
                                </programlisting>
                        </informalexample>
 
-                       <para> The string tagged as <literal>“direction”</literal> can be anything – all that
-                               matters is the first character.  If the string starts with “D” or “d”, the sort
+                       <para> The string tagged as <literal>"direction"</literal> can be anything -- all that
+                               matters is the first character.  If the string starts with "D" or "d", the sort
                                will be descending.  Otherwise it will be ascending.  So
-                               <literal>“diplodocus”</literal> or <literal>“Dioscorides”</literal> will work as
-                               well as <literal>“desc”</literal>, but <literal>“going down”</literal> means that
+                               <literal>"diplodocus"</literal> or <literal>"Dioscorides"</literal> will work as
+                               well as <literal>"desc"</literal>, but <literal>"going down"</literal> means that
                                the sort will go up. </para>
                        <para> You can also pass a column through some kind of transforming function, much as
-                               you can in the SELECT and WHERE clauses, using the <literal>“transform”</literal>
+                               you can in the SELECT and WHERE clauses, using the <literal>"transform"</literal>
                                tag.  For example, for a case-insensitive sort, you could raise to upper case: </para>
 
                        <informalexample>
                        </informalexample>
 
                        <para> If you need additional parameters for the function, you can use the
-                               <literal>“params”</literal> tag to pass them: </para>
+                               <literal>"params"</literal> tag to pass them: </para>
 
                        <informalexample>
                                <programlisting language="JSON">
                        <para> As we have seen elsewhere, all literal values are passed as quoted strings,
                                even if they are numbers. </para>
                        <para> If the function returns multiple columns, you can use the
-                               <literal>“result_field”</literal> tag to indicate which one you want (not shown). </para>
+                               <literal>"result_field"</literal> tag to indicate which one you want (not shown). </para>
                </sect3>
 
                <sect3>
                                </programlisting>
                        </informalexample>
 
-                       <para> For the <literal>“aout”</literal> class, the associated array is simply a list
+                       <para> For the <literal>"aout"</literal> class, the associated array is simply a list
                                of field names (in this case, just one).  Naturally, each field must reside in
                                the class with which it is associated. </para>
                        <para> However, a list of field names provides no way to specify the direction of
                                sorting, or a transforming function.  You can add those details only if the
                                class name is paired with an object, as in the example for the
-                               <literal>“aou”</literal> class.  The keys for such an object are field names, and
+                               <literal>"aou"</literal> class.  The keys for such an object are field names, and
                                the associated tags define other details. </para>
-                       <para> In this example, we use the <literal>“direction”</literal> tag to specify that
+                       <para> In this example, we use the <literal>"direction"</literal> tag to specify that
                                the name field be sorted in descending order.  This tag works the same way here as
-                               described earlier.  If the associated string starts with “D” or “d”, the sort will
+                               described earlier.  If the associated string starts with "D" or "d", the sort will
                                be descending; otherwise it will be ascending. </para>
                        <para> Here is the resulting SQL: </para>
 
                                </programlisting>
                        </informalexample>
 
-                       <para> You can also use the  <literal>“transform</literal>”, <literal>“params”</literal>,
-                               and <literal>“result_field”</literal> tags to specify the use of a transforming
+                       <para> You can also use the  <literal>"transform</literal>", <literal>"params"</literal>,
+                               and <literal>"result_field"</literal> tags to specify the use of a transforming
                                function, as described in the previous subsection.  For example: </para>
 
                        <informalexample>
                                there are situations where it can be useful, provided that the column is passed to
                                a transforming function. </para>
                        <para> For example, you might want a case-insensitive sort, except that for any given
-                               letter you want lower case to sort first.  For example, you want “diBona” to sort
-                               before “Dibona”.  Here's a way to do that, coding the ORDER BY clause as an array: </para>
+                               letter you want lower case to sort first.  For example, you want "diBona" to sort
+                               before "Dibona".  Here's a way to do that, coding the ORDER BY clause as an array: </para>
 
                        <informalexample>
                                <programlisting language="JSON">
                        </programlisting>
                </informalexample>
 
-               <para> The <literal>“transform”</literal> tag is there just to give us an excuse to do a GROUP
-                       BY.  What's important to notice is the <literal>“aggregate”</literal> tag. </para>
+               <para> The <literal>"transform"</literal> tag is there just to give us an excuse to do a GROUP
+                       BY.  What's important to notice is the <literal>"aggregate"</literal> tag. </para>
                <para> Here's the resulting SQL: </para>
 
                <informalexample>
 
                <para> The GROUP BY clause references fields from the SELECT clause by numerical reference,
                        instead of by repeating them.  Notice that the field it references, parent_ou, is the
-                       one that <emphasis>doesn't</emphasis> carry the <literal>“aggregate”</literal> tag in
+                       one that <emphasis>doesn't</emphasis> carry the <literal>"aggregate"</literal> tag in
                        the JSON. </para>
                <para> Let's state that more generally.  The GROUP BY clause includes only the fields that
-                       do <emphasis>not</emphasis> carry the <literal>“aggregate”</literal> tag (or that carry
+                       do <emphasis>not</emphasis> carry the <literal>"aggregate"</literal> tag (or that carry
                        it with a value of false). </para>
                <para> However, that logic applies only when some field somewhere <emphasis>does</emphasis>
-                       carry the <literal>“aggregate”</literal> tag, with a value of true.  If there is no
-                       <literal>“aggregate”</literal> tag, or it appears only with a value of false, then there
+                       carry the <literal>"aggregate"</literal> tag, with a value of true.  If there is no
+                       <literal>"aggregate"</literal> tag, or it appears only with a value of false, then there
                        is no GROUP BY clause. </para>
                <para> If you really want to include every field in the GROUP BY clause, don't use
-                       <literal>“aggregate”</literal>.  Use the <literal>“distinct”</literal> tag, as described
+                       <literal>"aggregate"</literal>.  Use the <literal>"distinct"</literal> tag, as described
                        in the next section. </para>
        </sect2>
 
                        </programlisting>
                </informalexample>
 
-               <para> Note the <literal>“distinct”</literal> entry at the top level of the
-                       query object, with a value of “true”. </para>
+               <para> Note the <literal>"distinct"</literal> entry at the top level of the
+                       query object, with a value of "true". </para>
 
                <informalexample>
                        <programlisting language="SQL">
 
        <sect2>
                <title>The HAVING Clause</title>
-               <para> For a HAVING clause, add a <literal>“having”</literal> entry at the top level
+               <para> For a HAVING clause, add a <literal>"having"</literal> entry at the top level
                        of the query object.  For the associated data, you can use all the same syntax
                        that you can use for a WHERE clause. </para>
                <para> Here's a simple example: </para>
                        </programlisting>
                </informalexample>
 
-               <para> We use the “aggregate” tag in the SELECT clause to give us a GROUP  BY to go
+               <para> We use the "aggregate" tag in the SELECT clause to give us a GROUP  BY to go
                        with the HAVING.  Results: </para>
 
                <informalexample>
                        </programlisting>
                </informalexample>
 
-               <para> In raw SQL we could have referred to “count( 1 )”.  But since JSON queries
+               <para> In raw SQL we could have referred to "count( 1 )".  But since JSON queries
                        cannot encode arbitrary expressions, we applied the count function to a column
                        that cannot be null. </para>
        </sect2>
                        </programlisting>
                </informalexample>
 
-               <para> The data associated with <literal>“offset”</literal> and <literal>“limit”</literal>
+               <para> The data associated with <literal>"offset"</literal> and <literal>"limit"</literal>
                        may be either a number or a string, but if it's a string, it should have a number
                        inside. </para>
                <para> Result: </para>