Documentation updates and clarifications

This adds placeholders for reference documentation.

doc/cljdoc.edn

@@ -2,6 +2,7 @@
  [["Readme" {:file "README.md"}]
   ["Changes" {:file "CHANGELOG.md"}]
   ["Getting Started" {:file "doc/getting-started.md"}
+   ["General Reference" {:file "doc/general-reference.md"}]
    ["SQL Clause Reference" {:file "doc/clause-reference.md"}]
    ["SQL Operator Reference" {:file "doc/operator-reference.md"}]
    ["SQL 'Special Syntax'" {:file "doc/special-syntax.md"}]

doc/differences-from-1-x.md

@@ -10,7 +10,7 @@ HoneySQL 1.x supported Clojure 1.7 and later. HoneySQL 2.x requires Clojure 1.9
 
 ## Group, Artifact, and Namespaces
 
-HoneySQL 2.x uses the group ID `com.github.seancorfield` with the original artifact ID of `honeysql`, in line with the recommendations in Inside Clojure's post about the changes in the Clojure CLI: [Deprecated unqualified lib names](https://insideclojure.org/2020/07/28/clj-exec/).
+HoneySQL 2.x uses the group ID `com.github.seancorfield` with the original artifact ID of `honeysql`, in line with the recommendations in Inside Clojure's post about the changes in the Clojure CLI: [Deprecated unqualified lib names](https://insideclojure.org/2020/07/28/clj-exec/); also Clojars [Verified Group Names policy](https://github.com/clojars/clojars-web/wiki/Verified-Group-Names).
 
 In addition, HoneySQL 2.x contains different namespaces so you can have both versions on your classpath without introducing any conflicts. The primary API is now in `honey.sql` and the helpers are in `honey.sql.helpers`. A Spec for the DSL data structure will be available in `honey.specs` at some point (work in progress).
 
@@ -80,7 +80,7 @@ You can now select a non-ANSI dialect of SQL using the new `honey.sql/set-dialec
 
 As noted above, the variadic options for `format` have been replaced by a single hash map as the optional second argument to `format`.
 
-The `:quoting <dialect>` option has superseded by the new dialect machinery and a new `:quoted` option that turns quoting on or off. You either use `:dialect <dialect>` instead or set a default dialect (via `set-dialect!`) and then use `{:quoted true}` in `format` calls where you want quoting.
+The `:quoting <dialect>` option has superseded by the new dialect machinery and a new `:quoted` option that turns quoting on or off. You either use `:dialect <dialect>` instead or set a default dialect (via `set-dialect!`) and then use `:quoted true` in `format` calls where you want quoting.
 
 Identifiers are automatically quoted if you specify a `:dialect` option to `format`, unless you also specify `:quoted false`.
 
@@ -105,11 +105,14 @@ The following new syntax has been added:
 * `:cast` -- `[:cast expr :type]` => `CAST( expr AS type )`,
 * `:composite` -- explicit syntax to produce a comma-separated list of expressions, wrapped in parentheses,
 * `:default` -- for `DEFAULT` values (in inserts) and for declaring column defaults in table definitions,
+* `:escape` -- used to wrap a regular expression so that non-standard escape characters can be provided,
 * `:inline` -- used as a function to replace the `sql/inline` / `#sql/inline` machinery,
-* `:interval` -- used as a function to support `INTERVAL <n> <units>`, e.g., `[:interval 30 :days]`.
+* `:interval` -- used as a function to support `INTERVAL <n> <units>`, e.g., `[:interval 30 :days]`,
+* `:lateral` -- used to wrap a statement or expression, to provide a `LATERAL` join,
 * `:lift` -- used as a function to prevent interpretation of a Clojure data structure as DSL syntax (e.g., when passing a vector or hash map as a parameter value) -- this should mostly be a replacement for `honeysql.format/value`,
 * `:nest` -- used as a function to add an extra level of nesting (parentheses) around an expression,
 * `:not` -- this is now explicit syntax,
+* `:over` -- the function-like part of a T-SQL window clause,
 * `:param` -- used as a function to replace the `sql/param` / `#sql/param` machinery,
 * `:raw` -- used as a function to replace the `sql/raw` / `#sql/raw` machinery. Vector subexpressions inside a `[:raw ..]` expression are formatted to SQL and parameters. Other subexpressions are just turned into strings and concatenated. This is different to the v1 behavior but should be more flexible, since you can now embed `:inline`, `:param`, and `:lift` inside a `:raw` expression.
 
@@ -117,8 +120,10 @@ The following new syntax has been added:
 
 Several additional pieces of syntax have also been added to support column
 definitions in `CREATE TABLE` clauses, now that v2 supports DDL statement
-construction: `:constraint`, `:foreign-key`, `:index`, `:primary-key`,
-`:references`, `:unique`, and -- as noted above -- `:default`.
+construction:
+
+* `:constraint`, `:default`, `:foreign-key`, `:index`, `:primary-key`, `:references`, `:unique`,
+* `:entity` -- used to force an expression to be rendered as a SQL entity (instead of a SQL keyword).
 
 ### select and function calls
 
@@ -174,6 +179,7 @@ And, finally, you can register new operators that will be recognized in expressi
 The `honey.sql.helpers` namespace includes a helper function that corresponds to every supported piece of the data DSL understood by HoneySQL (v1 only had a limited set of helper functions). Unlike v1 helpers which sometimes had both a regular helper and a `merge-` helper, v2 helpers will all merge clauses by default (if that makes sense for the underlying DSL): use `:dissoc` if you want to force an overwrite.
 
 The only helpers that have non-merging behavior are:
-* `intersect`, `union`, `union-all`, `except`, and `except-all` which always wrap around their arguments,
-* `delete`, `set`, `limit`, `offset`, `for`, and `values` which overwrite, rather than merge,
-* `composite` which is a convenience for the `:composite` syntax mentioned above: `(composite :a :b)` is the same as `[:composite :a :b]` which produces `(a, b)`.
+* The SQL set operations `intersect`, `union`, `union-all`, `except`, and `except-all` which always wrap around their arguments,
+* The SQL clauses `delete`, `fetch`, `for`, `limit`, `lock`, `offset`, `on-constraint`, `set`, `truncate`, `update`, and `values` which overwrite, rather than merge,
+* The DDL helpers `drop-column`, `drop-index`, `rename-table`, and `with-data`,
+* The function helper `composite` which is a convenience for the `:composite` syntax mentioned above: `(composite :a :b)` is the same as `[:composite :a :b]` which produces `(a, b)`.

doc/general-reference.md

@@ -0,0 +1,28 @@
+# General Reference Documentation
+
+This section provides more details about specific behavior in HoneySQL and
+how to generate certain SQL constructs.
+
+## SQL Entity Generation
+
+See #313
+
+## Tuples and Composite Values
+
+See #314
+
+## Other Sections Will Be Added!
+
+## Other Reference Documentation
+
+The full list of supported SQL clauses is documented in the
+[Clause Reference](clause-reference.md). The full list
+of operators supported (as prefix-form "functions") is
+documented in the [Operator Reference](operator-reference.md)
+section. The full list
+of "special syntax" functions is documented in the
+[Special Syntax](special-syntax.md) section. The best
+documentation for the helper functions is in the
+[honey.sql.helpers](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-alpha3/api/honey.sql.helpers) namespace.
+If you're migrating to HoneySQL 2.0, this [overview of differences
+between 1.0 and 2.0](differences-from-1-x.md) should help.

doc/getting-started.md

@@ -26,7 +26,7 @@ To execute SQL statements, you will also need a JDBC wrapper like
 
 SQL statements are represented as hash maps, with keys that
 represent clauses in SQL. SQL expressions are generally
-represented as vectors, where the first element identifies
+represented as sequences, where the first element identifies
 the function or operator and the remaining elements are the
 arguments or operands.
 
@@ -50,10 +50,10 @@ or symbols, are treated as positional parameters and replaced
 by `?` in the SQL string and lifted out into the vector that
 is returned from `format`.
 
-Most clauses expect a vector as their value, containing
+Most clauses expect a sequence as their value, containing
 either a list of SQL entities or the representation of a SQL
 expression. Some clauses accept a single SQL entity. A few
-accept a most specialized form (such as `:set` accepting a
+accept a more specialized form (such as `:set` accepting a
 hash map of SQL entities and SQL expressions).
 
 A SQL entity can be a simple keyword (or symbol) or a pair
@@ -97,7 +97,7 @@ the table name, i.e., `:foo/bar` instead of `:foo.bar`:
 ## SQL Expressions
 
 In addition to using hash maps to describe SQL clauses,
-HoneySQL uses vectors to describe SQL expressions. Any
+HoneySQL uses sequences to describe SQL expressions. Any
 sequence that begins with a keyword (or symbol) is considered
 to be a kind of function invocation. Certain "functions" are
 considered to be "special syntax" and have custom rendering.
@@ -168,7 +168,7 @@ call as the `:params` key of the options hash map.
 
 ## Functional Helpers
 
-In addition to the hash map (and vectors) approach of building
+In addition to the hash map (and sequences) approach of building
 SQL queries with raw Clojure data structures, a namespace full
 of helper functions is also available. These functions are
 generally variadic and threadable:
@@ -188,9 +188,9 @@ generally variadic and threadable:
 
 There is a helper function for every single clause that HoneySQL
 supports out of the box. In addition, there are helpers for
-`composite` and `over` that make it easier to construct those
-parts of the SQL DSL (examples of the former appear in the [README](README.md),
-examples of the latter appear in the [Clause Reference](docs/clause-reference.md))
+`composite`, `lateral`, `over`, and `upsert` that make it easier to construct those
+parts of the SQL DSL (examples of `composite` appear in the [README](README.md),
+examples of `over` appear in the [Clause Reference](docs/clause-reference.md))
 
 In addition to being variadic -- which often lets you omit one
 level of `[`..`]` -- the helper functions merge clauses, which
@@ -225,7 +225,7 @@ can rely on using keywords in `dissoc`.
 
 The following helpers shadow functions in `clojure.core` so
 you need to consider this when referring symbols in from the
-`honey.sql.helpers` namespace: `for`, `group-by`, `partition-by`,
+`honey.sql.helpers` namespace: `for`, `group-by`, `into`, `partition-by`,
 `set`, and `update`.
 
 ## DDL Statements
@@ -234,7 +234,7 @@ HoneySQL 1.x did not support any DDL statements. It was fairly
 common for people to use the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres)
 to get DDL support, even if they didn't need the PostgreSQL-specific
 extensions. That library does not work with HoneySQL 2.x but all
-of the functionality from it has been incorporated
+of the functionality from it (up to 0.3.104) has been incorporated
 into HoneySQL now and is described in the [PostgreSQL](postgresql.md)
 section (because that covers all of the things that the nilenso
 library supported and much of it was PostgreSQL-specific!).
@@ -288,7 +288,7 @@ specify a dialect in the `format` call, you can specify
 Out of the box, as part of the extended ANSI SQL support,
 HoneySQL supports quite a few [PostgreSQL extensions](postgresql.md).
 
-> Note: the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres) which provided PostgreSQL support for HoneySQL 1.x does not work with HoneySQL 2.x. However, HoneySQL 2.x includes all of the functionality from that library out of the box!
+> Note: the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres) which provided PostgreSQL support for HoneySQL 1.x does not work with HoneySQL 2.x. However, HoneySQL 2.x includes all of the functionality from that library (up to 0.3.104) out of the box!
 
 ## Format Options
 
@@ -319,5 +319,7 @@ of "special syntax" functions is documented in the
 [Special Syntax](special-syntax.md) section. The best
 documentation for the helper functions is in the
 [honey.sql.helpers](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-alpha3/api/honey.sql.helpers) namespace.
+More detail about certain core HoneySQL functionality can be found in the
+[Reference documentation](general-reference.md).
 If you're migrating to HoneySQL 2.0, this [overview of differences
 between 1.0 and 2.0](differences-from-1-x.md) should help.