Merge pull request #2287 from Kodiologist/doc-refine

Documentation refinements

docs/syntax.rst

@@ -10,6 +10,10 @@ turns text into, as when invoked with :hy:func:`hy.read`. The basic units of
 syntax at the textual level are called **forms**, and the basic objects
 representing forms are called **models**.
 
+Following Python, Hy is in general case-sensitive. For example, ``foo`` and
+``FOO`` are different symbols, and the Python-level variables they refer to are
+also different.
+
 .. _models:
 
 An introduction to models
@@ -435,7 +439,6 @@ produced is the same whether you take your code with sugar or without.
 ========================== ================
 Macro                      Syntax
 ========================== ================
-:hy:func:`annotate`        ```^FORM``
 :hy:func:`quasiquote`      ```FORM``
 :hy:func:`quote`           ``'FORM``
 :hy:func:`unpack-iterable` ``#* FORM``

docs/tutorial.rst

@@ -364,3 +364,9 @@ sneak off to your Hydeaway to do unspeakable things.
 Refer to Python's documentation for the details of Python semantics, and the
 rest of this manual for Hy-specific features. Like Hy itself, the manual is
 incomplete, but :ref:`contributions <hacking>` are always welcome.
+
+Bear in mind that Hy is still unstable, and with each release along the
+way to Hy 1.0, there are new breaking changes. Refer to `the NEWS file
+<https://github.com/hylang/hy/blob/master/NEWS.rst>`_ for how to update your
+code when you upgrade Hy, and be sure you're reading the version of this manual
+(shown at the top of each page) that matches the version of Hy you're running.

hy/models.py

@@ -294,7 +294,9 @@ def __bool__(self):
 
     def __call__(self, data, default=_sentinel):
         """Get the element of ``data`` named ``(hy.mangle self.name)``. Thus, ``(:foo
-        bar)`` is equivalent to ``(get bar (hy.mangle "foo"))``.
+        bar)`` is equivalent to ``(get bar "foo")`` (which is different from
+        ``(get bar :foo)``; dictionary keys are typically strings, not
+        :class:`hy.models.Keyword` objects).
 
         The optional second parameter is a default value; if provided, any
         :class:`KeyError` from :hy:func:`get` will be caught, and the default returned