Merge pull request #704 from iKevinY/doc-changes

Fixes to documentation (language & contributor modules)

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
 
@@ -63,7 +63,7 @@ ap-map
 Usage: ``(ap-map form list)``
 
 The anaphoric form of map works just like regular map except that
-instead of a function object it takes a Hy form. The special name,
+instead of a function object it takes a Hy form. The special name
 ``it`` is bound to the current object from the list in the iteration.
 
 .. code-block:: hy

docs/contrib/index.rst

@@ -1,6 +1,6 @@
-
+=========================
-Contrib Modules Index
+Contributor Modules Index
-=====================
+=========================
 
 Contents:
 

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 clojures take on `defn`.
+args and/or kwargs. Inspired by Clojure's take on ``defn``.
 
 .. code-block:: clj
 

docs/language/cli.rst

@@ -7,7 +7,7 @@ Command Line Interface
 hy
 --
 
-Command line options
+Command Line Options
 ^^^^^^^^^^^^^^^^^^^^
 
 .. cmdoption:: -c <command>
@@ -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

@@ -1,10 +1,10 @@
-=================
+=======
 Hy Core
-=================
+=======
 
 
 Core Functions
-===============
+==============
 
 .. _butlast-fn:
 
@@ -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, i.e. ``(= 0 (len coll))``.
+Returns ``True`` if *coll* is empty. Equivalent to ``(= 0 (len coll))``.
 
 .. code-block:: hy
 
@@ -172,7 +171,8 @@ every?
 
 Usage: ``(every? pred coll)``
 
-Return True if ``(pred x)`` is logical true for every ``x`` in ``coll``, otherwise False. Return True if ``coll`` is empty.
+Returns ``True`` if ``(pred x)`` is logical true for every *x* in *coll*,
+otherwise ``False``. Return ``True`` if *coll* is empty.
 
 .. code-block:: hy
 
@@ -196,7 +196,7 @@ float?
 
 Usage: ``(float? x)``
 
-Return True if x is a float.
+Returns ``True`` if *x* is a float.
 
 .. code-block:: hy
 
@@ -214,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
 
@@ -237,7 +236,7 @@ identity
 
 Usage: ``(identity x)``
 
-Returns argument supplied to the function
+Returns the argument supplied to the function.
 
 .. code-block:: hy
 
@@ -255,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
 
@@ -276,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
 
@@ -303,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
@@ -324,7 +322,8 @@ interleave
 
 Usage: ``(interleave seq1 seq2 ...)``
 
-Return an iterable of the first item in each of the sequences, then the second etc.
+Returns an iterable of the first item in each of the sequences,
+then the second, etc.
 
 .. code-block:: hy
 
@@ -344,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
 
@@ -362,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
@@ -395,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
 
@@ -417,12 +416,15 @@ Contrast with :ref:`iterable?-fn`.
    => (iterator? (iter {:a 1 :b 2 :c 3}))
    True
 
+
+.. _list*-fn:
+
 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
@@ -448,7 +450,7 @@ macroexpand
 
 Usage: ``(macroexpand form)``
 
-Returns the full macro expansion of form.
+Returns the full macro expansion of *form*.
 
 .. code-block:: hy
 
@@ -467,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
 
@@ -482,14 +484,14 @@ merge-with
 
 .. versionadded:: 0.10.1
 
-Usage: ``(merge-with f &rest maps)
+Usage: ``(merge-with f &rest maps)``
 
 Returns a map that consist of the rest of the maps joined onto first.
 If a key occurs in more than one map, the mapping(s) from the latter
 (left-to-right) will be combined with the mapping in the result by
 calling ``(f val-in-result val-in-latter)``.
 
-.. code-block:: clojure
+.. code-block:: hy
 
     => (merge-with (fn [x y] (+ x y)) {"a" 10 "b" 20} {"a" 1 "c" 30})
     {u'a': 11L, u'c': 30L, u'b': 20L}
@@ -502,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
 
@@ -521,11 +522,11 @@ Raises ``TypeError`` if ``(not (numeric? x))``.
 .. _nil?-fn:
 
 nil?
------
+----
 
 Usage: ``(nil? x)``
 
