Adhere to CPython's documentation guidelines

- Inline code is written using ``double backticks``
- Italicized text uses *asterisks* rather than `single backticks`
- Function parameters are italicized rather than written as inline code

docs/contrib/anaphoric.rst

@@ -24,8 +24,8 @@ ap-if
 
 Usage: ``(ap-if (foo) (print it))``
 
-Evaluate the first form for trutheyness, and bind it to ``it`` in both the
+Evaluates the first form for truthiness, and bind it to ``it`` in both the
-true and false branch.
+true and false branches.
 
 
 .. _ap-each:
@@ -46,7 +46,7 @@ ap-each-while
 Usage: ``(ap-each-while list pred body)``
 
 Evaluate the form for each element where the predicate form returns
-`True`.
+``True``.
 
 .. code-block:: hy
 

docs/contrib/loop.rst

@@ -4,8 +4,8 @@ loop/recur
 
 .. versionadded:: 0.10.0
 
-The loop/recur macro gives programmers a simple way to use tail-call
+The ``loop`` / ``recur`` macro gives programmers a simple way to use
-optimization (TCO) in their Hy code.
+tail-call optimization (TCO) in their Hy code.
 
     A tail call is a subroutine call that happens inside another
     procedure as its final action; it may produce a return value which

docs/contrib/multi.rst

@@ -4,8 +4,8 @@ defmulti
 
 .. versionadded:: 0.10.0
 
-`defmulti` lets you arity-overload a function by the given number of
+``defmulti`` lets you arity-overload a function by the given number of
-args and/or kwargs. Inspired by Clojure's take on `defn`.
+args and/or kwargs. Inspired by Clojure's take on ``defn``.
 
 .. code-block:: clj
 

docs/language/api.rst

@@ -2,7 +2,6 @@
 Hy (the language)
 =================
 
-
 .. warning::
     This is incomplete; please consider contributing to the documentation
     effort.
@@ -15,21 +14,21 @@ Hy maintains, over everything else, 100% compatibility in both directions
 with Python itself. All Hy code follows a few simple rules. Memorize
 this, as it's going to come in handy.
 
-These rules help ensure that Hy code is idiomatic and interface-able in both
+These rules help ensure that Hy code is idiomatic and interfaceable in both
 languages.
 
 
   * Symbols in earmufs will be translated to the upper-cased version of that
-    string. For example, `foo` will become `FOO`.
+    string. For example, ``foo`` will become ``FOO``.
 
   * UTF-8 entities will be encoded using
     `punycode <http://en.wikipedia.org/wiki/Punycode>`_ and prefixed with
-    `hy_`. For instance, `⚘` will become `hy_w7h`, `♥` will become `hy_g6h`,
+    ``hy_``. For instance, ``⚘`` will become ``hy_w7h``, ``♥`` will become
-    and `i♥u` will become `hy_iu_t0x`.
+    ``hy_g6h``, and ``i♥u`` will become ``hy_iu_t0x``.
 
   * Symbols that contain dashes will have them replaced with underscores. For
-    example, `render-template` will become `render_template`. This means that
+    example, ``render-template`` will become ``render_template``. This means
-    symbols with dashes will shadow their underscore equivalents, and vice
+    that symbols with dashes will shadow their underscore equivalents, and vice
     versa.
 
 
@@ -45,8 +44,7 @@ behavior that's slightly unexpected in some situations.
 
 .. versionadded:: 0.10.0
 
-
+``.`` is used to perform attribute access on objects. It uses a small DSL
-`.` is used to perform attribute access on objects. It uses a small DSL
 to allow quick access to attributes and items in a nested data structure.
 
 For instance,
@@ -55,17 +53,17 @@ For instance,
 
     (. foo bar baz [(+ 1 2)] frob)
 
-Compiles down to
+Compiles down to:
 
 .. code-block:: python
 
      foo.bar.baz[1 + 2].frob
 
-`.` compiles its first argument (in the example, `foo`) as the object on
+``.`` compiles its first argument (in the example, *foo*) as the object on
-which to do the attribute dereference. It uses bare symbols as
+which to do the attribute dereference. It uses bare symbols as attributes
-attributes to access (in the example, `bar`, `baz`, `frob`), and
+to access (in the example, *bar*, *baz*, *frob*), and compiles the contents
-compiles the contents of lists (in the example, ``[(+ 1 2)]``) for
+of lists (in the example, ``[(+ 1 2)]``) for indexation. Other arguments
-indexation. Other arguments throw a compilation error.
+throw a compilation error.
 
 Access to unknown attributes throws an :exc:`AttributeError`. Access to
 unknown keys throws an :exc:`IndexError` (on lists and tuples) or a
@@ -74,9 +72,9 @@ unknown keys throws an :exc:`IndexError` (on lists and tuples) or a
 ->
 --
 
-`->` or `threading macro` is used to avoid nesting of expressions. The threading
+``->`` (or the *threading macro*) is used to avoid nesting of expressions. The
-macro inserts each expression into the next expression’s first argument place.
+threading macro inserts each expression into the next expression's first argument
-The following code demonstrates this:
+place. The following code demonstrates this:
 
 .. code-block:: clj
 
@@ -88,9 +86,9 @@ The following code demonstrates this:
 ->>
 ---
 
-`->>` or `threading tail macro` is similar to `threading macro` but instead of
+``->>`` (or the *threading tail macro*) is similar to the *threading macro*, but
-inserting each expression into the next expression’s first argument, it
+instead of inserting each expression into the next expression's first argument,
-appends it as the last argument. The following code demonstrates this:
+it appends it as the last argument. The following code demonstrates this:
 
 .. code-block:: clj
 
@@ -102,10 +100,10 @@ appends it as the last argument. The following code demonstrates this:
 apply
 -----
 
-`apply` is used to apply an optional list of arguments and an optional
+``apply`` is used to apply an optional list of arguments and an optional
 dictionary of kwargs to a function.
 
-Usage: `(apply fn-name [args] [kwargs])`
+Usage: ``(apply fn-name [args] [kwargs])``
 
 Examples:
 
@@ -133,9 +131,9 @@ Examples:
 and
 ---
 
-`and` is used in logical expressions. It takes at least two parameters. If all
+``and`` is used in logical expressions. It takes at least two parameters. If
-parameters evaluate to `True`, the last parameter is returned. In any other
+all parameters evaluate to ``True``, the last parameter is returned. In any
-case, the first false value will be returned. Example usage:
+other case, the first false value will be returned. Example usage:
 
 .. code-block:: clj
 
@@ -153,7 +151,7 @@ case, the first false value will be returned. Example usage:
 
 .. note::
 
-    `and` shortcuts and stops evaluating parameters as soon as the first
+    ``and`` short-circuits and stops evaluating parameters as soon as the first
     false is encountered.
 
 .. code-block:: clj
@@ -165,24 +163,24 @@ case, the first false value will be returned. Example usage:
 assert
 ------
 
