Merge pull request #699 from iKevinY/doc-fixes

Various changes to documentation pages

CONTRIBUTING.rst

@@ -1,35 +1,33 @@
 Contributions are welcome & greatly appreciated, every little bit
 helps in making Hy more awesome.
 
-Pull requests are great! We love them, here is a quick guide:
+Pull requests are great! We love them; here is a quick guide:
 
-- Fork the repo, create a topic branch for a feature/fix. Avoid
+- Fork the repo and create a topic branch for a feature/fix. Avoid
-  making changes directly on the master branch
+  making changes directly on the master branch.
 
-- All incoming features should be accompanied with tests
+- All incoming features should be accompanied with tests.
 
 - Before you submit a PR, please run the tests and check your code
-  against the style guide.  You can do both these things at once::
+  against the style guide. You can do both of these things at once::
 
     $ make d
 
 - Make commits into logical units, so that it is easier to track &
   navigate later. Before submitting a PR, try squashing the commits
-  into changesets that are easy to come back to later. Also make sure
+  into changesets that are easy to come back to later. Also, make sure
-  you don't leave spurious whitespace in the changesets, this avoids
+  you don't leave spurious whitespace in the changesets; this avoids
   creation of whitespace fix commits later.
 
-- As far as commit messages go, try to adhere to
+- As far as commit messages go, try to adhere to the following:
-  the following:
 
-  + Try sticking to the 50 character limit for the first line of git
+  + Try sticking to the 50 character limit for the first line of Git
-    commit messages
+    commit messages.
 
-  + For more explanations etc. follow this up with a blank line and
+  + For more detail/explainations, follow this up with a blank line and
-    continue describing the commit in detail
+    continue describing the commit in detail.
 
-
+- Finally, add yourself to the AUTHORS file (as a separate commit): you
-- Finally add yourself to the AUTHORS file (as a separate commit), you
   deserve it :)
 
 - All incoming changes need to be acked by 2 different members of

docs/hacking.rst

@@ -1,13 +1,13 @@
 ===============
- Hacking on hy
+ Hacking on Hy
 ===============
 
 .. highlight:: bash
 
-Join our hyve!
+Join our Hyve!
 ==============
 
-Please come hack on hy!
+Please come hack on Hy!
 
 Please come hang out with us on ``#hy`` on ``irc.freenode.net``!
 
@@ -23,7 +23,7 @@ Hack!
 
 Do this:
 
-1. create a `virtual environment
+1. Create a `virtual environment
    <https://pypi.python.org/pypi/virtualenv>`_::
 
        $ virtualenv venv
@@ -38,23 +38,24 @@ Do this:
        $ mkvirtualenv hy
        $ workon hy
 
-2. get the source code::
+2. Get the source code::
 
        $ git clone https://github.com/hylang/hy.git
 
    or use your fork::
 
        $ git clone git@github.com:<YOUR_USERNAME>/hy.git
-3. install for hacking::
+
+3. Install for hacking::
 
        $ cd hy/
        $ pip install -e .
 
-4. install other develop-y requirements::
+4. Install other develop-y requirements::
 
        $ pip install -r requirements-dev.txt
 
-5. do awesome things; make someone shriek in delight/disgust at what
+5. Do awesome things; make someone shriek in delight/disgust at what
    you have wrought.
 
 
@@ -70,8 +71,8 @@ To run the tests::
 
 Write tests---tests are good!
 
-Also, it is good to run the tests for all the platforms supported and for pep8 compliant code. 
+Also, it is good to run the tests for all the platforms supported and for
-You can do so by running tox::
+PEP 8 compliant code. You can do so by running tox::
 
     $ tox
 
@@ -97,6 +98,6 @@ Contributing
 Core Team
 =========
 
-Core development team of hy consists of following developers.
+The core development team of Hy consists of following developers:
 
 .. include:: coreteam.rst

docs/quickstart.rst

@@ -11,10 +11,10 @@ Quickstart
 **HOW TO GET HY REAL FAST**:
 
 1. Create a `Virtual Python Environment
-   <https://pypi.python.org/pypi/virtualenv>`_
+   <https://pypi.python.org/pypi/virtualenv>`_.
-2. Activate your Virtual Python Environment
+2. Activate your Virtual Python Environment.
-3. Install `hy from PyPI <https://pypi.python.org/pypi/hy>`_ with ``pip install hy``
+3. Install `hy from PyPI <https://pypi.python.org/pypi/hy>`_ with ``pip install hy``.
-4. Start a REPL with ``hy``
+4. Start a REPL with ``hy``.
 5. Type stuff in the REPL::
 
        => (print "Hy!")
@@ -25,19 +25,19 @@ Quickstart
 
        etc
 
-6. Hit CTRL-D when you're done
+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::
 
