Merge remote-tracking branch 'danielsh/docs-copyedit-v1'

* danielsh/docs-copyedit-v1:
  docs copyedit: minor: Spelling/punctuation fix.
  docs copyedit: Rewrap to 80 columns, part 4.
  docs copyedit: Rewrap to 80 columns, part 3.
  docs copyedit: Rewrap to 80 columns, part 2.
  docs copyedit: Clarify tagline.
  docs copyedit: minor.
  docs copyedit: Review toplevel and tests README.md files.
  docs copyedit: Rewrap to 80 columns.
  docs copyedit: Restyle bold-italic to fixed-width.
  docs copyedit: Port 6d93ea07fd to the other highlighters' README's.
  docs copyedit: Whitespace.

README.md

@@ -1,10 +1,13 @@
 zsh-syntax-highlighting
 =======================
 
-**[Fish shell](http://www.fishshell.com) like syntax highlighting for [Zsh](http://www.zsh.org).**
+**[Fish shell][fish]-like like syntax highlighting for [Zsh][zsh].**
 
 *Requirements: zsh 4.3.17+.*
 
+[fish]: http://www.fishshell.com/
+[zsh]: http://www.zsh.org/
+
 This package provides syntax highlighing for the shell zsh.  It enables
 highlighing of commands whilst they are typed at a zsh prompt into an
 interactive terminal.  This helps in reviewing commands before running
@@ -18,9 +21,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)
+* Arch Linux: [community/zsh-syntax-highlighting][arch-package] / [AUR/zsh-syntax-highlighting-git][AUR-package]
-* Gentoo: [mv overlay](http://gpo.zugaina.org/app-shells/zsh-syntax-highlighting)
+* Gentoo: [mv overlay][gentoo-overlay]
-* Mac OS X / Homebrew: [brew install zsh-syntax-highlighting](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/zsh-syntax-highlighting.rb)
+* 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 +37,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,27 +53,34 @@ 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. 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
+Either of the above methods is suitable for a single-user installation,
-no special privileges.  If, however, you desire to install zsh-syntax-highlighting
+which requires no special privileges.  If, however, you desire to install
-system-wide, you may do so by running `make install` and directing your users to
+zsh-syntax-highlighting system-wide, you may do so by running `make install`
-add `source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh`
+and directing your users to add
+  `source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh`
 in their `.zshrc`s.
 
 
@@ -77,13 +96,16 @@ syntax highlighting.
 
 ### How are new releases announced?
 
-There is currently no "push" announcements channel.  However, the following alternatives exist:
+There is currently no "push" announcements channel.  However, the following
+alternatives exist:
 
 - 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)
+Syntax highlighting is done by pluggable highlighter scripts.  See the
-for documentation and configuration settings.
+[`highlighters` directory](./highlighters) for documentation and configuration
+settings.

highlighters/README.md

@@ -3,18 +3,19 @@ zsh-syntax-highlighting / highlighters
 
 Syntax highlighting is done by pluggable highlighters:
 
-* [***main***](main) - the base highlighter, and the only one active by default.
+* [`main`](main) - the base highlighter, and the only one active by default.
-* [***brackets***](brackets) - matches brackets and parenthesis.
+* [`brackets`](brackets) - matches brackets and parenthesis.
-* [***pattern***](pattern) - matches user-defined patterns.
+* [`pattern`](pattern) - matches user-defined patterns.
-* [***cursor***](cursor) - matches the cursor position.
+* [`cursor`](cursor) - matches the cursor position.
-* [***root***](root) - triggered if the current user is root.
+* [`root`](root) - triggered if the current user is root.
-* [***line***](line) - applied to the whole command line
+* [`line`](line) - applied to the whole command line
 
 
 How to activate highlighters
 ----------------------------
 
-To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in `~/.zshrc`, for example:
+To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in
+`~/.zshrc`, for example:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor)
 
@@ -22,23 +23,31 @@ To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in
 How to tweak highlighters
 -------------------------
 
-Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` array. Navigate into each highlighter directory to see what styles it defines and how to configure it.
+Highlighters look up styles from the `ZSH_HIGHLIGHT_STYLES` array.
+Navigate into each highlighter directory to see what styles it defines
+and how to configure it.
 
 
 How to implement a new highlighter
 ----------------------------------
 
-To create your own ***myhighlighter*** highlighter:
+To create your own `myhighlighter` highlighter:
 
-* Create your script at **highlighters/*myhighlighter*/*myhighlighter*-highlighter.zsh**.
+* Create your script at
-* Implement the `_zsh_highlight_myhighlighter_highlighter_predicate` function. This function must return 0 when the highlighter needs to be called and non-zero otherwise, for example:
+    `highlighters/${myhighlighter}/${myhighlighter}-highlighter.zsh`.
+
+* Implement the `_zsh_highlight_myhighlighter_highlighter_predicate` function.
+  This function must return 0 when the highlighter needs to be called and
+  non-zero otherwise, for example:
 
         _zsh_highlight_myhighlighter_highlighter_predicate() {
           # Call this highlighter in SVN repositories
           [[ -d .svn ]]
         }
 
-* Implement the `_zsh_highlight_myhighlighter_highlighter` function. This function does the actual syntax highlighting, by modifying `region_highlight`, for example:
+* Implement the `_zsh_highlight_myhighlighter_highlighter` function.
+  This function does the actual syntax highlighting, by modifying
+  `region_highlight`, for example:
 
         _zsh_highlight_myhighlighter_highlighter() {
           # Colorize the whole buffer with blue background

highlighters/brackets/README.md

@@ -1,11 +1,13 @@
 zsh-syntax-highlighting / highlighters / brackets
 =================================================
 
-This is the ***brackets*** highlighter, that highlights brackets, parenthesis and matches them.
+This is the `brackets` highlighter, that highlights brackets and parentheses, and
+matches them.
 
 
 How to activate it
 ------------------
+
 To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] brackets)
@@ -13,13 +15,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
 How to tweak it
 ---------------
+
 This highlighter defines the following styles:
 
 * `bracket-error` - unmatched brackets
 * `bracket-level-N` - brackets with nest level N
 * `cursor-matchingbracket` - the matching bracket, if cursor is on a bracket
 
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for example in `~/.zshrc`:
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
 
     # To define styles for nested brackets up to level 4
     ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold'
@@ -27,4 +31,5 @@ To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for
     ZSH_HIGHLIGHT_STYLES[bracket-level-3]='fg=yellow,bold'
     ZSH_HIGHLIGHT_STYLES[bracket-level-4]='fg=magenta,bold'
 
-The syntax for declaring styles is [documented here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/cursor/README.md

@@ -1,11 +1,12 @@
 zsh-syntax-highlighting / highlighters / cursor
-=================================================
+===============================================
 
-This is the ***cursor*** highlighter, that highlights the cursor.
+This is the `cursor` highlighter, that highlights the cursor.
 
 
 How to activate it
 ------------------
+
 To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] cursor)
@@ -13,12 +14,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
 How to tweak it
 ---------------
+
 This highlighter defines the following styles:
 
 * `cursor` - the style for the current cursor position
 
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for example in `~/.zshrc`:
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
 
     ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
 
-The syntax for declaring styles is [documented here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/line/README.md

@@ -1,11 +1,12 @@
 zsh-syntax-highlighting / highlighters / line
-=================================================
+=============================================
 
-This is the ***line*** highlighter, that highlights the whole line.
+This is the `line` highlighter, that highlights the whole line.
 
 
 How to activate it
 ------------------
+
 To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] line)
@@ -13,12 +14,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
 How to tweak it
 ---------------
+
 This highlighter defines the following styles:
 
 * `line` - the style for the whole line
 
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for example in `~/.zshrc`:
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
 
     ZSH_HIGHLIGHT_STYLES[line]='bold'
 
-The syntax for declaring styles is [documented here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/main/README.md

@@ -1,7 +1,7 @@
 zsh-syntax-highlighting / highlighters / main
 =============================================
 
-This is the ***main*** highlighter, that highlights:
+This is the `main` highlighter, that highlights:
 
 * Commands
 * Options
@@ -11,6 +11,7 @@ This is the ***main*** highlighter, that highlights:
 
 How to activate it
 ------------------
+
 To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] main)
@@ -20,6 +21,7 @@ This highlighter is active by default.
 
 How to tweak it
 ---------------
+
 This highlighter defines the following styles:
 
 * `unknown-token` - unknown tokens / errors
@@ -50,7 +52,8 @@ This highlighter defines the following styles:
 * `comment` - comments, when `setopt INTERACTIVE_COMMENTS` is in effect (`echo # foo`)
 * `default` - everything else
 
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for example in `~/.zshrc`:
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
 
     # Declare the variable
     typeset -A ZSH_HIGHLIGHT_STYLES

highlighters/pattern/README.md

@@ -1,11 +1,12 @@
 zsh-syntax-highlighting / highlighters / pattern
 ================================================
 
-This is the ***pattern*** highlighter, that highlights user defined patterns.
+This is the `pattern` highlighter, that highlights user defined patterns.
 
 
 How to activate it
 ------------------
+
 To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] pattern)
@@ -13,9 +14,12 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
 How to tweak it
 ---------------
-To use this highlighter, associate patterns with styles in the `ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`:
+
+To use this highlighter, associate patterns with styles in the
+`ZSH_HIGHLIGHT_PATTERNS` array, for example in `~/.zshrc`:
 
     # To have commands starting with `rm -rf` in red:
     ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
 
-The syntax for declaring styles is [documented here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

highlighters/root/README.md

@@ -1,11 +1,13 @@
 zsh-syntax-highlighting / highlighters / root
-=================================================
+=============================================
 
-This is the ***root*** highlighter, that highlights the whole line if the current user is root.
+This is the `root` highlighter, that highlights the whole line if the current
+user is root.
 
 
 How to activate it
 ------------------
+
 To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
     ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] root)
@@ -13,12 +15,15 @@ To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
 
 How to tweak it
 ---------------
+
 This highlighter defines the following styles:
 
 * `root` - the style for the whole line if the current user is root.
 
-To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`, for example in `~/.zshrc`:
+To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
+for example in `~/.zshrc`:
 
     ZSH_HIGHLIGHT_STYLES[root]='bg=red'
 
-The syntax for declaring styles is [documented here](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).
+The syntax for declaring styles is documented in [the `zshzle(1)` manual
+page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135).

tests/README.md

@@ -8,22 +8,28 @@ 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.,
+**Isolation**: Each test is run in a separate subshell, so any variables,
-it defines will be visible to the tested code (that computes `$region_highlight`), but will not affect
+aliases, functions, etc., it defines will be visible to the tested code (that
-subsequent tests.  The current working directory of tests is set to a newly-created empty directory,
+computes `$region_highlight`), but will not affect subsequent tests.  The
+current working directory of tests is set to a newly-created empty directory,
 which is automatically cleaned up after the test exits.
 
 
-highlighting test
+Highlighting test
 -----------------
-[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of the highlighting. Usage:
+
+[`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of
+the highlighting. Usage:
 
     zsh test-highlighting.zsh <HIGHLIGHTER NAME>
 
@@ -31,12 +37,16 @@ All tests may be run with
 
     make test
 
-which will run all highlighting tests and report results in [TAP](http://testanything.org/) format.
+which will run all highlighting tests and report results in [TAP format][TAP].
+
+[TAP]: http://testanything.org/
 
 
-performance test
+Performance test
 ----------------
-[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the highlighting. Usage:
+
+[`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the
+highlighting. Usage:
 
     zsh test-perfs.zsh <HIGHLIGHTER NAME>