fix #471 by documenting SQL kws in fn call args

CHANGELOG.md

@@ -3,7 +3,7 @@
 * 2.4.next in progress
   * Address [#474](https://github.com/seancorfield/honeysql/issues/474) by adding dot-selection special syntax.
   * Improve docstrings for PostgreSQL operators via PR [#473](https://github.com/seancorfield/honeysql/pull/473) [@holyjak](https://github.com/holyjak).
-  * Address [#471](https://github.com/seancorfield/honeysql/issues/471) by supporting interspersed SQL keywords in function calls. Documentation TBD!
+  * Address [#471](https://github.com/seancorfield/honeysql/issues/471) by supporting interspersed SQL keywords in function calls.
   * Fix [#467](https://github.com/seancorfield/honeysql/issues/467) by allowing single keywords (symbols) as a short hand for a single-element sequence in more constructs via PR [#470](https://github.com/seancorfield/honeysql/pull/470) [@p-himik](https://github.com/p-himik).
   * Address [#466](https://github.com/seancorfield/honeysql/issues/466) by treating `[:and]` as `TRUE` and `[:or]` as `FALSE`.
   * Fix [#465](https://github.com/seancorfield/honeysql/issues/465) to allow multiple columns in `:order-by` special syntax via PR [#468](https://github.com/seancorfield/honeysql/pull/468) [@p-himik](https://github.com/p-himik).

doc/getting-started.md

@@ -112,6 +112,30 @@ Some "functions" are considered to be operators. In general,
 
 > Note: you can use the `:numbered true` option to `format` to produce SQL containing numbered placeholders, like `FOO(a, $1, $2)`, instead of positional placeholders (`?`).
 
+As of 2.4.next, function calls with "named" arguments are supported
+which some databases support, e.g., MySQL and PostgreSQL both have
+`SUBSTRING()`:
+
+<!-- :test-doc-blocks/skip -->
+```clojure
+[:substring :col 3 4]              ;=> SUBSTRING(col, 3, 4)
+;; can also be written:
+[:substring :col :!from 3 :!for 4] ;=> SUBSTRING(col FROM 3 FOR 4)
+```
+
+In a function call, any keywords (or symbols) that begin with `!` followed
+by a letter are treated as inline SQL keywords to be used instead of `,`
+between arguments -- or in front of arguments, such as for `TRIM()`:
+
+<!-- :test-doc-blocks/skip -->
+```clojure
+[:trim :!leading "x" :!from :col] ;=> TRIM(LEADING ? FROM col), with "x" parameter
+[:trim :!both :!from :col]        ;=> TRIM(BOTH FROM col), trims spaces
+;; adjacent inline SQL keywords can be combined with a hyphen:
+[:trim :!both-from :col]          ;=> TRIM(BOTH FROM col)
+;; (because - in a SQL keyword is replaced by a space)
+```
+
 Operators are all treated as variadic (except for `:=` and
 `:<>` / `:!=` / `:not=` which are binary and require exactly two operands).
 Special syntax can have zero or more arguments and each form is