-`assert` is used to verify conditions while the program is running. If the
+``assert`` is used to verify conditions while the program is running. If the
-condition is not met, an `AssertionError` is raised. The example usage:
+condition is not met, an ``AssertionError`` is raised. Example usage:
 
 .. code-block:: clj
 
     (assert (= variable expected-value))
 
-Assert takes a single parameter, a conditional that evaluates to either `True`
+``assert`` takes a single parameter, a conditional that evaluates to either
-or `False`.
+``True`` or ``False``.
 
 
 assoc
 -----
 
-`assoc` is used to associate a key with a value in a dictionary or to set an
+``assoc`` is used to associate a key with a value in a dictionary or to set an
-index of a list to a value. It takes at least three parameters: the `data
+index of a list to a value. It takes at least three parameters: the *data
-structure` to be modified, `key` or `index`  and `value`. If more than three
+structure* to be modified, a *key* or *index*, and a *value*. If more than
-parameters are used, it will associate in pairs.
+three parameters are used, it will associate in pairs.
 
 Examples of usage:
 
@@ -203,15 +201,15 @@ Examples of usage:
   ... (print collection))
   [1, 2, None, 4]
 
-.. note:: `assoc` modifies the datastructure in place and returns `None`.
+.. note:: ``assoc`` modifies the datastructure in place and returns ``None``.
 
 
 break
 -----
 
-`break` is used to break out from a loop. It terminates the loop immediately.
+``break`` is used to break out from a loop. It terminates the loop immediately.
-The following example has an infinite `while` loop that is terminated as soon
+The following example has an infinite ``while`` loop that is terminated as soon
-as the user enters `k`.
+as the user enters *k*.
 
 .. code-block:: clj
 
@@ -223,8 +221,8 @@ as the user enters `k`.
 cond
 ----
 
-`cond` can be used to build nested if-statements. The following example shows
+``cond`` can be used to build nested ``if`` statements. The following example
-the relationship between the macro and the expanded code:
+shows the relationship between the macro and its expansion:
 
 .. code-block:: clj
 
@@ -234,7 +232,7 @@ the relationship between the macro and the expanded code:
     (if condition-1 result-1
       (if condition-2 result-2))
 
-As shown below only the first matching result block is executed.
+As shown below, only the first matching result block is executed.
 
 .. code-block:: clj
 
@@ -251,9 +249,9 @@ As shown below only the first matching result block is executed.
 continue
 --------
 
-`continue` returns execution to the start of a loop. In the following example,
+``continue`` returns execution to the start of a loop. In the following example,
-function `(side-effect1)` is called for each iteration. `(side-effect2)`
+``(side-effect1)`` is called for each iteration. ``(side-effect2)``, however,
-however is called only for every other value in the list.
+is only called on every other value in the list.
 
 .. code-block:: clj
 
@@ -271,11 +269,11 @@ however is called only for every other value in the list.
 dict-comp
 ---------
 
-`dict-comp` is used to create dictionaries. It takes three or four parameters.
+``dict-comp`` is used to create dictionaries. It takes three or four parameters.
-The first two parameters are for controlling the return value
+The first two parameters are for controlling the return value (key-value pair)
-(key-value pair), while the third is used to select items from a sequence. The
+while the third is used to select items from a sequence. The fourth and optional
-fourth and optional parameter can be used to filter out some of the items in
+parameter can be used to filter out some of the items in the sequence based on a
-the sequence based on a conditional expression.
+conditional expression.
 
 .. code-block:: hy
 
@@ -286,10 +284,10 @@ the sequence based on a conditional expression.
 do / progn
 ----------
 
-`do` and `progn` are used to evaluate each of their arguments and return the last
+``do`` and `progn` are used to evaluate each of their arguments and return the
-one. Return values from every other than the last argument are discarded. It can be
+last one. Return values from every other than the last argument are discarded.
-used in `lambda` or `list-comp` to perform more complex logic as shown by one of the
+It can be used in ``lambda`` or ``list-comp`` to perform more complex logic as
-examples.
+shown in one of the following examples.
 
 Some example usage:
 
@@ -309,14 +307,14 @@ Some example usage:
     ...           (x (range 10)))
     [0, 2, 4, 6, 8, 20, 24, 28, 32, 36]
 
-`do` can accept any number of arguments, from 1 to n.
+``do`` can accept any number of arguments, from 1 to n.
 
 
 def / setv
 ----------
 
-`def` and `setv` are used to bind a value, object, or function to a symbol. For
+``def`` and ``setv`` are used to bind a value, object, or function to a symbol.
-example:
+For example:
 
 .. code-block:: clj
 
@@ -332,7 +330,7 @@ example:
 defclass
 --------
 
-New classes are declared with `defclass`. It can takes two optional parameters:
+New classes are declared with ``defclass``. It can takes two optional parameters:
 a vector defining a possible super classes and another vector containing
 attributes of the new class as two item vectors.
 
@@ -363,9 +361,9 @@ below:
 defn / defun
 ------------
 
-`defn` and `defun` macros are used to define functions. They take three
+``defn`` and ``defun`` macros are used to define functions. They take three
-parameters: the `name` of the function to define, a vector of `parameters`,
+parameters: the *name* of the function to define, a vector of *parameters*,
-and the `body` of the function:
+and the *body* of the function:
 
 .. code-block:: clj
 
@@ -377,7 +375,7 @@ Parameters may have the following keywords in front of them:
     Parameter is optional. The parameter can be given as a two item list, where
     the first element is parameter name and the second is the default value. The
     parameter can be also given as a single item, in which case the default
-    value is None.
+    value is ``None``.
 
     .. code-block:: clj
 
@@ -437,12 +435,11 @@ defn-alias / defun-alias
 
 .. versionadded:: 0.10.0
 
-The `defn-alias` and `defun-alias` macros are much like `defn`_ above,
+The ``defn-alias`` and ``defun-alias`` macros are much like `defn`_,
-with the difference that instead of defining a function with a single
+with the distinction that instead of defining a function with a single
 name, these can also define aliases. Other than taking a list of
-symbols for function names as the first parameter, `defn-alias` and
+symbols for function names as the first parameter, ``defn-alias`` and
-`defun-alias` have no other differences compared to `defn` and
+``defun-alias`` are no different from ``defn`` and ``defun``.
-`defun`.
 
 .. code-block:: clj
 
@@ -459,7 +456,7 @@ defmain
 
 .. versionadded:: 0.10.1
 
-The `defmain` macro defines a main function that is immediately called
+The ``defmain`` macro defines a main function that is immediately called
 with ``sys.argv`` as arguments if and only if this file is being executed
 as a script.  In other words, this:
 
@@ -486,9 +483,9 @@ function, this will be used as the exit status for your script.
 (Python defaults to exit status 0 otherwise, which means everything's
 okay!)
 
-(Since (sys.exit 0) is not run explicitly in case of a non-integer
+(Since ``(sys.exit 0)`` is not run explicitly in the case of a non-integer
-return from defmain, it's good to put (defmain) as the last bit of
+return from ``defmain``, it's a good idea to put ``(defmain)`` as the last
-code in your file.)
+piece of code in your file.)
 
 
 .. _defmacro:
