From 0ab450ae47ef01d9f6d27318f253edddc3899ca1 Mon Sep 17 00:00:00 2001 From: Matthew Martin Date: Tue, 17 Nov 2015 21:11:09 -0600 Subject: [PATCH] docs: Move docs into docs/ --- docs/highlighters.md | 59 ++++++++++++++++++++++++++++++ docs/highlighters/brackets.md | 26 ++++++++++++++ docs/highlighters/cursor.md | 19 ++++++++++ docs/highlighters/line.md | 19 ++++++++++ docs/highlighters/main.md | 63 ++++++++++++++++++++++++++++++++ docs/highlighters/pattern.md | 16 +++++++++ docs/highlighters/root.md | 20 +++++++++++ highlighters/README.md | 60 +------------------------------ highlighters/brackets/README.md | 27 +------------- highlighters/cursor/README.md | 20 +---------- highlighters/line/README.md | 20 +---------- highlighters/main/README.md | 64 +-------------------------------- highlighters/pattern/README.md | 17 +-------- highlighters/root/README.md | 21 +---------- 14 files changed, 229 insertions(+), 222 deletions(-) create mode 100644 docs/highlighters.md create mode 100644 docs/highlighters/brackets.md create mode 100644 docs/highlighters/cursor.md create mode 100644 docs/highlighters/line.md create mode 100644 docs/highlighters/main.md create mode 100644 docs/highlighters/pattern.md create mode 100644 docs/highlighters/root.md mode change 100644 => 120000 highlighters/README.md mode change 100644 => 120000 highlighters/brackets/README.md mode change 100644 => 120000 highlighters/cursor/README.md mode change 100644 => 120000 highlighters/line/README.md mode change 100644 => 120000 highlighters/main/README.md mode change 100644 => 120000 highlighters/pattern/README.md mode change 100644 => 120000 highlighters/root/README.md diff --git a/docs/highlighters.md b/docs/highlighters.md new file mode 100644 index 0000000..cc56f4e --- /dev/null +++ b/docs/highlighters.md @@ -0,0 +1,59 @@ +zsh-syntax-highlighting / highlighters +====================================== + +Syntax highlighting is done by pluggable highlighters: + +* [`main`](highlighters/main.md) - the base highlighter, and the only one active by default. +* [`brackets`](highlighters/brackets.md) - matches brackets and parenthesis. +* [`pattern`](highlighters/pattern.md) - matches user-defined patterns. +* [`cursor`](highlighters/cursor.md) - matches the cursor position. +* [`root`](highlighters/root.md) - triggered if the current user is root. +* [`line`](highlighters/line.md) - 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: + + ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor) + + +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. + + +How to implement a new 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: + + _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: + + _zsh_highlight_myhighlighter_highlighter() { + # Colorize the whole buffer with blue background + region_highlight+=(0 $#BUFFER bg=blue) + } + +* Activate your highlighter in `~/.zshrc`: + + ZSH_HIGHLIGHT_HIGHLIGHTERS+=(myhighlighter) diff --git a/docs/highlighters/brackets.md b/docs/highlighters/brackets.md new file mode 100644 index 0000000..df47d8c --- /dev/null +++ b/docs/highlighters/brackets.md @@ -0,0 +1,26 @@ +zsh-syntax-highlighting / highlighters / brackets +------------------------------------------------- + +This is the `brackets` highlighter, that highlights brackets and parentheses, and +matches them. + + +### 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 define styles for nested brackets up to level 4 + ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold' + ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold' + 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 in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/cursor.md b/docs/highlighters/cursor.md new file mode 100644 index 0000000..3ff6c8e --- /dev/null +++ b/docs/highlighters/cursor.md @@ -0,0 +1,19 @@ +zsh-syntax-highlighting / highlighters / cursor +----------------------------------------------- + +This is the `cursor` highlighter, that highlights the cursor. + + +### 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`: + + ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/line.md b/docs/highlighters/line.md new file mode 100644 index 0000000..ac69f68 --- /dev/null +++ b/docs/highlighters/line.md @@ -0,0 +1,19 @@ +zsh-syntax-highlighting / highlighters / line +--------------------------------------------- + +This is the `line` highlighter, that highlights the whole line. + + +### 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`: + + ZSH_HIGHLIGHT_STYLES[line]='bold' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/main.md b/docs/highlighters/main.md new file mode 100644 index 0000000..bbf87ce --- /dev/null +++ b/docs/highlighters/main.md @@ -0,0 +1,63 @@ +zsh-syntax-highlighting / highlighters / main +--------------------------------------------- + +This is the `main` highlighter, that highlights: + +* Commands +* Options +* Arguments +* Paths +* Strings + +This highlighter is active by default. + + +### How to tweak it + +This highlighter defines the following styles: + +* `unknown-token` - unknown tokens / errors +* `reserved-word` - shell reserved words (`if`, `for`) +* `alias` - aliases +* `suffix-alias` - suffix aliases (requires zsh 5.1.1 or newer) +* `builtin` - shell builtin commands (`shift`, `pwd`, `zstyle`) +* `function` - function names +* `command` - command names +* `precommand` - precommand modifiers (e.g., `noglob`, `builtin`) +* `commandseparator` - command separation tokens (`;`, `&&`) +* `hashed-command` - hashed commands +* `path` - existing filenames +* `path_prefix` - prefixes of existing filenames +* `globbing` - globbing expressions (`*.txt`) +* `history-expansion` - history expansion expressions (`!foo` and `^foo^bar`) +* `single-hyphen-option` - single hyphen options (`-o`) +* `double-hyphen-option` - double hyphen options (`--option`) +* `back-quoted-argument` - backquoted expressions (`` `foo` ``) +* `single-quoted-argument` - single quoted arguments (`` 'foo' ``) +* `double-quoted-argument` - double quoted arguments (`` "foo" ``) +* `dollar-quoted-argument` - dollar quoted arguments (`` $'foo' ``) +* `dollar-double-quoted-argument` - parameter expansion inside double quotes (`$foo` inside `""`) +* `back-double-quoted-argument` - back double quoted arguments (`\x` inside `""`) +* `back-dollar-quoted-argument` - back dollar quoted arguments (`\x` inside `$''`) +* `assign` - parameter assignments +* `redirection` - redirection operators (`<`, `>`, etc) +* `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`: + + # Declare the variable + typeset -A ZSH_HIGHLIGHT_STYLES + + # To differentiate aliases from other command types + ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold' + + # To have paths colored instead of underlined + ZSH_HIGHLIGHT_STYLES[path]='fg=cyan' + + # To disable highlighting of globbing expressions + ZSH_HIGHLIGHT_STYLES[globbing]='none' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/pattern.md b/docs/highlighters/pattern.md new file mode 100644 index 0000000..b0b2b90 --- /dev/null +++ b/docs/highlighters/pattern.md @@ -0,0 +1,16 @@ +zsh-syntax-highlighting / highlighters / pattern +------------------------------------------------ + +This is the `pattern` highlighter, that highlights user defined patterns. + + +### How to tweak it + +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 in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/docs/highlighters/root.md b/docs/highlighters/root.md new file mode 100644 index 0000000..0b1f217 --- /dev/null +++ b/docs/highlighters/root.md @@ -0,0 +1,20 @@ +zsh-syntax-highlighting / highlighters / root +--------------------------------------------- + +This is the `root` highlighter, that highlights the whole line if the current +user is root. + + +### 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`: + + ZSH_HIGHLIGHT_STYLES[root]='bg=red' + +The syntax for declaring styles is documented in [the `zshzle(1)` manual +page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/README.md b/highlighters/README.md deleted file mode 100644 index 0d104cd..0000000 --- a/highlighters/README.md +++ /dev/null @@ -1,59 +0,0 @@ -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 - - -How to activate highlighters ----------------------------- - -To activate an highlighter, add it to the `ZSH_HIGHLIGHT_HIGHLIGHTERS` array in -`~/.zshrc`, for example: - - ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor) - - -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. - - -How to implement a new 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: - - _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: - - _zsh_highlight_myhighlighter_highlighter() { - # Colorize the whole buffer with blue background - region_highlight+=(0 $#BUFFER bg=blue) - } - -* Activate your highlighter in `~/.zshrc`: - - ZSH_HIGHLIGHT_HIGHLIGHTERS+=(myhighlighter) diff --git a/highlighters/README.md b/highlighters/README.md new file mode 120000 index 0000000..7b048c0 --- /dev/null +++ b/highlighters/README.md @@ -0,0 +1 @@ +../docs/highlighters.md \ No newline at end of file diff --git a/highlighters/brackets/README.md b/highlighters/brackets/README.md deleted file mode 100644 index df47d8c..0000000 --- a/highlighters/brackets/README.md +++ /dev/null @@ -1,26 +0,0 @@ -zsh-syntax-highlighting / highlighters / brackets -------------------------------------------------- - -This is the `brackets` highlighter, that highlights brackets and parentheses, and -matches them. - - -### 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 define styles for nested brackets up to level 4 - ZSH_HIGHLIGHT_STYLES[bracket-level-1]='fg=blue,bold' - ZSH_HIGHLIGHT_STYLES[bracket-level-2]='fg=red,bold' - 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 in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/brackets/README.md b/highlighters/brackets/README.md new file mode 120000 index 0000000..d8f3a5a --- /dev/null +++ b/highlighters/brackets/README.md @@ -0,0 +1 @@ +../docs/highlighters/brackets.md \ No newline at end of file diff --git a/highlighters/cursor/README.md b/highlighters/cursor/README.md deleted file mode 100644 index 3ff6c8e..0000000 --- a/highlighters/cursor/README.md +++ /dev/null @@ -1,19 +0,0 @@ -zsh-syntax-highlighting / highlighters / cursor ------------------------------------------------ - -This is the `cursor` highlighter, that highlights the cursor. - - -### 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`: - - ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/cursor/README.md b/highlighters/cursor/README.md new file mode 120000 index 0000000..13f58ef --- /dev/null +++ b/highlighters/cursor/README.md @@ -0,0 +1 @@ +../docs/highlighters/cursor.md \ No newline at end of file diff --git a/highlighters/line/README.md b/highlighters/line/README.md deleted file mode 100644 index ac69f68..0000000 --- a/highlighters/line/README.md +++ /dev/null @@ -1,19 +0,0 @@ -zsh-syntax-highlighting / highlighters / line ---------------------------------------------- - -This is the `line` highlighter, that highlights the whole line. - - -### 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`: - - ZSH_HIGHLIGHT_STYLES[line]='bold' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/line/README.md b/highlighters/line/README.md new file mode 120000 index 0000000..80edd29 --- /dev/null +++ b/highlighters/line/README.md @@ -0,0 +1 @@ +../docs/highlighters/line.md \ No newline at end of file diff --git a/highlighters/main/README.md b/highlighters/main/README.md deleted file mode 100644 index bbf87ce..0000000 --- a/highlighters/main/README.md +++ /dev/null @@ -1,63 +0,0 @@ -zsh-syntax-highlighting / highlighters / main ---------------------------------------------- - -This is the `main` highlighter, that highlights: - -* Commands -* Options -* Arguments -* Paths -* Strings - -This highlighter is active by default. - - -### How to tweak it - -This highlighter defines the following styles: - -* `unknown-token` - unknown tokens / errors -* `reserved-word` - shell reserved words (`if`, `for`) -* `alias` - aliases -* `suffix-alias` - suffix aliases (requires zsh 5.1.1 or newer) -* `builtin` - shell builtin commands (`shift`, `pwd`, `zstyle`) -* `function` - function names -* `command` - command names -* `precommand` - precommand modifiers (e.g., `noglob`, `builtin`) -* `commandseparator` - command separation tokens (`;`, `&&`) -* `hashed-command` - hashed commands -* `path` - existing filenames -* `path_prefix` - prefixes of existing filenames -* `globbing` - globbing expressions (`*.txt`) -* `history-expansion` - history expansion expressions (`!foo` and `^foo^bar`) -* `single-hyphen-option` - single hyphen options (`-o`) -* `double-hyphen-option` - double hyphen options (`--option`) -* `back-quoted-argument` - backquoted expressions (`` `foo` ``) -* `single-quoted-argument` - single quoted arguments (`` 'foo' ``) -* `double-quoted-argument` - double quoted arguments (`` "foo" ``) -* `dollar-quoted-argument` - dollar quoted arguments (`` $'foo' ``) -* `dollar-double-quoted-argument` - parameter expansion inside double quotes (`$foo` inside `""`) -* `back-double-quoted-argument` - back double quoted arguments (`\x` inside `""`) -* `back-dollar-quoted-argument` - back dollar quoted arguments (`\x` inside `$''`) -* `assign` - parameter assignments -* `redirection` - redirection operators (`<`, `>`, etc) -* `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`: - - # Declare the variable - typeset -A ZSH_HIGHLIGHT_STYLES - - # To differentiate aliases from other command types - ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold' - - # To have paths colored instead of underlined - ZSH_HIGHLIGHT_STYLES[path]='fg=cyan' - - # To disable highlighting of globbing expressions - ZSH_HIGHLIGHT_STYLES[globbing]='none' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/main/README.md b/highlighters/main/README.md new file mode 120000 index 0000000..e99df2e --- /dev/null +++ b/highlighters/main/README.md @@ -0,0 +1 @@ +../docs/highlighters/main.md \ No newline at end of file diff --git a/highlighters/pattern/README.md b/highlighters/pattern/README.md deleted file mode 100644 index b0b2b90..0000000 --- a/highlighters/pattern/README.md +++ /dev/null @@ -1,16 +0,0 @@ -zsh-syntax-highlighting / highlighters / pattern ------------------------------------------------- - -This is the `pattern` highlighter, that highlights user defined patterns. - - -### How to tweak it - -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 in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/pattern/README.md b/highlighters/pattern/README.md new file mode 120000 index 0000000..edaff5a --- /dev/null +++ b/highlighters/pattern/README.md @@ -0,0 +1 @@ +../docs/highlighters/pattern.md \ No newline at end of file diff --git a/highlighters/root/README.md b/highlighters/root/README.md deleted file mode 100644 index 0b1f217..0000000 --- a/highlighters/root/README.md +++ /dev/null @@ -1,20 +0,0 @@ -zsh-syntax-highlighting / highlighters / root ---------------------------------------------- - -This is the `root` highlighter, that highlights the whole line if the current -user is root. - - -### 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`: - - ZSH_HIGHLIGHT_STYLES[root]='bg=red' - -The syntax for declaring styles is documented in [the `zshzle(1)` manual -page](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#SEC135). diff --git a/highlighters/root/README.md b/highlighters/root/README.md new file mode 120000 index 0000000..2f69e4a --- /dev/null +++ b/highlighters/root/README.md @@ -0,0 +1 @@ +../docs/highlighters/root.md \ No newline at end of file