From 8f7c990eed010504fca5da1bbf7e3b6c318b003b Mon Sep 17 00:00:00 2001
From: Sean Corfield <sean@worldsingles.com>
Date: Fri, 9 Apr 2021 17:23:39 -0700
Subject: [PATCH] Complete special syntax docs

---
 doc/clause-reference.md |  6 +++++-
 doc/special-syntax.md   | 20 +++++++++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/clause-reference.md b/doc/clause-reference.md
index e94a87b..00a3681 100644
--- a/doc/clause-reference.md
+++ b/doc/clause-reference.md
@@ -17,6 +17,10 @@ DDL clauses are listed first, followed by SQL clauses.
 
 HoneySQL supports the following DDL clauses as a data DSL.
 
+Several of these include column specifications and HoneySQL
+provides some special syntax (functions) to support that.
+See [Clause Descriptors in Special Syntax](special-syntax.md#clause-descriptors) for more details.
+
 ## alter-table, add-column, drop-column, modify-column, rename-column
 
 `:alter-table` can accept either a single table name or
@@ -118,7 +122,7 @@ will be uppercased (mostly to give the appearance of separating
 the column name from the SQL keywords).
 
 Various function-like expressions can be specified, as shown
-in the example above, but allow things like `CHECK` for a
+in the example above, that allow things like `CHECK` for a
 constraint, `FOREIGN KEY` (with a column name), `REFERENCES`
 (with a pair of column names). See [Clause Descriptors in Special Syntax](special-syntax.md#clause-descriptors) for more details.
 
diff --git a/doc/special-syntax.md b/doc/special-syntax.md
index 46d4e07..afce294 100644
--- a/doc/special-syntax.md
+++ b/doc/special-syntax.md
@@ -67,11 +67,24 @@ SQL entity. This is intended for use in contexts that would
 otherwise produce a sequence of SQL keywords, such as when
 constructing DDL statements.
 
+```clojure
+[:tablespace :quux]
+;;=> TABLESPACE QUUX
+[:tablespace [:entity :quux]]
+;;=> TABLESPACE quux
+```
+
 ## escape
 
 Intended to be used with regular expression patterns to
 specify the escape characters (if any).
 
+```clojure
+(format {:select :* :from :foo
+         :where [:similar-to :foo [:escape "bar" [:inline  "*"]]]})
+;;=> ["SELECT * FROM foo WHERE foo SIMILAR TO ? ESCAPE '*'" "bar"]))))
+```
+
 ## inline
 
 Accepts a single argument and tries to render it as a
@@ -101,7 +114,8 @@ that represents a time unit. Produces an `INTERVAL` expression:
 ## lateral
 
 Accepts a single argument that can be a (`SELECT`) clause or
-a (function call) expression.
+a (function call) expression. Produces a `LATERAL` subquery
+clause based on the `SELECT` clause or the SQL expression.
 
 ## lift
 
@@ -230,7 +244,7 @@ Otherwise, these render as regular function calls:
 [:primary-key :x :y] ;=> PRIMARY KEY(x, y)
 ```
 
-## constraint, default, references
+### constraint, default, references
 
 Although these are grouped together, they are generally
 used differently. This group renders as SQL keywords if
@@ -248,7 +262,7 @@ followed by the rest as a regular argument list:
 [:references :foo :bar] ;=> REFERENCES foo(bar)
 ```
 
-## index, unique
+### index, unique
 
 These behave like the group above except that if the
 first argument is `nil`, it is omitted: