docs copyedit: Review toplevel and tests README.md files.

README.md

@@ -1,7 +1,7 @@
 zsh-syntax-highlighting
 =======================
 
-**[Fish shell](http://www.fishshell.com) like syntax highlighting for [Zsh](http://www.zsh.org).**
+**[Fish shell](http://www.fishshell.com) like syntax highlighting for Zsh.**
 
 *Requirements: zsh 4.3.17+.*
 
@@ -18,9 +18,15 @@ How to install
 
 ### Using packages
 
-* Arch Linux: [community/zsh-syntax-highlighting](https://www.archlinux.org/packages/zsh-syntax-highlighting) / [AUR/zsh-syntax-highlighting-git](https://aur.archlinux.org/packages/zsh-syntax-highlighting-git)
-* Gentoo: [mv overlay](http://gpo.zugaina.org/app-shells/zsh-syntax-highlighting)
-* Mac OS X / Homebrew: [brew install zsh-syntax-highlighting](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/zsh-syntax-highlighting.rb)
+* Arch Linux: [community/zsh-syntax-highlighting][arch-package] / [AUR/zsh-syntax-highlighting-git][AUR-package]
+* Gentoo: [mv overlay][gentoo-overlay]
+* Mac OS X / Homebrew: [brew install zsh-syntax-highlighting][brew-package]
+
+[arch-package]: https://www.archlinux.org/packages/zsh-syntax-highlighting
+[AUR-package]: https://aur.archlinux.org/packages/zsh-syntax-highlighting-git
+[gentoo-overlay]: http://gpo.zugaina.org/app-shells/zsh-syntax-highlighting
+[brew-package]: https://github.com/Homebrew/homebrew/blob/master/Library/Formula/zsh-syntax-highlighting.rb
+
 
 ### In your ~/.zshrc
 
@@ -28,7 +34,10 @@ How to install
 
         git clone git://github.com/zsh-users/zsh-syntax-highlighting.git
 
-  (or [download a snapshot](https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz))
+  If `git` is not installed, you could download a snapshot of the latest
+  development tree from:
+
+        https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz
 
 * Source the script **at the end** of `~/.zshrc`:
 
@@ -41,21 +50,27 @@ How to install
 
 ### With oh-my-zsh
 
-* Download the script or clone this repository in [oh-my-zsh](http://github.com/robbyrussell/oh-my-zsh) plugins directory:
+Oh-my-zsh is a zsh configuration framework.  It lives at
+<http://github.com/robbyrussell/oh-my-zsh>.
+
+To install zsh-syntax-highlighting under oh-my-zsh:
+
+1. Download the script or clone this repository in oh-my-zsh's plugins directory:
 
         git clone git://github.com/zsh-users/zsh-syntax-highlighting.git ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
 
-* Activate the plugin in `~/.zshrc`:
+2. Activate the plugin in `~/.zshrc`:
 
         plugins=( [plugins...] zsh-syntax-highlighting)
 
-* Source `~/.zshrc`  to take changes into account:
+3. Source `~/.zshrc`  to take changes into account:
 
         source ~/.zshrc
 
 Note that `zsh-syntax-highlighting` must be the last plugin sourced,
 so make it the last element of the `$plugins` array.
 
+
 ### System-wide installation
 
 Either of the above methods is suitable for a single-user installation, which requires
@@ -82,8 +97,10 @@ There is currently no "push" announcements channel.  However, the following alte
 - GitHub's RSS feed of releases: https://github.com/zsh-users/zsh-syntax-highlighting/releases.atom
 - An anitya entry: https://release-monitoring.org/project/7552/
 
+
 How to tweak
 ------------
 
-Syntax highlighting is done by pluggable highlighter scripts, see the [highlighters directory](highlighters)
-for documentation and configuration settings.
+Syntax highlighting is done by pluggable highlighter scripts.  See the
+[`highlighters` directory](./highlighters) for documentation and configuration
+settings.

tests/README.md

@@ -8,12 +8,14 @@ directory with test data files.
 See the [main highlighter](../highlighters/main/test-data) for examples.
 
 Each test should define the array parameter `$expected_region_highlight`.
-The value of that parameter is a list of `"$i $j $style [$todo]"` strings.
+The value of that parameter is a list of strings of the form  `"$i $j $style"`.
+or `"$i $j $style $todo"`.
 Each string specifies the highlighting that `$BUFFER[$i,$j]` should have;
 that is, `$i` and `$j` specify a range, 1-indexed, inclusive of both endpoints.
-If `$todo` exists, the test point is marked as TODO (the failure of that test point will not fail the test), and `$todo` is used as the explanation.
+If `$todo` exists, the test point is marked as TODO (the failure of that test
+point will not fail the test), and `$todo` is used as the explanation.
 
-_Note_: `$region_highlight` uses the same `"$i $j $style"` syntax but interprets the indexes differently.
+**Note**: `$region_highlight` uses the same `"$i $j $style"` syntax but interprets the indexes differently.
 
 **Isolation**: Each test is run in a separate subshell, so any variables, aliases, functions, etc.,
 it defines will be visible to the tested code (that computes `$region_highlight`), but will not affect