Miscellaneous fixes to transplanted style guide

docs/style-guide.rst

@@ -4,7 +4,7 @@ Hy Style Guide
 
    “You know, Minister, I disagree with Dumbledore on many counts…but
    you cannot deny he’s got style…”
-   — Phineas Nigellus Black, Harry Potter & the Order of the Phoenix
+   — Phineas Nigellus Black, *Harry Potter and the Order of the Phoenix*
 
 The Hy style guide intends to be a set of ground rules for the Hyve
 (yes, the Hy community prides itself in appending Hy to everything)
@@ -18,7 +18,7 @@ Prelude
 The Tao of Hy
 -------------
 
-::
+.. code-block:: none
 
    Ummon asked the head monk, "What sutra are you lecturing on?"
    "The Nirvana Sutra."
@@ -36,14 +36,14 @@ The Tao of Hy
 The following illustrates a brief list of design decisions that went
 into the making of Hy.
 
-+ Look like a lisp, DTRT with it (e.g. dashes turn to underscores,
++ Look like a Lisp; DTRT with it (e.g. dashes turn to underscores, earmuffs
-  earmuffs turn to all-caps.)
+  turn to all-caps).
 + We're still Python. Most of the internals translate 1:1 to Python internals.
-+ Use unicode everywhere.
++ Use Unicode everywhere.
-+ Fix the bad decisions in Python 2 when we can (see true_division)
++ Fix the bad decisions in Python 2 when we can (see ``true_division``).
 + When in doubt, defer to Python.
-+ If you're still unsure, defer to Clojure
++ If you're still unsure, defer to Clojure.
-+ If you're even more unsure, defer to Common Lisp
++ If you're even more unsure, defer to Common Lisp.
 + Keep in mind we're not Clojure. We're not Common Lisp. We're
   Homoiconic Python, with extra bits that make sense.
 
@@ -58,41 +58,41 @@ Layout & Indentation
 
 .. code-block:: clj
 
-  ;; good (and preferred):
+   ;; Good (and preferred)
-  (defn fib [n]
+   (defn fib [n]
-    (if (<= n 2)
+     (if (<= n 2)
-	n
+       n
-	(+ (fib (- n 1)) (fib (- n 2)))))
+       (+ (fib (- n 1)) (fib (- n 2)))))
 