-       (print "I was going to code in python syntax, but then I got hy.")
+       (print "I was going to code in Python syntax, but then I got Hy.")
 
-8. Save as ``awesome.hy``
+8. Save as ``awesome.hy``.
 9. And run your first Hy program::
 
         hy awesome.hy
 
-10. Take a deep breath so as to not hyperventilate
+10. Take a deep breath so as to not hyperventilate.
 11. Smile villainously and sneak off to your hydeaway and do
-    unspeakable things
+    unspeakable things.

docs/tutorial.rst

@@ -3,7 +3,7 @@ Tutorial
 ========
 
 .. TODO
-.. 
+..
 ..  - How do I index into arrays or dictionaries?
 ..  - How do I do array ranges?  e.g. x[5:] or y[2:10]
 ..  - Blow your mind with macros!
@@ -12,34 +12,34 @@ Tutorial
 
 Welcome to the Hy tutorial!
 
-In a nutshell, Hy is a lisp dialect, but one that converts its
+In a nutshell, Hy is a Lisp dialect, but one that converts its
-structure into Python... literally a conversion into Python's abstract
+structure into Python ... literally a conversion into Python's abstract
 syntax tree!  (Or to put it in more crude terms, Hy is lisp-stick on a
-python!)
+Python!)
 
 This is pretty cool because it means Hy is several things:
 
- - A lisp that feels very pythonic
+ - A Lisp that feels very Pythonic
- - For lispers, a great way to use lisp's crazy powers but in the wide
+ - For Lispers, a great way to use Lisp's crazy powers but in the wide
    world of Python's libraries (why yes, you now can write a Django
-   application in lisp!)
+   application in Lisp!)
- - For pythonistas, a great way to start exploring lisp, from the
+ - For Pythonistas, a great way to start exploring Lisp, from the
-   comfort of python!
+   comfort of Python!
  - For everyone: a pleasant language that has a lot of neat ideas!
 
 
-Basic intro to lisp for pythonistas
+Basic intro to Lisp for Pythonistas
 ===================================
 
-Okay, maybe you've never used lisp before, but you've used python!
+Okay, maybe you've never used Lisp before, but you've used Python!
 
-A "hello world" in hy is actually super simple.  Let's try it:
+A "hello world" program in Hy is actually super simple. Let's try it:
 
 .. code-block:: clj
 
    (print "hello world")
 
-See?  Easy!  As you may have guessed, this is the same as the python
+See?  Easy!  As you may have guessed, this is the same as the Python
 version of::
 
   print "hello world"
@@ -58,7 +58,7 @@ Which would return 4 and would be the equivalent of:
 
 What you'll notice is that the first item in the list is the function
 being called and the rest of the arguments are the arguments being
-passed in.  In fact, in hy (as with most lisps) we can pass in
+passed in.  In fact, in Hy (as with most Lisps) we can pass in
 multiple arguments to the plus operator:
 
 .. code-block:: clj
@@ -67,13 +67,13 @@ multiple arguments to the plus operator:
 
 Which would return 59.
 
-Maybe you've heard of lisp before but don't know much about it.  Lisp
+Maybe you've heard of Lisp before but don't know much about it.  Lisp
-isn't as hard as you might think, and hy inherits from python, so hy
+isn't as hard as you might think, and Hy inherits from Python, so Hy
-is a great way to start learning lisp.  The main thing that's obvious
+is a great way to start learning Lisp.  The main thing that's obvious
-about lisp is that there's a lot of parentheses.  This might seem
+about Lisp is that there's a lot of parentheses.  This might seem
 confusing at first, but it isn't so hard.  Let's look at some simple
 math that's wrapped in a bunch of parentheses that we could enter into
-the hy interpreter:
+the Hy interpreter:
 
 .. code-block:: clj
 
@@ -81,13 +81,13 @@ the hy interpreter:
 
 This would return 38.  But why?  Well, we could look at the equivalent
 expression in python::
-  
+
   result = ((1 + 3 + 88) / 2) - 8
 
 If you were to try to figure out how the above were to work in python,
 you'd of course figure out the results by solving each inner
-parenthesis.  That's the same basic idea in hy.  Let's try this
+parenthesis.  That's the same basic idea in Hy.  Let's try this
-exercise first in python::
+exercise first in Python::
 
   result = ((1 + 3 + 88) / 2) - 8
   # simplified to...
@@ -97,7 +97,7 @@ exercise first in python::
   # simplified to...
   result = 38
 
-Now let's try the same thing in hy:
+Now let's try the same thing in Hy:
 
 .. code-block:: clj
 
@@ -109,28 +109,28 @@ Now let's try the same thing in hy:
    ; simplified to...
    (setv result 38)
 
-As you probably guessed, this last expression with "setv" means to
+As you probably guessed, this last expression with ``setv`` means to
 assign the variable "result" to 38.
 
 See?  Not too hard!
 