@@ -496,11 +493,11 @@ code in your file.)
 defmacro
 --------
 
-`defmacro` is used to define macros. The general format is
+``defmacro`` is used to define macros. The general format is
-`(defmacro name [parameters] expr)`.
+``(defmacro name [parameters] expr)``.
 
-The following example defines a macro that can be used to swap order of elements in
+The following example defines a macro that can be used to swap order of elements
-code, allowing the user to write code in infix notation, where operator is in
+in code, allowing the user to write code in infix notation, where operator is in
 between the operands.
 
 .. code-block:: clj
@@ -519,9 +516,9 @@ between the operands.
 defmacro-alias
 --------------
 
-`defmacro-alias` is used to define macros with multiple names
+``defmacro-alias`` is used to define macros with multiple names
-(aliases). The general format is `(defmacro-alias [names] [parameters]
+(aliases). The general format is ``(defmacro-alias [names] [parameters]
-expr)`. It creates multiple macros with the same parameter list and
+expr)``. It creates multiple macros with the same parameter list and
 body, under the specified list of names.
 
 The following example defines two macros, both of which allow the user
@@ -547,11 +544,11 @@ defmacro/g!
 
 .. versionadded:: 0.9.12
 
-`defmacro/g!` is a special version of `defmacro` that is used to
+``defmacro/g!`` is a special version of ``defmacro`` that is used to
-automatically generate :ref:`gensym` for any symbol that
+automatically generate :ref:`gensym` for any symbol that starts with
-starts with ``g!``.
+``g!``.
 
-So ``g!a`` would become ``(gensym "a")``.
+For example, ``g!a`` would become ``(gensym "a")``.
 
 .. seealso::
 
@@ -562,7 +559,7 @@ defreader
 
 .. versionadded:: 0.9.12
 
-`defreader` defines a reader macro, enabling you to restructure or
+``defreader`` defines a reader macro, enabling you to restructure or
 modify syntax.
 
 .. code-block:: clj
@@ -582,7 +579,7 @@ del
 
 .. versionadded:: 0.9.12
 
-`del` removes an object from the current namespace.
+``del`` removes an object from the current namespace.
 
 .. code-block:: clj
 
@@ -593,7 +590,7 @@ del
     File "<console>", line 1, in <module>
   NameError: name 'foo' is not defined
 
-`del` can also remove objects from mappings, lists, and more.
+``del`` can also remove objects from mappings, lists, and more.
 
 .. code-block:: clj
 
@@ -615,7 +612,7 @@ doto
 
 .. versionadded:: 0.10.1
 
-`doto` macro is used to simplify a sequence of method calls to an object.
+``doto`` is used to simplify a sequence of method calls to an object.
 
 .. code-block:: clj
 
@@ -634,7 +631,7 @@ doto
 eval
 ----
 
-`eval` evaluates a quoted expression and returns the value.
+``eval`` evaluates a quoted expression and returns the value.
 
 .. code-block:: clj
 
@@ -652,7 +649,7 @@ eval-when-compile
 first / car
 -----------
 
-`first` and `car` are macros for accessing the first element of a collection:
+``first`` and ``car`` are macros for accessing the first element of a collection:
 
 .. code-block:: clj
 
@@ -663,11 +660,11 @@ first / car
 for
 ---
 
-`for` is used to call a function for each element in a list or vector.
+``for`` is used to call a function for each element in a list or vector.
-The results of each call are discarded and the for expression returns
+The results of each call are discarded and the ``for`` expression returns
-`None` instead. The example code iterates over `collection` and
+``None`` instead. The example code iterates over *collection* and for each
-for each `element` in `collection` calls the `side-effect`
+*element* in *collection* calls the ``side-effect`` function with *element*
-function with `element` as its argument:
+as its argument:
 
 .. code-block:: clj
 
@@ -678,8 +675,9 @@ function with `element` as its argument:
     (for [element collection] (side-effect element)
          (else (side-effect-2)))
 
-The optional `else` block is executed only if the `for` loop terminates
+The optional ``else`` block is only executed if the ``for`` loop terminates
-normally. If the execution is halted with `break`, the `else` does not execute.
+normally. If the execution is halted with ``break``, the ``else`` block does
+not execute.
 
 .. code-block:: clj
 
@@ -703,12 +701,13 @@ normally. If the execution is halted with `break`, the `else` does not execute.
 genexpr
 -------
 
-`genexpr` is used to create generator expressions. It takes two or three parameters.
+``genexpr`` is used to create generator expressions. It takes two or three
-The first parameter is the expression controlling the return value, while
+parameters. The first parameter is the expression controlling the return value,
-the second is used to select items from a list. The third and optional
+while the second is used to select items from a list. The third and optional
 parameter can be used to filter out some of the items in the list based on a
-conditional expression. `genexpr` is similar to `list-comp`, except that it returns
+conditional expression. ``genexpr`` is similar to ``list-comp``, except it
-an iterable that evaluates values one by one instead of evaluating them immediately.
+returns an iterable that evaluates values one by one instead of evaluating them
+immediately.
 
 .. code-block:: hy
 
@@ -725,8 +724,8 @@ gensym
 
 .. versionadded:: 0.9.12
 
-`gensym` is used to generate a unique symbol to allow writing macros
+``gensym`` is used to generate a unique symbol that allows macros to be
-without accidental variable name clashes.
+written without accidental variable name clashes.
 
 .. code-block:: clj
 
@@ -743,10 +742,10 @@ without accidental variable name clashes.
 get
 ---
 
-`get` is used to access single elements in lists and dictionaries. `get` takes
+``get`` is used to access single elements in lists and dictionaries. ``get``
-two parameters: the `data structure` and the `index` or `key` of the item.
+takes two parameters: the *data structure* and the *index* or *key* of the
-It will then return the corresponding value from the dictionary or the list.
+item. It will then return the corresponding value from the dictionary or the
-Example usage:
+list. Example usage:
 
 .. code-block:: clj
 
@@ -757,23 +756,23 @@ Example usage:
    bark
    two
 
-.. note:: `get` raises a KeyError if a dictionary is queried for a non-existing
+.. note:: ``get`` raises a KeyError if a dictionary is queried for a
-          key.
+          non-existing key.
 
-.. note:: `get` raises an IndexError if a list or a tuple is queried for an index
+.. note:: ``get`` raises an IndexError if a list or a tuple is queried for an
-          that is out of bounds.
+          index that is out of bounds.
 
 
 global
 ------
 
-`global` can be used to mark a symbol as global. This allows the programmer to
+``global`` can be used to mark a symbol as global. This allows the programmer to
 assign a value to a global symbol. Reading a global symbol does not require the
-`global` keyword -- only assigning it does.
+``global`` keyword -- only assigning it does.
 