-  ;; still OK:
+   ;; Still okay
-  (defn fib [n]
+   (defn fib [n]
-    (if (<= n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
+     (if (<= n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
 
-  ;; still OK:
+   ;; Still okay
-  (defn fib [n]
+   (defn fib [n]
-    (if (<= n 2)
+     (if (<= n 2)
-      n
+       n
-      (+ (fib (- n 1)) (fib (- n 2)))))
+       (+ (fib (- n 1)) (fib (- n 2)))))
 
-  ;; Stupid as hell
+   ;; Hysterically ridiculous
-  (defn fib [n]
+   (defn fib [n]
-      (if (<= n 2)
+       (if (<= n 2)
-	      n ;; Yes, I love randomly hitting the space key
+               n ;; yes, I love randomly hitting the space key
-	(+ (fib (- n 1)) (fib (- n 2)))))
+         (+ (fib (- n 1)) (fib (- n 2)))))
 
 
-+ Parens must *never* be left alone, sad and lonesome on their own
++ Parentheses must *never* be left alone, sad and lonesome on their own
   line.
 
 .. code-block:: clj
 
-  ;; good (and preferred):
+  ;; Good (and preferred)
   (defn fib [n]
     (if (<= n 2)
 	n
 	(+ (fib (- n 1)) (fib (- n 2)))))
 
-  ;; Stupid as hell
+  ;; Hysterically ridiculous
   (defn fib [n]
       (if (<= n 2)
 	n
@@ -101,29 +101,25 @@ Layout & Indentation
   )  ; GAH, BURN IT WITH FIRE
 
 
-+ **`let` blocks**
++ Vertically align ``let`` blocks.
-
-  Align vertically the `let` blocks
 
 .. code-block:: clj
 
-  (let [[foo (bar)]
+   (let [[foo (bar)]
-	[qux (baz)]]
+         [qux (baz)]]
-    (foo qux))
+     (foo qux))
 
 
-+ **Inline comments**
++ Inline comments shall be two spaces from the end of the code; they
-
-  Inline comments shall be two spaces from the end of the code, they
   must always have a space between the comment character and the start
-  of the comment. Also try not commenting the obvious
+  of the comment. Also, try to not comment the obvious.
 
 .. code-block:: clj
 
    ;; Good
    (setv ind (dec x))  ; indexing starts from 0
 
-   ;; Style compliant but just states the obvious
+   ;; Style-compliant but just states the obvious
    (setv ind (dec x))  ; sets index to x-1
 
    ;; Bad
@@ -133,12 +129,12 @@ Layout & Indentation
 Coding Style
 ============
 
-+ As a convention, try not to use `def` for other than global
++ As a convention, try not to use ``def`` for anything other than global
-  variables, use `setv` inside functions,loops etc.
+  variables; use ``setv`` inside functions, loops, etc.
 
 .. code-block:: clj
 
-   ;; good (and preferred)
+   ;; Good (and preferred)
    (def *limit* 400000)
 
    (defn fibs [a b]
@@ -146,74 +142,61 @@ Coding Style
        (yield a)
        (setv (, a b) (, b (+ a b)))))
 
-   ;; bad & not preferred
+   ;; Bad (and not preferred)
    (defn fibs [a b]
      (while true
        (yield a)
        (def (, a b) (, b (+ a b)))))
 
 
-+ Do not use the s-expression syntax where vector syntax is intended.
++ Do not use s-expression syntax where vector syntax is intended.
-  For instance, the fact that:
+  For instance, the fact that the former of these two examples works
+  is just because the compiler isn't overly strict. In reality, the
+  correct syntax in places such as this is the latter.
 
 .. code-block:: clj
 
-   ;; bad (and evil)
+   ;; Bad (and evil)
    (defn foo (x) (print x))
    (foo 1)
 
-
+   ;; Good (and preferred)
-works is just because the compiler isn't overly strict. In reality,
-the correct syntax in places such as this is:
-
-.. code-block:: clj
-
-   ;; good (and preferred):
    (defn foo [x] (print x))
    (foo 1)
 
 
-+ Threading Macro
++ Use the threading macro or the threading tail macros when encountering
-
+  deeply nested s-expressions. However, be judicious when using them. Do
-  Use the threading macro or the threading tail macros when
+  use them when clarity and readability improves; do not construct
-  encountering deeply nested s-expressions
+  convoluted, hard to understand expressions.
 
 .. code-block:: clj
 
-  ;; preferred
+   ;; Preferred
-  (def *names*
-    (with [f (open "names.txt")]
-	  (-> (.read f) (.strip) (.replace "\"" "") (.split ",") (sorted))))
-
-   ;; not so good
    (def *names*
      (with [f (open "names.txt")]
-	 (sorted (.spilt "," (.replace "\"" "" (.strip (.read f)))))))
+       (-> (.read f) (.strip) (.replace "\"" "") (.split ",") (sorted))))
 
+   ;; Not so good
+   (def *names*
+     (with [f (open "names.txt")]
+     (sorted (.spilt "," (.replace "\"" "" (.strip (.read f)))))))
 
-However be judicious when using them, do use them when clarity and
+   ;; Probably not a good idea
-readability improves. Do not construct convoluted hard to understand
-expressions
-
-.. code-block:: clj
-
-   ;; This is probably not a good idea
    (defn square? [x]
      (->> 2 (pow (int (sqrt x))) (= x)))
 
 
-+ Dot Notation
++ Clojure-style dot notation is preferred over the direct call of
-
+  the object's method, though both will continue to be supported.
-  The clojure style dot notation is preferred over the direct call of
-  the object's method, though both will continue to be supported
 
 .. code-block:: clj
 
-   ;; good:
+   ;; Good
    (with [fd (open "/etc/passwd")]
        (print (.readlines fd)))
 
-   ;; not so good:
+   ;; Not so good
    (with [fd (open "/etc/passwd")]
        (print (fd.readlines)))
 
@@ -221,14 +204,14 @@ expressions
 Conclusion
 ==========
 
-  “Fashions fade, style is eternal”
+   “Fashions fade, style is eternal”
-  —Yves Saint Laurent
+   —Yves Saint Laurent
 
 
-This guide is just a set of community guidelines, obviously community
+This guide is just a set of community guidelines, and obviously, community
-guidelines do not make sense without an active
+guidelines do not make sense without an active community. Contributions are
-community. Contributions are welcome. Join us at #hy in freenode, blog
+welcome. Join us at #hy in freenode, blog about it, tweet about it, and most
-about it, tweet about it, and importantly have fun with Hy
+importantly, have fun with Hy.
 
 
 Thanks