-This is the basic premise of lisp... lisp stands for "list
+This is the basic premise of Lisp. Lisp stands for "list
-processing"... this means that the structure of the program is
+processing"; this means that the structure of the program is
-actually lists of lists.  (If you're familiar with python lists,
+actually lists of lists.  (If you're familiar with Python lists,
 imagine the entire same structure as above but with square brackets
 instead, any you'll be able to see the structure above as both a
 program and a datastructure.)  This is easier to understand with more
-examples, so let's write a simple python program and test it and then
+examples, so let's write a simple Python program, test it, and then
-show the equivalent hy program::
+show the equivalent Hy program::
 
   def simple_conversation():
       print "Hello!  I'd like to get to know you.  Tell me about yourself!"
       name = raw_input("What is your name? ")
       age = raw_input("What is your age? ")
       print "Hello " + name + "!  I see you are " + age + " years old."
-  
+
   simple_conversation()
-  
+
 If we ran this program, it might go like::
 
   Hello!  I'd like to get to know you.  Tell me about yourself!
@@ -138,7 +138,7 @@ If we ran this program, it might go like::
   What is your age? 38
   Hello Gary!  I see you are 38 years old.
 
-Now let's look at the equivalent hy program:
+Now let's look at the equivalent Hy program:
 
 .. code-block:: clj
 
@@ -155,7 +155,7 @@ If you look at the above program, as long as you remember that the
 first element in each list of the program is the function (or
 macro... we'll get to those later) being called and that the rest are
 the arguments, it's pretty easy to figure out what this all means.
-(As you probably also guessed, defn is the hy method of defining
+(As you probably also guessed, ``defn`` is the Hy method of defining
 methods.)
 
 Still, lots of people find this confusing at first because there's so
@@ -165,23 +165,23 @@ matching (this will help you figure out what each parenthesis pairs up
 with) and things will start to feel comfortable.
 
 There are some advantages to having a code structure that's actually a
-very simple datastructure as the core of lisp is based on.  For one
+very simple data structure as the core of Lisp is based on.  For one
 thing, it means that your programs are easy to parse and that the
 entire actual structure of the program is very clearly exposed to you.
 (There's an extra step in hy where the structure you see is converted
-to python's own representations... in more "pure" lisps such as common
+to Python's own representations ... in "purer" Lisps such as Common
-lisp or emacs lisp, the data structure you see for the code and the
+Lisp or Emacs Lisp, the data structure you see in the code and the
 data structure that is executed is much more literally close.)
 
 Another implication of this is macros: if a program's structure is a
 simple data structure, that means you can write code that can write
 code very easily, meaning that implementing entirely new language
-features can be very fast.  Previous to hy, this wasn't very possible
+features can be very fast.  Previous to Hy, this wasn't very possible
-for python programmers... now you too can make use of macros'
+for Python programmers ... now you too can make use of macros'
 incredible power (just be careful to not aim them footward)!
 
 
-Hy is a Lisp flavored Python
+Hy is a Lisp-flavored Python
 ============================
 
 Hy converts to Python's own abstract syntax tree, so you'll soon start
@@ -199,7 +199,7 @@ Hy.  Let's experiment with this in the hy interpreter::
   => (, 1 2 3)
   (1, 2, 3)
 
-If you are familiar with other lisps, you may be interested that Hy
+If you are familiar with other Lisps, you may be interested that Hy
 supports the Common Lisp method of quoting:
 
 .. code-block:: clj
@@ -207,7 +207,7 @@ supports the Common Lisp method of quoting:
    => '(1 2 3)
    (1L 2L 3L)
 
-You also have access to all the builtin types' nice methods::
+You also have access to all the built-in types' nice methods::
 
   => (.strip " fooooo   ")
   "fooooo"
@@ -216,7 +216,7 @@ What's this?  Yes indeed, this is precisely the same as::
 
   " fooooo   ".strip()
 
-That's right... lisp with dot notation!  If we have this string
+That's right---Lisp with dot notation!  If we have this string
 assigned as a variable, we can also do the following:
 
 .. code-block:: clj
@@ -232,13 +232,13 @@ What about conditionals?:
      (print "this is if true")
      (print "this is if false"))
 
-As you can tell above, the first argument to if is a truth test, the
+As you can tell above, the first argument to ``if`` is a truth test, the
-second argument is a body if true, and the third argument (optional!)
+second argument is the body if true, and the third argument (optional!)
-is if false (ie, "else"!).
+is if false (ie. ``else``).
 
 If you need to do more complex conditionals, you'll find that you
-don't have elif available in hy.  Instead, you should use something
+don't have ``elif`` available in Hy.  Instead, you should use something
-called "cond".  In python, you might do something like::
+called ``cond``.  In Python, you might do something like::
 
   somevar = 33
   if somevar > 50:
@@ -248,7 +248,7 @@ called "cond".  In python, you might do something like::
   else:
       print "That variable is jussssst right!"
 
-In hy, you would do:
+In Hy, you would do:
 
 .. code-block:: clj
 
@@ -260,12 +260,12 @@ In hy, you would do:
     [true
      (print "That variable is jussssst right!")])
 
-What you'll notice is that cond switches off between a some statement
+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
+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
+for "true"--that's because true will always be true, so if we get this
-this far, we'll always run that one!
+far, we'll always run that one!
 
 You might notice above that if you have code like:
 
@@ -288,8 +288,8 @@ You can do the following:
        (print "and why not, let's keep talking about how true it is!))
      (print "this one's still simply just false"))
 
-You can see that we used "do" to wrap multiple statements.  If you're
+You can see that we used ``do`` to wrap multiple statements.  If you're
-familiar with other lisps, this is the equivalent of "progn"
+familiar with other Lisps, this is the equivalent of ``progn``
 elsewhere.
 
 Comments start with semicolons:
@@ -300,13 +300,13 @@ Comments start with semicolons:
   ; (print "but this will not")
   (+ 1 2 3)  ; we'll execute the addition, but not this comment!
 
-Looping is not hard but has a kind of special structure.  In python,
+Looping is not hard but has a kind of special structure.  In Python,
 we might do::
 
   for i in range(10):
       print "'i' is now at " + str(i)
 
-The equivalent in hy would be:
+The equivalent in Hy would be:
 
 .. code-block:: clj
 
@@ -314,21 +314,21 @@ The equivalent in hy would be:
     (print (+ "'i' is now at " (str i))))
 
 
