Merge pull request #2632 from Kodiologist/doc-tweaks

Documentation tweaks

Author: Kodiologist

docs/api.rst

@@ -793,7 +793,7 @@ Context managers and pattern-matching
    Python's ``with e1 as _: …``), ``with`` will leave it anonymous (as Python's
    ``with e1: …``).
 
-   Finally, any variable-manager pair may be preceded with the keyword
+   Finally, any variable-manager pair may be preceded by the keyword
    ``:async`` to use an asynchronous context manager::
 
      (with [:async v1 e1] …)
@@ -991,8 +991,8 @@ Functions
    Type parameters require Python 3.12, and have the semantics specified by
    :pep:`695`. The keyword ``:tp`` introduces the list of type parameters. Each
    item of the list is a symbol, an annotated symbol (such as ``#^ int T``), or
-   an unpacked symbol (such as ``#* T`` or ``#** T``). As in Python, unpacking
-   and annotation can't be used with the same parameter.
+   an unpacked symbol (such as ``#* T`` or ``#** T``). As in Python, a single
+   parameter can't be both annotated and unpacked.
 
 .. hy:macro:: (fn [args])
 

docs/syntax.rst

@@ -190,6 +190,12 @@ at compile-time. To prevent a literal keyword from being treated specially in
 an expression, you can :hy:func:`quote` the keyword, or you can use it as the
 value for another keyword argument, as in ``(f :foo :bar)``.
 
+Whereas Python requires all positional arguments in a call to precede all
+keyword arguments, Hy allows them to mingled, as in ``(f 1 :foo 2 3)``. This is
+implemented by simply moving the keyword arguments back, as in ``(f 1 3 :foo
+2)``, with the attendant consequences for order of evaluation (:ref:`which
+shouldn't generally be relied upon in Hy <order-of-eval>`).
+
 Otherwise, keywords are simple model objects that evaluate to themselves. Users
 of other Lisps should note that it's often a better idea to use a string than a
 keyword, because the rest of Python uses strings for cases in which other Lisps
@@ -454,8 +460,12 @@ example, ``{"a" 1 "b" 2}`` produces a dictionary mapping ``"a"`` to ``1`` and
 ``"b"`` to ``2``. Trying to compile a :class:`Dict <hy.models.Dict>` with an
 odd number of child models is an error.
 
-As in Python, calling :class:`dict` with keyword arguments is often more
-convenient than using a literal dictionary.
+As in Python, calling :class:`dict` with keyword arguments may be more
+convenient than using a literal dictionary when all the keys are
+strings. Compare the following alternatives::
+
+    (dict :a 1 :b 2 :c 3 :d 4 :e 5)
+    {"a" 1  "b" 2  "c" 3  "d" 4  "e" 5}
 
 .. autoclass:: hy.models.Dict
 

docs/tutorial.rst

@@ -229,6 +229,17 @@ Set a function parameter by name with a ``:keyword``::
 
     (test 1 2 :d "y")             ; => [1, 2, None, 'y', ()]
 
+Keyword arguments may be placed before or among positional arguments, with the
+same effect as putting all the positional arguments first::
+
+    (test 1 :d "y" 2)             ; => [1, 2, None, 'y', ()]
+
+You can unpack iterable objects into positional arguments with ``#*`` (:hy:func:`unpack-iterable`), or dictionary-like objects into keyword arguments with ``#**`` (:hy:func:`unpack-mapping`)::
+
+    (setv x [1 2 3])
+    (setv y {"d" 4})
+    (test #* x #** y)             ; => [1, 2, 3, 4, ()]
+
 Note that unlike Python, Hy doesn't always evaluate function arguments (or the
 items in a literal list, or the items in a literal dictionary, etc.) :ref:`in
 the order they appear in the code <order-of-eval>`. But you can always force a