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.
This commit is contained in:
Daniel Shahaf 2015-11-24 06:30:30 +00:00
commit c575f8f375
10 changed files with 125 additions and 59 deletions

View file

@ -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)
* 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 +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
no special privileges. If, however, you desire to install zsh-syntax-highlighting
system-wide, you may do so by running `make install` and directing your users to
add `source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh`
Either of the above methods is suitable for a single-user installation,
which requires no special privileges. If, however, you desire to install
zsh-syntax-highlighting system-wide, you may do so by running `make install`
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)
for documentation and configuration settings.
Syntax highlighting is done by pluggable highlighter scripts. See the
[`highlighters` directory](./highlighters) for documentation and configuration
settings.

View file

@ -3,7 +3,7 @@ up to 1933de83be0bbfb41c44d182fe581ad85012b71a
# Changes in version 0.3.1
# Changes in version 0.3.1
## Added highlighting of:

View file

@ -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.
* [***brackets***](brackets) - matches brackets and parenthesis.
* [***pattern***](pattern) - matches user-defined patterns.
* [***cursor***](cursor) - matches the cursor position.
* [***root***](root) - triggered if the current user is root.
* [***line***](line) - applied to the whole command line
* [`main`](main) - the base highlighter, and the only one active by default.
* [`brackets`](brackets) - matches brackets and parenthesis.
* [`pattern`](pattern) - matches user-defined patterns.
* [`cursor`](cursor) - matches the cursor position.
* [`root`](root) - triggered if the current user is root.
* [`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**.
* 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:
* Create your script at
`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

View file

@ -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).

View file

@ -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).

View file

@ -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).

View file

@ -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

View file

@ -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).

View file

@ -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).

View file

@ -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.,
it defines will be visible to the tested code (that computes `$region_highlight`), but will not affect
subsequent tests. The current working directory of tests is set to a newly-created empty directory,
**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 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>