-The following example shows how the global symbol `a` is assigned a value in a
+The following example shows how the global symbol ``a`` is assigned a value in a
-function and is later on printed in another function. Without the `global` keyword,
+function and is later on printed in another function. Without the ``global``
-the second function would have thrown a `NameError`.
+keyword, the second function would have thrown a ``NameError``.
 
 .. code-block:: clj
 
@@ -793,13 +792,14 @@ if / if-not
 .. versionadded:: 0.10.0
    if-not
 
-`if` is used to conditionally select code to be executed. It has to contain a
+``if`` is used to conditionally select code to be executed. It has to contain a
 condition block and the block to be executed if the condition block evaluates
-to `True`. Optionally, it may contain a final block that is executed in case
+to ``True``. Optionally, it may contain a final block that is executed in case
-the evaluation of the condition is `False`. The `if-not` form is similar, but
+the evaluation of the condition is ``False``.
-the second block will be executed when the condition fails while the third and
+
-final block is executed when the test succeeds -- the opposite order of the `if`
+``if-not`` is similar, but the second block will be executed when the condition
-form.
+fails while the third and final block is executed when the test succeeds -- the
+opposite order of ``if``.
 
 Example usage:
 
@@ -813,9 +813,9 @@ Example usage:
       (print "let's go and work")
       (print "let's go shopping"))
 
-Truth values of Python objects are respected. `None`, `False`, zero of any numeric
+Python truthiness is respected. ``None``, ``False``, zero of any numeric type,
-type, an empty sequence, and an empty dictionary are considered `False`. Everything else
+an empty sequence, and an empty dictionary are considered ``False``; everything
-is considered `True`.
+else is considered ``True``.
 
 
 lisp-if / lif and lisp-if-not / lif-not
@@ -826,10 +826,11 @@ lisp-if / lif and lisp-if-not / lif-not
 .. versionadded:: 0.10.2
    lisp-if-not / lif-not
 
-For those that prefer a more Lispy `if` clause, we have `lisp-if`, or `lif`.  This
+For those that prefer a more Lispy ``if`` clause, we have ``lisp-if``, or
-*only* considers `None`/`nil` as false!  All other "false-ish" Python values are
+``lif``. This *only* considers ``None`` / ``nil`` to be false! All other
-considered true.  Conversely, we have `lisp-if-not` and `lif-not` in parallel to
+"false-ish" Python values are considered true. Conversely, we have
-`if` and `if-not` which reverses the comparison.
+``lisp-if-not`` and ``lif-not`` in parallel to ``if`` and ``if-not`` which
+reverses the comparison.
 
 
 .. code-block:: clj
@@ -863,8 +864,8 @@ considered true.  Conversely, we have `lisp-if-not` and `lif-not` in parallel to
 import
 ------
 
-`import` is used to import modules, like in Python. There are several forms
+``import`` is used to import modules, like in Python. There are several ways
-of import you can use.
+that ``import`` can be used.
 
 .. code-block:: clj
 
@@ -897,9 +898,9 @@ of import you can use.
 lambda / fn
 -----------
 
-`lambda` and `fn` can be used to define an anonymous function. The parameters are
+``lambda`` and ``fn`` can be used to define an anonymous function. The parameters are
-similar to `defn`: the first parameter is vector of parameters and the rest is the
+similar to ``defn``: the first parameter is vector of parameters and the rest is the
-body of the function. `lambda` returns a new function. In the following example, an
+body of the function. ``lambda`` returns a new function. In the following example, an
 anonymous function is defined and passed to another function for filtering output.
 
 .. code-block:: clj
@@ -917,7 +918,7 @@ anonymous function is defined and passed to another function for filtering outpu
     Dave
 
 Just as in normal function definitions, if the first element of the
-body is a string, it serves as docstring.  This is useful for giving
+body is a string, it serves as a docstring. This is useful for giving
 class methods docstrings.
 
 .. code-block:: clj
@@ -940,8 +941,8 @@ This can be confirmed via Python's built-in ``help`` function::
 let
 ---
 
-`let` is used to create lexically scoped variables. They are created at the
+``let`` is used to create lexically scoped variables. They are created at the
-beginning of the `let` form and cease to exist after the form. The following
+beginning of the ``let`` form and cease to exist after the form. The following
 example showcases this behaviour:
 
 .. code-block:: clj
@@ -953,10 +954,10 @@ example showcases this behaviour:
     6
     5
 
-The `let` macro takes two parameters: a vector defining `variables` and the
+The ``let`` macro takes two parameters: a vector defining *variables* and the
-`body` which gets executed. `variables` is a vector where each element is either
+*body* which gets executed. *variables* is a vector where each element is either
 a single variable or a vector defining a variable value pair. In the case of a
-single variable, it is assigned value `None`; otherwise, the supplied value is
+single variable, it is assigned value ``None``; otherwise, the supplied value is
 used.
 
 .. code-block:: clj
@@ -968,7 +969,7 @@ used.
 list-comp
 ---------
 
-`list-comp` performs list comprehensions. It takes two or three parameters.
+``list-comp`` performs list comprehensions. It takes two or three parameters.
 The first parameter is the expression controlling the return value, while
 the second is used to select items from a list. The third and optional
 parameter can be used to filter out some of the items in the list based on a
@@ -990,9 +991,9 @@ conditional expression. Some examples:
 not
 ---
 
-`not` is used in logical expressions. It takes a single parameter and
+``not`` is used in logical expressions. It takes a single parameter and
-returns a reversed truth value. If `True` is given as a parameter, `False`
+returns a reversed truth value. If ``True`` is given as a parameter, ``False``
-will be returned and vice-versa. Example usage:
+will be returned, and vice-versa. Example usage:
 
 .. code-block:: clj
 
@@ -1009,8 +1010,8 @@ will be returned and vice-versa. Example usage:
 or
 --
 
-`or` is used in logical expressions. It takes at least two parameters. It will
+``or`` is used in logical expressions. It takes at least two parameters. It
-return the first non-false parameter. If no such value exists, the last
+will return the first non-false parameter. If no such value exists, the last
 parameter will be returned.
 
 .. code-block:: clj
@@ -1024,7 +1025,7 @@ parameter will be returned.
     => (and False 1 True False)
     1
 
-.. note:: `or` short-circuits and stops evaluating parameters as soon as the
+.. note:: ``or`` short-circuits and stops evaluating parameters as soon as the
           first true value is encountered.
 
 .. code-block:: clj
@@ -1036,24 +1037,23 @@ parameter will be returned.
 print
 -----
 
-`print` is used to output on screen. Example usage:
+``print`` is used to output on screen. Example usage:
 
 .. code-block:: clj
 
     (print "Hello world!")
 
-.. note:: `print` always returns None
+.. note:: ``print`` always returns ``None``.
 
 
 quasiquote
 ----------
 
