Merge pull request #2261 from Kodiologist/dc

Documentation tweaks

CONTRIBUTING.rst

@@ -44,9 +44,6 @@ help you with these finicky things or do them for you if necessary.
 Deciding what to do
 -------------------
 
-Issues tagged good-first-bug_ are expected to be relatively easy to
-fix, so they may be good targets for your first PR for Hy.
-
 If you're proposing a major change to the Hy language, or you're
 unsure of the proposed change, create an issue to discuss it before
 you write any code. This will allow others to give feedback on your
@@ -185,7 +182,6 @@ http://contributor-covenant.org/version/1/1/0/.
 .. _issue tracker: https://github.com/hylang/hy/issues
 .. _GitHub: https://github.com/hylang/hy
 .. _This getting-started guide: http://rogerdudler.github.io/git-guide/
-.. _good-first-bug: https://github.com/hylang/hy/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-bug
 .. _the Github Discussions page: https://github.com/hylang/hy/discussions
 .. _Stack Overflow: https://stackoverflow.com/questions/tagged/hy
 .. _xfail: https://docs.pytest.org/en/latest/skipping.html#mark-a-test-function-as-expected-to-fail

docs/language/internals.rst

@@ -159,12 +159,18 @@ valid numeric python literals will be turned into their Hy counterpart.
 Symbol
 ~~~~~~~~
 
-``hy.models.Symbol`` is the model used to represent symbols in the Hy
-language. Like ``String``, it inherits from ``str`` (or ``unicode`` on Python
-2).
-
-Symbols are :ref:`mangled <mangling>` when they are compiled
-to Python variable names.
+``hy.models.Symbol`` is the model used to represent symbols in the Hy language.
+Like ``String``, it inherits from ``str``.
+
+Literal symbols can be denoted with a single quote, as in ``'cinco``. To
+convert a string to a symbol at run-time (or while expanding a macro), use
+``hy.models.Symbol`` as a constructor, as in ``(hy.models.Symbol "cinco")``.
+Thus, ``hy.models.Symbol`` plays a role similar to the ``intern`` function in
+other Lisps.
+
+Symbols are :ref:`mangled <mangling>` when they are compiled to Python variable
+names, but not before: ``(!= 'a_b 'a-b)`` although ``(= (hy.mangle 'a_b)
+(hy.mangle 'a-b))``.
 
 .. _hykeyword:
 

docs/tutorial.rst

@@ -2,9 +2,11 @@
 Tutorial
 ========
 
-.. image:: _static/cuddles-transparent-small.png
+.. figure:: _static/cuddles-transparent-small.png
    :alt: Karen Rustard's Cuddles
 
+   Hy's mascot, Cuddles the cuttlefish.
+
 This chapter provides a quick introduction to Hy. It assumes a basic background
 in programming, but no specific prior knowledge of Python or Lisp.
 

docs/whyhy.rst

@@ -2,13 +2,16 @@
 Why Hy?
 =======
 
-Hy is a multi-paradigm general-purpose programming language in the `Lisp family
-<https://en.wikipedia.org/wiki/Lisp_(programming_language)>`_. It's implemented
-as a kind of alternative syntax for Python. Compared to Python, Hy offers a
-variety of extra features, generalizations, and syntactic simplifications, as
-would be expected of a Lisp. Compared to other Lisps, Hy provides direct access
-to Python's built-ins and third-party Python libraries, while allowing you to
-freely mix imperative, functional, and object-oriented styles of programming.
+Hy (named after the insect order Hymenoptera, since Paul Tagliamonte
+was studying swarm behavior when he created the language) is a
+multi-paradigm general-purpose programming language in the `Lisp
+family <https://en.wikipedia.org/wiki/Lisp_(programming_language)>`_.
+It's implemented as a kind of alternative syntax for Python. Compared
+to Python, Hy offers a variety of extra features, generalizations, and
+syntactic simplifications, as would be expected of a Lisp. Compared to
+other Lisps, Hy provides direct access to Python's built-ins and
+third-party Python libraries, while allowing you to freely mix
+imperative, functional, and object-oriented styles of programming.
 
 
 Hy versus Python