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 6d93ea07fd61 to the other highlighters' README's. docs copyedit: Whitespace.
This commit is contained in:
Daniel Shahaf
commit
c575f8f375
52
README.md
52
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)
|
||||
* 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.
|
||||
|
||||
@ -3,7 +3,7 @@ up to 1933de83be0bbfb41c44d182fe581ad85012b71a
|
||||
|
||||
|
||||
|
||||
# Changes in version 0.3.1
|
||||
# Changes in version 0.3.1
|
||||
|
||||
|
||||
## Added highlighting of:
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user