zsh-syntax-highlighting/README.md

zsh-syntax-highlighting
=======================

**[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
them, particularly in catching syntax errors.

[![Screenshot](images/preview-smaller.png)](images/preview.png)


How to install
--------------

See [INSTALL.md](INSTALL.md).


FAQ
---

### Why must `zsh-syntax-highlighting.zsh` be sourced at the end of the `.zshrc` file?

`zsh-syntax-highlighting.zsh` wraps ZLE widgets.  It must be sourced after all
custom widgets have been created (i.e., after all `zle -N` calls and after
running `compinit`).  Widgets created later will work, but will not update the
syntax highlighting.

### Does syntax highlighting work during incremental history search?

Highlighting the command line during an incremental history search
(with the `history-incremental-search-backward` widget, which is
bound by default to <kbd>Ctrl+R</kbd> in zsh's emacs keymap) requires zsh 5.3
or newer.

Under zsh 5.2 and older, the zsh-default [underlining][zshzle-Character-Highlighting]
of the matched portion of the buffer remains available, but zsh-syntax-highlighting's
additional highlighting is unavailable.  (Those versions of zsh do not provide
enough information to allow computing the highlighting correctly.)

See [issue #288][i288] for details.

[zshzle-Character-Highlighting]: http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting
[i288]: https://github.com/zsh-users/zsh-syntax-highlighting/pull/288

### How are new releases announced?

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
[documentation on highlighters](docs/highlighters.md) for details and
configuration settings.
-												Big refactoring.

* Don't override user defined styles
* Better modularisation of highlighters
* Allow to define which highlighters are activated
* Allow to define the order in which they are defined
* Minor performance optimizations
* Fixed some variables leak
* Improve documentation
* Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array

											
										
										
											2011-06-13 04:57:14 +08:00
+								zsh-syntax-highlighting
 								=======================
-												Add README

											
										
										
											2010-12-26 01:47:12 +08:00
-												docs copyedit: Clarify tagline.

Restore zsh URL removed a few commits ago.

											
										
										
											2015-11-17 11:47:11 +08:00
+								**[Fish shell][fish]-like like syntax highlighting for [Zsh][zsh].**
-												Update README

											
										
										
											2011-01-06 06:07:22 +08:00
-												#110: Now using :A modifier, bump zsh version requirement
											
										
										
											2013-12-24 19:40:35 +08:00
+								*Requirements: zsh 4.3.17+.*
-												Add README

											
										
										
											2010-12-26 01:47:12 +08:00
-												docs copyedit: Clarify tagline.

Restore zsh URL removed a few commits ago.

											
										
										
											2015-11-17 11:47:11 +08:00
+								[fish]: http://www.fishshell.com/
 								[zsh]: http://www.zsh.org/
-												README.md += overview description paragraph

Based on text by Carsten Hey <carsten@debian.org>.

											
										
										
											2015-10-20 22:56:10 +08:00
+								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
 								them, particularly in catching syntax errors.
-												Add screenshot.

preview-smaller.png is derived from preview.png by 50% downscaling.

Prior art: https://github.com/zsh-readable/zsh-readable/commit/66c18e6b71d5ed1a95bea481e2d6982fd1a3e560

											
										
										
											2015-10-24 17:43:25 +08:00
+								[![Screenshot](images/preview-smaller.png)](images/preview.png)
-												Issue 7: Add instructions for using with oh-my-zsh

											
										
										
											2010-12-30 23:35:55 +08:00
-												Big refactoring.

* Don't override user defined styles
* Better modularisation of highlighters
* Allow to define which highlighters are activated
* Allow to define the order in which they are defined
* Minor performance optimizations
* Fixed some variables leak
* Improve documentation
* Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array

											
										
										
											2011-06-13 04:57:14 +08:00
+								How to install
 								--------------
-												Add "copy-pastable" installation instructions

											
										
										
											2010-12-26 05:10:50 +08:00
-												docs: Split README.md into INSTALL.md.

Fixes zsh-users/zsh-syntax-highlighting#235.

											
										
										
											2015-11-24 15:05:41 +08:00
+								See [INSTALL.md](INSTALL.md).
-												README: Document 'make install'.

Fixes zsh-users/zsh-syntax-highlighting#218.

											
										
										
											2015-10-23 12:45:18 +08:00
-												README: give the rationale for the at-end-of-.zshrc requirement

											
										
										
											2015-01-26 17:08:31 +08:00
+								FAQ
 								---
 								### Why must `zsh-syntax-highlighting.zsh` be sourced at the end of the `.zshrc` file?
 								`zsh-syntax-highlighting.zsh` wraps ZLE widgets.  It must be sourced after all
-												README: Expand the at-end-of-.zshrc FAQ answer.

Fixes zsh-users/zsh-syntax-highlighting#185.

											
										
										
											2015-09-25 02:45:35 +08:00
+								custom widgets have been created (i.e., after all `zle -N` calls and after
 								running `compinit`).  Widgets created later will work, but will not update the
 								syntax highlighting.
-												README: give the rationale for the at-end-of-.zshrc requirement

											
										
										
											2015-01-26 17:08:31 +08:00
-												README: Rephrase a question non-negatively^W neutrally.

											
										
										
											2016-08-17 01:08:47 +08:00
+								### Does syntax highlighting work during incremental history search?
-												driver: Don't highlight in isearch

zsh version 5.2 and lower don't support ISEARCHMATCH_ACTIVE and
we are unable to re-apply zle_highlight on top. Therefore it is
impossible to see the underlined matched area.

Since that information is more important, completely disable
highlighting in isearch in that case.

To do that, we need to make sure we are actually called when
something changes in isearch.

Trumps #257.

The FAQ entry presupposes #245 will be fixed (in time for the release) too.

											
										
										
											2016-03-30 04:13:46 +08:00
 								Highlighting the command line during an incremental history search
 								(with the `history-incremental-search-backward` widget, which is
 								bound by default to <kbd>Ctrl+R</kbd> in zsh's emacs keymap) requires zsh 5.3
 								or newer.
-												noop: Rewrap.

											
										
										
											2016-08-17 01:09:42 +08:00
+								Under zsh 5.2 and older, the zsh-default [underlining][zshzle-Character-Highlighting]
 								of the matched portion of the buffer remains available, but zsh-syntax-highlighting's
 								additional highlighting is unavailable.  (Those versions of zsh do not provide
 								enough information to allow computing the highlighting correctly.)
-												driver: Don't highlight in isearch

zsh version 5.2 and lower don't support ISEARCHMATCH_ACTIVE and
we are unable to re-apply zle_highlight on top. Therefore it is
impossible to see the underlined matched area.

Since that information is more important, completely disable
highlighting in isearch in that case.

To do that, we need to make sure we are actually called when
something changes in isearch.

Trumps #257.

The FAQ entry presupposes #245 will be fixed (in time for the release) too.

											
										
										
											2016-03-30 04:13:46 +08:00
 								See [issue #288][i288] for details.
-												README: Add a reference to upstream's documentation.

											
										
										
											2016-08-17 01:09:04 +08:00
+								[zshzle-Character-Highlighting]: http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting
-												driver: Don't highlight in isearch

zsh version 5.2 and lower don't support ISEARCHMATCH_ACTIVE and
we are unable to re-apply zle_highlight on top. Therefore it is
impossible to see the underlined matched area.

Since that information is more important, completely disable
highlighting in isearch in that case.

To do that, we need to make sure we are actually called when
something changes in isearch.

Trumps #257.

The FAQ entry presupposes #245 will be fixed (in time for the release) too.

											
										
										
											2016-03-30 04:13:46 +08:00
+								[i288]: https://github.com/zsh-users/zsh-syntax-highlighting/pull/288
-												README: Document release announcements.

Thanks to tibbs@fedora for setting up anitya.

											
										
										
											2015-09-25 06:58:22 +08:00
+								### How are new releases announced?
-												docs copyedit: Rewrap to 80 columns, part 2.

											
										
										
											2015-11-17 11:02:39 +08:00
+								There is currently no "push" announcements channel.  However, the following
 								alternatives exist:
-												README: Document release announcements.

Thanks to tibbs@fedora for setting up anitya.

											
										
										
											2015-09-25 06:58:22 +08:00
 								- 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/
-												docs copyedit: Review toplevel and tests README.md files.

											
										
										
											2015-11-17 11:02:39 +08:00
-												Big refactoring.

* Don't override user defined styles
* Better modularisation of highlighters
* Allow to define which highlighters are activated
* Allow to define the order in which they are defined
* Minor performance optimizations
* Fixed some variables leak
* Improve documentation
* Brackets highlighter: use ZSH_HIGHLIGHT_STYLES instead of a specific array

											
										
										
											2011-06-13 04:57:14 +08:00
+								How to tweak
 								------------
-												Update README

											
										
										
											2011-01-06 06:07:22 +08:00
-												docs copyedit: Review toplevel and tests README.md files.

											
										
										
											2015-11-17 11:02:39 +08:00
+								Syntax highlighting is done by pluggable highlighter scripts.  See the
-												docs: Followup to the recent docs branch: clean up some internal cross-references.

											
										
										
											2015-11-27 01:33:21 +08:00
+								[documentation on highlighters](docs/highlighters.md) for details and
 								configuration settings.