-Return True if x is nil/None.
+Returns ``True`` if *x* is ``nil`` / ``None``.
 
 .. code-block:: hy
 
@@ -554,7 +555,7 @@ none?
 
 Usage: ``(none? x)``
 
-Return True if x is None.
+Returns ``True`` if *x* is ``None``.
 
 .. code-block:: hy
 
@@ -580,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
 
@@ -610,12 +611,12 @@ Raise ``ValueError`` if ``n`` is negative.
 .. _numeric?-fn:
 
 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
 
@@ -636,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
 
@@ -659,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
 
@@ -678,12 +677,11 @@ Raises ``TypeError`` if ``(not (numeric? x))``.
 .. _second-fn:
 
 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
 
@@ -700,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
 
@@ -728,7 +726,7 @@ string?
 
 Usage: ``(string? x)``
 
-Return True if x is a string.
+Returns ``True`` if *x* is a string.
 
 .. code-block:: hy
 
@@ -745,7 +743,7 @@ zero?
 
 Usage: ``(zero? x)``
 
-Return True if x is zero (0).
+Returns ``True`` if *x* is zero.
 
 .. code-block:: hy
 
@@ -760,7 +758,7 @@ Return True if x is zero (0).
 
 
 Sequence Functions
-=======================
+==================
 
 Sequence functions can either create or operate on a potentially
 infinite sequence without requiring the sequence be fully realized in
@@ -819,11 +817,11 @@ To get the Fibonacci number at index 9, (starting from 0):
 .. _cycle-fn:
 
 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
 
@@ -841,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
 
@@ -862,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
 
@@ -887,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
 
@@ -912,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
 
@@ -934,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`.
 
@@ -955,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
@@ -974,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
 
@@ -992,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
 
@@ -1039,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`.
 
@@ -1064,7 +1061,7 @@ repeat
 
 Usage: ``(repeat x)``
 
-Return an iterator (infinite) of ``x``.
+Returns an iterator (infinite) of ``x``.
 
 .. code-block:: hy
 
@@ -1079,7 +1076,7 @@ repeatedly
 
 Usage: ``(repeatedly fn)``
 
-Return an iterator by calling ``fn`` repeatedly.
+Returns an iterator by calling *fn* repeatedly.
 
 .. code-block:: hy
 
@@ -1096,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
 
@@ -1117,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
 
@@ -1141,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
 
@@ -1154,7 +1151,7 @@ Return an iterator from ``coll`` as long as predicate, ``pred`` returns True.
    => (list (take-while neg? [ 1 2 3 -4 5]))
    []
 
-.. _zipwith:
+.. _zipwith-fn:
 
 zipwith
 -------
@@ -1163,10 +1160,11 @@ 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:: clojure
+.. code-block:: hy
 
    => (import operator)
    => (list (zipwith operator.add [1 2 3] [4 5 6]))

docs/language/internals.rst

@@ -10,7 +10,7 @@ Internal Hy Documentation
 Hy Models
 =========
 
-Introduction to Hy models
+Introduction to Hy Models
 -------------------------
 
 Hy models are a very thin layer on top of regular Python objects,
@@ -33,7 +33,7 @@ macros, be that in the compiler or in pure hy macros.
 ``HyObject`` is not intended to be used directly to instantiate Hy
 models, but only as a mixin for other classes.
 
-Compound models
+Compound Models
 ---------------
 
 Parenthesized and bracketed lists are parsed as compound models by the