-`quasiquote` allows you to quote a form, but also selectively evaluate
+``quasiquote`` allows you to quote a form, but also selectively evaluate
-expressions. Expressions inside a `quasiquote` can be selectively evaluated
+expressions. Expressions inside a ``quasiquote`` can be selectively evaluated
-using `unquote` (~). The evaluated form can also be spliced using
+using ``unquote`` (``~``). The evaluated form can also be spliced using
-`unquote-splice` (~@). Quasiquote can be also written using the backquote (`)
+``unquote-splice`` (``~@``). Quasiquote can be also written using the backquote
-symbol.
+(`````) symbol.
-
 
 .. code-block:: clj
 
@@ -1067,9 +1067,8 @@ symbol.
 quote
 -----
 
-`quote` returns the form passed to it without evaluating it. `quote` can
+``quote`` returns the form passed to it without evaluating it. ``quote`` can
-be alternatively written using the (') symbol
+alternatively be written using the apostrophe (``'``) symbol.
-
 
 .. code-block:: clj
 
@@ -1084,11 +1083,11 @@ be alternatively written using the (') symbol
 require
 -------
 
-`require` is used to import macros from a given module. It takes at least one
+``require`` is used to import macros from a given module. It takes at least one
 parameter specifying the module which macros should be imported. Multiple
-modules can be imported with a single `require`.
+modules can be imported with a single ``require``.
 
-The following example will import macros from `module-1` and `module-2`:
+The following example will import macros from ``module-1`` and ``module-2``:
 
 .. code-block:: clj
 
@@ -1098,8 +1097,8 @@ The following example will import macros from `module-1` and `module-2`:
 rest / cdr
 ----------
 
-`rest` and `cdr` return the collection passed as an argument without the first
+``rest`` and ``cdr`` return the collection passed as an argument without the
-element:
+first element:
 
 .. code-block:: clj
 
@@ -1110,7 +1109,7 @@ element:
 set-comp
 --------
 
-`set-comp` is used to create sets. It takes two or three parameters.
+``set-comp`` is used to create sets. It takes two or three parameters.
 The first parameter is for controlling the return value, while the second is
 used to select items from a sequence. The third and optional parameter can be
 used to filter out some of the items in the sequence based on a conditional
@@ -1126,13 +1125,13 @@ expression.
 slice
 -----
 
-`slice` can be used to take a subset of a list and create a new list from it.
+``slice`` can be used to take a subset of a list and create a new list from it.
 The form takes at least one parameter specifying the list to slice. Two
 optional parameters can be used to give the start and end position of the
-subset. If they are not supplied, default value of `None` will be used instead.
+subset. If they are not supplied, the default value of ``None`` will be used
-The third optional parameter is used to control step between the elements.
+instead. The third optional parameter is used to control step between the elements.
 
-`slice` follows the same rules as its Python counterpart. Negative indices are
+``slice`` follows the same rules as its Python counterpart. Negative indices are
 counted starting from the end of the list. Some example usage:
 
 .. code-block:: clj
@@ -1158,8 +1157,8 @@ counted starting from the end of the list. Some example usage:
 throw / raise
 -------------
 
-The `throw` or `raise` forms can be used to raise an `Exception` at runtime.
+The ``throw`` or ``raise`` forms can be used to raise an ``Exception`` at
-Example usage:
+runtime. Example usage:
 
 .. code-block:: clj
 
@@ -1173,15 +1172,15 @@ Example usage:
     ; Throw an IOError("foobar")
 
 
-`throw` can accept a single argument (an `Exception` class or instance) or
+``throw`` can accept a single argument (an ``Exception`` class or instance)
-no arguments to re-raise the last `Exception`.
+or no arguments to re-raise the last ``Exception``.
 
 
 try
 ---
 
-The `try` form is used to start a `try` / `catch` block. The form is used
+The ``try`` form is used to start a ``try`` / ``catch`` block. The form is
-as follows:
+used as follows:
 
 .. code-block:: clj
 
@@ -1191,19 +1190,19 @@ as follows:
         (else (print "no errors"))
         (finally (print "all done")))
 
-`try` must contain at least one `catch` block, and may optionally have an
+``try`` must contain at least one ``catch`` block, and may optionally include
-`else` or `finally` block. If an error is raised with a matching catch
+an ``else`` or ``finally`` block. If an error is raised with a matching catch
-block during execution of `error-prone-function`, that catch block will
+block during the execution of ``error-prone-function``, that ``catch`` block
-be executed. If no errors are raised, the `else` block is executed. The
+will be executed. If no errors are raised, the ``else`` block is executed. The
-`finally` block will be executed last, regardless of whether or not an error
+``finally`` block will be executed last regardless of whether or not an error
 was raised.
 
 
 unless
 ------
 
-The `unless` macro is a shorthand for writing an `if` statement that checks if the
+The ``unless`` macro is a shorthand for writing an ``if`` statement that checks if
-given conditional is `False`. The following shows the expansion of this macro.
+the given conditional is ``False``. The following shows the expansion of this macro.
 
 .. code-block:: clj
 
@@ -1217,8 +1216,8 @@ given conditional is `False`. The following shows the expansion of this macro.
 unquote
 -------
 
-Within a quasiquoted form, `unquote` forces evaluation of a symbol. `unquote`
+Within a quasiquoted form, ``unquote`` forces evaluation of a symbol. ``unquote``
-is aliased to the `~` symbol.
+is aliased to the tilde (``~``) symbol.
 
 .. code-block:: clj
 
@@ -1233,10 +1232,10 @@ is aliased to the `~` symbol.
 unquote-splice
 --------------
 
-`unquote-splice` forces the evaluation of a symbol within a quasiquoted form,
+``unquote-splice`` forces the evaluation of a symbol within a quasiquoted form,
-much like `unquote`. `unquote-splice` can only be used when the symbol being
+much like ``unquote``. ``unquote-splice`` can only be used when the symbol
-unquoted contains an iterable value, as it "splices" that iterable into the
+being unquoted contains an iterable value, as it "splices" that iterable into
-quasiquoted form. `unquote-splice` is aliased to the `~@` symbol.
+the quasiquoted form. ``unquote-splice`` is aliased to the ``~@`` symbol.
 
 .. code-block:: clj
 
@@ -1248,13 +1247,12 @@ quasiquoted form. `unquote-splice` is aliased to the `~@` symbol.
     ;=> (u'+' 1L 2L 3L 4L)
 
 
-
 when
 ----
 
-`when` is similar to `unless`, except it tests when the given conditional is
+``when`` is similar to ``unless``, except it tests when the given conditional is
-`True`. It is not possible to have an `else` block in a `when` macro. The following
+``True``. It is not possible to have an ``else`` block in a ``when`` macro. The
-shows the expansion of the macro.
+following shows the expansion of the macro.
 
 .. code-block:: clj
 
@@ -1262,24 +1260,25 @@ shows the expansion of the macro.
 
     (if conditional (do statement))
 
+
 while
 -----
 
-`while` is used to execute one or more blocks as long as a condition is met.
+``while`` is used to execute one or more blocks as long as a condition is met.
-The following example will output "hello world!" to the screen indefinitely:
+The following example will output "Hello world!" to the screen indefinitely:
 
 .. code-block:: clj
 
-    (while True (print "hello world!"))
+    (while True (print "Hello world!"))
 
 
 with
 ----
 
-`with` is used to wrap the execution of a block within a context manager. The
+``with`` is used to wrap the execution of a block within a context manager. The
 context manager can then set up the local system and tear it down in a controlled
-manner. The archetypical example of using `with` is when processing files. `with`
+manner. The archetypical example of using ``with`` is when processing files.
-can bind context to an argument or ignore it completely, as shown below:
+``with`` can bind context to an argument or ignore it completely, as shown below:
 
 .. code-block:: clj
 
@@ -1289,8 +1288,8 @@ can bind context to an argument or ignore it completely, as shown below:
 
     (with [[arg (expr)] [(expr)]] block)
 
-The following example will open file `NEWS` and print its content on screen. The
+The following example will open the ``NEWS`` file and print its content to the
-file is automatically closed after it has been processed.
+screen. The file is automatically closed after it has been processed.
 
 .. code-block:: clj
 
@@ -1300,9 +1299,9 @@ file is automatically closed after it has been processed.
 with-decorator
 --------------
 
-`with-decorator` is used to wrap a function with another. The function
+``with-decorator`` is used to wrap a function with another. The function
 performing the decoration should accept a single value: the function being
-decorated, and return a new function. `with-decorator` takes a minimum
+decorated, and return a new function. ``with-decorator`` takes a minimum
 of two parameters: the function performing decoration and the function
 being decorated. More than one decorator function can be applied; they
 will be applied in order from outermost to innermost, ie. the first
@@ -1321,11 +1320,11 @@ are called just like a function call.
       (defn some-function [] ...)
 
 
-In the following example, `inc-decorator` is used to decorate the function
+In the following example, ``inc-decorator`` is used to decorate the function
-`addition` with a function that takes two parameters and calls the
+``addition`` with a function that takes two parameters and calls the
 decorated function with values that are incremented by 1. When
-the decorated `addition` is called with values 1 and 1, the end result
+the decorated ``addition`` is called with values 1 and 1, the end result
-will be 4 (1+1 + 1+1).
+will be 4 (``1+1 + 1+1``).
 
 .. code-block:: clj
 
@@ -1350,7 +1349,8 @@ with-gensyms
 
 .. versionadded:: 0.9.12
 
-`with-gensym` is used to generate a set of :ref:`gensym` for use in a macro.
+``with-gensym`` is used to generate a set of :ref:`gensym` for use in a macro.
+The following code:
 
 .. code-block:: hy
 
@@ -1374,11 +1374,11 @@ expands to:
 yield
 -----
 
-`yield` is used to create a generator object that returns one or more values.
+``yield`` is used to create a generator object that returns one or more values.
 The generator is iterable and therefore can be used in loops, list
 comprehensions and other similar constructs.
 
-The function `random-numbers` shows how generators can be used to generate
+The function ``random-numbers`` shows how generators can be used to generate
 infinite series without consuming infinite amount of memory.
 
 .. code-block:: clj
@@ -1407,7 +1407,7 @@ yield-from
 
 **PYTHON 3.3 AND UP ONLY!**
 
-`yield-from` is used to call a subgenerator.  This is useful if you
+``yield-from`` is used to call a subgenerator.  This is useful if you
 want your coroutine to be able to delegate its processes to another
 coroutine, say, if using something fancy like
 `asyncio <http://docs.python.org/3.4/library/asyncio.html>`_.

docs/language/cli.rst

@@ -63,7 +63,7 @@ Command Line Options
 hyc
 ---
 
-Command line options
+Command Line Options
 ^^^^^^^^^^^^^^^^^^^^
 
 .. cmdoption:: file[, fileN]
@@ -94,7 +94,7 @@ hy2py
 
 .. versionadded:: 0.10.1
 
-Command line options
+Command Line Options
 ^^^^^^^^^^^^^^^^^^^^
 
 .. cmdoption:: -s

docs/language/core.rst

@@ -13,7 +13,7 @@ butlast
 
 Usage: ``(butlast coll)``
 
-Returns an iterator of all but the last item in ``coll``.
+Returns an iterator of all but the last item in *coll*.
 
 .. code-block:: hy
 
@@ -40,7 +40,7 @@ coll?
 
 Usage: ``(coll? x)``
 
-Returns `True` if argument is iterable and not a string.
+Returns ``True`` if *x* is iterable and not a string.
 
 .. code-block:: hy
 
@@ -61,7 +61,7 @@ cons
 
 Usage: ``(cons a b)``
 
-Returns a fresh :ref:`cons cell <hycons>` with car `a` and cdr `b`.
+Returns a fresh :ref:`cons cell <hycons>` with car *a* and cdr *b*.
 
 .. code-block:: hy
 
@@ -81,7 +81,7 @@ cons?
 
 Usage: ``(cons? foo)``
 
-Checks whether ``foo`` is a :ref:`cons cell <hycons>`.
+Checks whether *foo* is a :ref:`cons cell <hycons>`.
 
 .. code-block:: hy
 
@@ -103,9 +103,8 @@ dec
 
 Usage: ``(dec x)``
 
-Return one less than x. Equivalent to ``(- x 1)``.
+Returns one less than *x*. Equivalent to ``(- x 1)``. Raises ``TypeError``
-
+if ``(not (numeric? x))``.
-Raises ``TypeError`` if ``(not (numeric? x))``.
 
 .. code-block:: hy
 
@@ -128,8 +127,8 @@ disassemble
 
 Usage: ``(disassemble tree &optional [codegen false])``
 
-Dump the Python AST for given Hy ``tree`` to standard output. If *codegen*
+Dump the Python AST for given Hy *tree* to standard output. If *codegen*
-is ``true`` function prints Python code instead.
+is ``True``, the function prints Python code instead.
 
 .. code-block:: hy
 
@@ -149,7 +148,7 @@ empty?
 
 Usage: ``(empty? coll)``
 
-Return `True` if ``coll`` is empty. Equivalent to ``(= 0 (len coll))``.
+Returns ``True`` if *coll* is empty. Equivalent to ``(= 0 (len coll))``.
 
 .. code-block:: hy
 
@@ -172,8 +171,8 @@ every?
 
 Usage: ``(every? pred coll)``
 
-Return `True` if ``(pred x)`` is logical true for every ``x`` in ``coll``,
+Returns ``True`` if ``(pred x)`` is logical true for every *x* in *coll*,
-otherwise `False`. Return `True` if ``coll`` is empty.
+otherwise ``False``. Return ``True`` if *coll* is empty.
 
 .. code-block:: hy
 
@@ -197,7 +196,7 @@ float?
 
 Usage: ``(float? x)``
 
-Return `True` if x is a float.
+Returns ``True`` if *x* is a float.
 
 .. code-block:: hy
 
@@ -215,9 +214,8 @@ even?
 
 Usage: ``(even? x)``
 
-Return `True` if x is even.
+Returns ``True`` if *x* is even. Raises ``TypeError`` if
-
+``(not (numeric? x))``.
-Raises ``TypeError`` if ``(not (numeric? x))``.
 
 .. code-block:: hy
 
@@ -238,7 +236,7 @@ identity
 
 Usage: ``(identity x)``
 
-Returns argument supplied to the function
+Returns the argument supplied to the function.
 
 .. code-block:: hy
 
@@ -256,9 +254,8 @@ inc
 
 Usage: ``(inc x)``
 
-Return one more than x. Equivalent to ``(+ x 1)``.
+Returns one more than *x*. Equivalent to ``(+ x 1)``. Raises ``TypeError``
-
+if ``(not (numeric? x))``.
-Raises ``TypeError`` if ``(not (numeric? x))``.
 
 .. code-block:: hy
 
@@ -277,9 +274,9 @@ Raises ``TypeError`` if ``(not (numeric? x))``.
 instance?
 ---------
 
-Usage: ``(instance? CLASS x)``
+Usage: ``(instance? class x)``
 
-Return `True` if x is an instance of CLASS.
+Returns ``True`` if *x* is an instance of *class*.
 
 .. code-block:: hy
 
@@ -304,7 +301,7 @@ integer?
 
 Usage: ``(integer? x)``
 
-Return `True` if x is an integer. For Python 2, this is
+Returns `True` if *x* is an integer. For Python 2, this is
 either ``int`` or ``long``. For Python 3, this is ``int``.
 
 .. code-block:: hy
@@ -325,7 +322,7 @@ interleave
 
 Usage: ``(interleave seq1 seq2 ...)``
 
-Return an iterable of the first item in each of the sequences,
+Returns an iterable of the first item in each of the sequences,
 then the second, etc.
 
 .. code-block:: hy
@@ -346,7 +343,7 @@ interpose
 
 Usage: ``(interpose item seq)``
 
-Return an iterable of the elements of the sequence separated by the item.
+Returns an iterable of the elements of the sequence separated by the item.
 
 .. code-block:: hy
 
@@ -364,7 +361,7 @@ iterable?
 
 Usage: ``(iterable? x)``
 
-Return `True` if x is iterable. Iterable objects return a new iterator
+Returns ``True`` if *x* is iterable. Iterable objects return a new iterator
 when ``(iter x)`` is called. Contrast with :ref:`iterator?-fn`.
 
 .. code-block:: hy
@@ -397,9 +394,9 @@ iterator?
 
 Usage: ``(iterator? x)``
 
-Return `True` if x is an iterator. Iterators are objects that return
+Returns ``True`` if *x* is an iterator. Iterators are objects that return
-themselves as an iterator when ``(iter x)`` is called.
+themselves as an iterator when ``(iter x)`` is called. Contrast with
-Contrast with :ref:`iterable?-fn`.
+:ref:`iterable?-fn`.
 
 .. code-block:: hy
 
@@ -427,7 +424,7 @@ list*
 
 Usage: ``(list* head &rest tail)``
 
-Generate a chain of nested cons cells (a dotted list) containing the
+Generates a chain of nested cons cells (a dotted list) containing the
 arguments. If the argument list only has one element, return it.
 
 .. code-block:: hy
@@ -453,7 +450,7 @@ macroexpand
 
 Usage: ``(macroexpand form)``
 
-Returns the full macro expansion of form.
+Returns the full macro expansion of *form*.
 
 .. code-block:: hy
 
@@ -472,7 +469,7 @@ macroexpand-1
 
 Usage: ``(macroexpand-1 form)``
 
-Returns the single step macro expansion of form.
+Returns the single step macro expansion of *form*.
 
 .. code-block:: hy
 
@@ -507,9 +504,8 @@ neg?
 
 Usage: ``(neg? x)``
 
-Return `True` if x is less than zero (0).
+Returns ``True`` if *x* is less than zero. Raises ``TypeError`` if
-
+``(not (numeric? x))``.
-Raises ``TypeError`` if ``(not (numeric? x))``.
 
 .. code-block:: hy
 
@@ -530,7 +526,7 @@ nil?
 
 Usage: ``(nil? x)``
 
-Return `True` if x is `nil`/`None`.
+Returns ``True`` if *x* is ``nil`` / ``None``.
 
 .. code-block:: hy
 
@@ -559,7 +555,7 @@ none?
 
 Usage: ``(none? x)``
 
-Return `True` if x is `None`.
+Returns ``True`` if *x* is ``None``.
 
 .. code-block:: hy
 
@@ -585,9 +581,9 @@ nth
 
 Usage: ``(nth coll n &optional [default nil])``
 
-Return the `nth` item in a collection, counting from 0. Return the
+Returns the *n*-th item in a collection, counting from 0. Return the
 default value, ``nil``, if out of bounds (unless specified otherwise).
-Raise ``ValueError`` if ``n`` is negative.
+Raises ``ValueError`` if *n* is negative.
 
 .. code-block:: hy
 
@@ -619,8 +615,8 @@ numeric?
 
 Usage: ``(numeric? x)``
 
-Return `True` if x is a numeric, as defined in the Python
+Returns ``True`` if *x* is a numeric, as defined in Python's
-numbers module class ``numbers.Number``.
+``numbers.Number`` class.
 
 .. code-block:: hy
 
@@ -641,9 +637,8 @@ odd?
 
 Usage: ``(odd? x)``
 
-Return `True` if x is odd.
+Returns ``True`` if *x* is odd. Raises ``TypeError`` if
-
+``(not (numeric? x))``.
-Raises ``TypeError`` if ``(not (numeric? x))``.
 
 .. code-block:: hy
 
@@ -664,9 +659,8 @@ pos?
 
 Usage: ``(pos? x)``
 
-Return `True` if x is greater than zero (0).
+Returns ``True`` if *x* is greater than zero. Raises ``TypeError``
-
+if ``(not (numeric? x))``.
-Raises ``TypeError`` if ``(not (numeric? x))``.
 
 .. code-block:: hy
 
@@ -687,8 +681,7 @@ second
 
 Usage: ``(second coll)``
 
-Return the second member of ``coll``. Equivalent to
+Returns the second member of *coll*. Equivalent to ``(get coll 1)``.
-``(get coll 1)``
 
 .. code-block:: hy
 
@@ -705,8 +698,8 @@ some
 
 Usage: ``(some pred coll)``
 
-Return the first logical true value of ``(pred x)`` for any ``x`` in
+Returns the first logically-true value of ``(pred x)`` for any ``x`` in
-``coll``, otherwise ``nil``. Return ``nil`` if ``coll`` is empty.
+*coll*, otherwise ``nil``. Return ``nil`` if *coll* is empty.
 
 .. code-block:: hy
 
@@ -733,7 +726,7 @@ string?
 
 Usage: ``(string? x)``
 
-Return `True` if x is a string.
+Returns ``True`` if *x* is a string.
 
 .. code-block:: hy
 
@@ -750,7 +743,7 @@ zero?
 
 Usage: ``(zero? x)``
 
-Return `True` if x is zero (0).
+Returns ``True`` if *x* is zero.
 
 .. code-block:: hy
 
@@ -828,7 +821,7 @@ cycle
 
 Usage: ``(cycle coll)``
 
-Return an infinite iterator of the members of coll.
+Returns an infinite iterator of the members of coll.
 
 .. code-block:: clj
 
@@ -846,7 +839,7 @@ distinct
 
 Usage: ``(distinct coll)``
 
-Returns an iterator containing only the unique members in ``coll``.
+Returns an iterator containing only the unique members in *coll*.
 
 .. code-block:: hy
 
@@ -867,8 +860,8 @@ drop
 
 Usage: ``(drop n coll)``
 
-Return an iterator, skipping the first ``n`` members of ``coll``
+Returns an iterator, skipping the first *n* members of *coll*.
-Raises ``ValueError`` if ``n`` is negative.
+Raises ``ValueError`` if *n* is negative.
 
 .. code-block:: hy
 
@@ -892,7 +885,8 @@ drop-last
 
 Usage: ``(drop-last n coll)``
 
-Return an iterator of all but the last ``n`` items in ``coll``. Raise ``ValueError`` if ``n`` is negative.
+Returns an iterator of all but the last *n* items in *coll*. Raises
+``ValueError`` if *n* is negative.
 
 .. code-block:: hy
 
@@ -917,8 +911,7 @@ drop-while
 
 Usage: ``(drop-while pred coll)``
 
-Return an iterator, skipping members of ``coll`` until ``pred``
+Returns an iterator, skipping members of *coll* until *pred* is ``False``.
-is False.
 
 .. code-block:: hy
 
@@ -939,7 +932,7 @@ filter
 
 Usage: ``(filter pred coll)``
 
-Return an iterator for all items in ``coll`` that pass the predicate ``pred``.
+Returns an iterator for all items in *coll* that pass the predicate *pred*.
 
 See also :ref:`remove-fn`.
 
@@ -960,7 +953,7 @@ flatten
 
 Usage: ``(flatten coll)``
 
-Return a single list of all the items in ``coll``, by flattening all
+Returns a single list of all the items in *coll*, by flattening all
 contained lists and/or tuples.
 
 .. code-block:: hy
@@ -979,7 +972,7 @@ iterate
 
 Usage: ``(iterate fn x)``
 
-Return an iterator of `x`, `fn(x)`, `fn(fn(x))`.
+Returns an iterator of *x*, *fn(x)*, *fn(fn(x))*, etc.
 
 .. code-block:: hy
 
@@ -997,10 +990,9 @@ read
 
 Usage: ``(read &optional [from-file eof])``
 
-Reads the next hy expression from `from-file` (defaults to `sys.stdin`), and
+Reads the next Hy expression from *from-file* (defaulting to ``sys.stdin``), and
-can take a single byte as EOF (defaults to an empty string).
+can take a single byte as EOF (defaults to an empty string). Raises ``EOFError``
-Raises an `EOFError` if `from-file` ends before a complete expression can be
+if *from-file* ends before a complete expression can be parsed.
-parsed.
 
 .. code-block:: hy
 
@@ -1044,8 +1036,8 @@ remove
 
 Usage: ``(remove pred coll)``
 
-Return an iterator from ``coll`` with elements that pass the
+Returns an iterator from *coll* with elements that pass the
-predicate, ``pred``, removed.
+predicate, *pred*, removed.
 
 See also :ref:`filter-fn`.
 
@@ -1069,7 +1061,7 @@ repeat
 
 Usage: ``(repeat x)``
 
-Return an iterator (infinite) of ``x``.
+Returns an iterator (infinite) of ``x``.
 
 .. code-block:: hy
 
@@ -1084,7 +1076,7 @@ repeatedly
 
 Usage: ``(repeatedly fn)``
 
-Return an iterator by calling ``fn`` repeatedly.
+Returns an iterator by calling *fn* repeatedly.
 
 .. code-block:: hy
 
@@ -1101,8 +1093,8 @@ take
 
 Usage: ``(take n coll)``
 
-Return an iterator containing the first ``n`` members of ``coll``.
+Returns an iterator containing the first *n* members of *coll*.
-Raises ``ValueError`` if ``n`` is negative.
+Raises ``ValueError`` if *n* is negative.
 
 .. code-block:: hy
 
@@ -1122,7 +1114,7 @@ take-nth
 
 Usage: ``(take-nth n coll)``
 
-Return an iterator containing every ``nth`` member of ``coll``.
+Returns an iterator containing every *n*-th member of *coll*.
 
 .. code-block:: hy
 
@@ -1146,7 +1138,7 @@ take-while
 
 Usage: ``(take-while pred coll)``
 
-Return an iterator from ``coll`` as long as predicate, ``pred`` returns True.
+Returns an iterator from *coll* as long as *pred* returns ``True``.
 
 .. code-block:: hy
 
@@ -1168,8 +1160,9 @@ zipwith
 
 Usage: ``(zipwith fn coll ...)``
 
-Equivalent to ``zip``, but uses a multi-argument function instead of creating a tuple.
+Equivalent to ``zip``, but uses a multi-argument function instead of creating
-If ``zipwith`` is called with N collections, then ``fn`` must accept N arguments.
+a tuple. If ``zipwith`` is called with N collections, then *fn* must accept
+N arguments.
 
 .. code-block:: hy
 

docs/quickstart.rst

@@ -27,7 +27,7 @@ Quickstart
 
 6. Hit CTRL-D when you're done.
 
-OMG! That's amazing! I want to write a Hy program.
+*OMG! That's amazing! I want to write a Hy program.*
 
 7. Open up an elite programming editor and type::
 

docs/tutorial.rst

@@ -264,8 +264,8 @@ What you'll notice is that ``cond`` switches off between a some statement
 that is executed and checked conditionally for true or falseness, and
 then a bit of code to execute if it turns out to be true.  You'll also
 notice that the ``else`` is implemented at the end simply by checking
-for "true"--that's because true will always be true, so if we get this
+for ``true`` -- that's because ``true`` will always be true, so if we get
-far, we'll always run that one!
+this far, we'll always run that one!
 
 You might notice above that if you have code like:
 
@@ -325,7 +325,7 @@ example:
      (os.mkdir "/tmp/somedir/anotherdir")
      (print "Hey, that path isn't there!"))
 
-Python's context managers ('with' statements) are used like this:
+Python's context managers (``with`` statements) are used like this:
 
 .. code-block:: clj
 
@@ -488,7 +488,7 @@ Protips!
 ========
 
 Hy also features something known as the "threading macro", a really neat
-feature of Clojure's. The "threading macro" (written as "->"), is used
+feature of Clojure's. The "threading macro" (written as ``->``) is used
 to avoid deep nesting of expressions.
 
 The threading macro inserts each expression into the next expression's first