-You can also import and make use of various python libraries.  For
+You can also import and make use of various Python libraries.  For
 example:
 
 .. code-block:: clj
 
    (import os)
-  
+
    (if (os.path.isdir "/tmp/somedir")
      (os.mkdir "/tmp/somedir/anotherdir")
      (print "Hey, that path isn't there!"))
 
 Python's context managers ('with' statements) are used like this:
 
-.. code-block:: clj 
+.. code-block:: clj
- 
+
      (with [[f (open "/tmp/data.in")]]
        (print (.read f)))
 
@@ -336,15 +336,15 @@ which is equivalent to::
 
   with open("/tmp/data.in") as f:
       print f.read()
- 
+
-And yes, we do have lisp comprehensions!  In Python you might do::
+And yes, we do have Lisp comprehensions!  In Python you might do::
 
   odds_squared = [
     pow(num, 2)
     for num in range(100)
     if num % 2 == 1]
 
-In hy, you could do these like:
+In Hy, you could do these like:
 
 .. code-block:: clj
 
@@ -359,12 +359,12 @@ In hy, you could do these like:
 
   ; And, an example stolen shamelessly from a Clojure page:
   ; Let's list all the blocks of a Chessboard:
-  
+
   (list-comp
     (, x y)
     (x (range 8)
      y "ABCDEFGH"))
-  
+
   ; [(0, 'A'), (0, 'B'), (0, 'C'), (0, 'D'), (0, 'E'), (0, 'F'), (0, 'G'), (0, 'H'),
   ;  (1, 'A'), (1, 'B'), (1, 'C'), (1, 'D'), (1, 'E'), (1, 'F'), (1, 'G'), (1, 'H'),
   ;  (2, 'A'), (2, 'B'), (2, 'C'), (2, 'D'), (2, 'E'), (2, 'F'), (2, 'G'), (2, 'H'),
@@ -376,11 +376,11 @@ In hy, you could do these like:
 
 
 Python has support for various fancy argument and keyword arguments.
-In python we might see::
+In Python we might see::
 
   >>> def optional_arg(pos1, pos2, keyword1=None, keyword2=42):
   ...   return [pos1, pos2, keyword1, keyword2]
-  ... 
+  ...
   >>> optional_arg(1, 2)
   [1, 2, None, 42]
   >>> optional_arg(1, 2, 3, 4)
@@ -401,7 +401,7 @@ The same thing in Hy::
   ...          "pos2" 2
   ...          "pos1" 3
   ...          "keyword2" 4})
-  ... 
+  ...
   [3, 2, 1, 4]
 
 See how we use apply to handle the fancy passing? :)
@@ -431,7 +431,7 @@ The Hy equivalent:
     (import pprint)
     (pprint.pprint (, foo bar args kwargs)))
 
-Finally, of course we need classes!  In python we might have a class
+Finally, of course we need classes!  In Python, we might have a class
 like::
 
   class FooBar(object):
@@ -460,7 +460,7 @@ In Hy:
         ; Currently needed for --init-- because __init__ needs None
         ; Hopefully this will go away :)
         None)]
-  
+
      [get-x
       (fn [self]
         "Return our copy of x"