@@ -77,7 +77,7 @@ The decision of using a list instead of a dict as the base class for
 benefit of allowing compound expressions as dict keys (as, for instance,
 the :ref:`HyExpression` Python class isn't hashable).
 
-Atomic models
+Atomic Models
 -------------
 
 In the input stream, double-quoted strings, respecting the Python
@@ -115,7 +115,7 @@ strings.
 
 .. _hy_numeric_models:
 
-Numeric models
+Numeric Models
 ~~~~~~~~~~~~~~
 
 ``hy.models.integer.HyInteger`` represents integer literals (using the
@@ -217,7 +217,7 @@ from source to runtime.
 
 .. _lexing:
 
-Steps 1 and 2: Tokenizing and parsing
+Steps 1 and 2: Tokenizing and Parsing
 -------------------------------------
 
 The first stage of compiling Hy is to lex the source into tokens that we can
@@ -238,7 +238,7 @@ on (directly), and it's what the compiler uses when it compiles Hy down.
 
 .. _compiling:
 
-Step 3: Hy compilation to Python AST
+Step 3: Hy Compilation to Python AST
 ------------------------------------
 
 This is where most of the magic in Hy happens. This is where we take Hy AST
@@ -262,7 +262,7 @@ All methods that preform a compilation are marked with the ``@builds()``
 decorator. You can either pass the class of the Hy model that it compiles,
 or you can use a string for expressions. I'll clear this up in a second.
 
-First stage type-dispatch
+First Stage Type-Dispatch
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Let's start in the ``compile`` method. The first thing we do is check the
@@ -276,14 +276,14 @@ Hy AST to Python AST. The ``compile_string`` method takes the ``HyString``, and
 returns an ``ast.Str()`` that's populated with the correct line-numbers and
 content.
 
-Macro-expand
+Macro-Expand
 ~~~~~~~~~~~~
 
 If we get a ``HyExpression``, we'll attempt to see if this is a known
 Macro, and push to have it expanded by invoking ``hy.macros.macroexpand``, then
 push the result back into ``HyASTCompiler.compile``.
 
-Second stage expression-dispatch
+Second Stage Expression-Dispatch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The only special case is the ``HyExpression``, since we need to create different
@@ -300,7 +300,7 @@ properly handle that case as well (most likely by raising an ``Exception``).
 If the String isn't known to Hy, it will default to create an ``ast.Call``,
 which will try to do a runtime call (in Python, something like ``foo()``).
 
-Issues hit with Python AST
+Issues Hit with Python AST
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Python AST is great; it's what's enabled us to write such a powerful project
@@ -351,7 +351,7 @@ into::
 By forcing things into an ``ast.expr`` if we can, but the general idea holds.
 
 
-Step 4: Python bytecode output and runtime
+Step 4: Python Bytecode Output and Runtime
 ------------------------------------------
 
 After we have a Python AST tree that's complete, we can try and compile it to
@@ -365,8 +365,8 @@ Hy Macros
 
 .. _using-gensym:
 
-Using gensym for safer macros
+Using gensym for Safer Macros
-------------------------------
+-----------------------------
 
 When writing macros, one must be careful to avoid capturing external variables
 or using variable names that might conflict with user code.
@@ -447,13 +447,13 @@ Our final version of ``nif``, built with ``defmacro/g!`` becomes:
 
 
 
-Checking macro arguments and raising exceptions
+Checking Macro Arguments and Raising Exceptions
 -----------------------------------------------
 
 
 
-Hy Compiler Builtins
+Hy Compiler Built-Ins
-====================
+=====================
 
 .. todo::
     Write this.

docs/language/readermacros.rst

@@ -6,8 +6,8 @@
 Reader Macros
 =============
 
-Reader macros gives LISP the power to modify and alter syntax on the fly.
+Reader macros gives Lisp the power to modify and alter syntax on the fly.
-You don't want polish notation? A reader macro can easily do just that. Want
+You don't want Polish notation? A reader macro can easily do just that. Want
 Clojure's way of having a regex? Reader macros can also do this easily.
 
 
@@ -33,7 +33,7 @@ else. This is a problem reader macros are able to solve in a neat way.
     => #t(1 2 3)
     (1, 2, 3)
 
-You could even do like clojure, and have a literal for regular expressions!
+You could even do it like Clojure and have a literal for regular expressions!
 
 ::
 
@@ -46,10 +46,10 @@ You could even do like clojure, and have a literal for regular expressions!
 Implementation
 ==============
 
-``defreader`` takes a single character as symbol name for the reader macro,
+``defreader`` takes a single character as symbol name for the reader macro;
-anything longer will return an error. Implementation wise, ``defreader``
+anything longer will return an error. Implementation-wise, ``defreader``
-expands into a lambda covered with a decorator, this decorator saves the
+expands into a lambda covered with a decorator. This decorator saves the
-lambda in a dict with its module name and symbol.
+lambda in a dictionary with its module name and symbol.
 
 ::
 

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
 
@@ -542,7 +542,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