docs: Enable Syntax Highlighting for Code Snippits

HACKING.md

@@ -11,16 +11,18 @@ The `main` highlighter
 
 The following function `pz` is useful when working on the `main` highlighting:
 
-    pq() {
+```zsh
+pq() {
   (( $#argv )) || return 0
   print -r -l -- ${(qqqq)argv}
-    }
-    pz() {
+}
+pz() {
   local arg
   for arg; do
     pq ${(z)arg}
   done
-    }
+}
+```
 
 It prints, for each argument, its token breakdown, similar to how the main
 loop of the `main` highlighter sees it.
@@ -32,17 +34,19 @@ Since the test harness empties `ZSH_HIGHLIGHT_STYLES` and the `brackets`
 highlighter interrogates `ZSH_HIGHLIGHT_STYLES` to determine how to highlight,
 tests must set the `bracket-level-#` keys themselves.  For example:
 
-    ZSH_HIGHLIGHT_STYLES[bracket-level-1]=
-    ZSH_HIGHLIGHT_STYLES[bracket-level-2]=
+```zsh
+ZSH_HIGHLIGHT_STYLES[bracket-level-1]=
+ZSH_HIGHLIGHT_STYLES[bracket-level-2]=
 
-    BUFFER='echo ({x})'
+BUFFER='echo ({x})'
 
-    expected_region_highlight=(
+expected_region_highlight=(
   "6  6  bracket-level-1" # (
   "7  7  bracket-level-2" # {
   "9  9  bracket-level-2" # }
   "10 10 bracket-level-1" # )
-    )
+)
+```
 
 Testing the `pattern` and `regexp` highlighters
 -----------------------------------------------
@@ -53,20 +57,24 @@ cannot get the `ZSH_HIGHLIGHT_STYLES` keys.  Therefore, when writing tests, use
 the style itself as third word (cf. the
 [documentation for `expected_region_highlight`](docs/highlighters.md)).  For example:
 
-    ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
+```zsh
+ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
 
-    BUFFER='rm -rf /'
+BUFFER='rm -rf /'
 
-    expected_region_highlight=(
+expected_region_highlight=(
   "1 8 fg=white,bold,bg=red" # rm -rf /
-    )
+)
+```
 
 Miscellany
 ----------
 
 If you work on the driver (`zsh-syntax-highlighting.zsh`), you may find the following zstyle useful:
 
-    zstyle ':completion:*:*:*:*:globbed-files' ignored-patterns {'*/',}zsh-syntax-highlighting.plugin.zsh
+```zsh
+zstyle ':completion:*:*:*:*:globbed-files' ignored-patterns {'*/',}zsh-syntax-highlighting.plugin.zsh
+```
 
 IRC channel
 -----------

INSTALL.md

@@ -33,17 +33,23 @@ See also [repology's cross-distro index](https://repology.org/metapackage/zsh-sy
 
 Simply clone this repository and source the script:
 
-    git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
-    echo "source ${(q-)PWD}/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc
+```zsh
+git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
+echo "source ${(q-)PWD}/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc
+```
 
   Then, enable syntax highlighting in the current interactive shell:
 
-    source ./zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
+```zsh
+source ./zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
+```
 
   If `git` is not installed, download and extract a snapshot of the latest
   development tree from:
 
-    https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz
+```
+https://github.com/zsh-users/zsh-syntax-highlighting/archive/master.tar.gz
+```
 
   Note the `source` command must be **at the end** of `~/.zshrc`.
 
@@ -69,11 +75,15 @@ your `.zshrc`.
 
 1. Clone this repository in oh-my-zsh's plugins directory:
 
-       % git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
+    ```zsh
+    git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
+    ```
 
 2. Activate the plugin in `~/.zshrc`:
 
+    ```zsh
     plugins=( [plugins...] zsh-syntax-highlighting)
+    ```
 
 3. Restart zsh (such as by opening a new instance of your terminal emulator).
 
@@ -104,10 +114,14 @@ Any 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
+```zsh
+make install
+```
 
 and directing your users to add
 
-    source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
+```zsh
+source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
+```
 
 to their `.zshrc`s.

changelog.md

@@ -309,50 +309,66 @@ in this area.
 - incomplete sudo commands
   (a3047a912100, 2f05620b19ae)
 
+    ```zsh
     sudo;
     sudo -u;
+    ```
 
 - command words following reserved words
   (#207, #222, b397b12ac139 et seq, 6fbd2aa9579b et seq, 8b4adbd991b0)
 
+    ```zsh
     if ls; then ls; else ls; fi
     repeat 10 do ls; done
+    ```
 
     (The `ls` are now highlighted as a command.)
 
 - comments (when `INTERACTIVE_COMMENTS` is set)
   (#163, #167, 693de99a9030)
 
+    ```zsh
     echo Hello # comment
+    ```
 
 - closing brackets of arithmetic expansion, subshells, and blocks
   (#226, a59f442d2d34, et seq)
 
+    ```zsh
     (( foo ))
     ( foo )
     { foo }
+    ```
 
 - command names enabled by the `PATH_DIRS` option
   (#228, 96ee5116b182)
 
+    ```zsh
     # When ~/bin/foo/bar exists, is executable, ~/bin is in $PATH,
     # and 'setopt PATH_DIRS' is in effect
     foo/bar
+    ```
 
 - parameter expansions with braces inside double quotes
   (#186, 6e3720f39d84)
 
+    ```zsh
     echo "${foo}"
+    ```
 
 - parameter expansions in command word
   (#101, 4fcfb15913a2)
 
+    ```zsh
     x=/bin/ls
     $x -l
+    ```
 
-- the command separators '|&', '&!', '&|'
+- the command separators '\|&', '&!', '&\|'
 
+    ```zsh
     view file.pdf &!  ls
+    ```
 
 
 ## Fixed highlighting of:
@@ -360,23 +376,31 @@ in this area.
 - precommand modifiers at non-command-word position
   (#209, 2c9f8c8c95fa)
 
+    ```zsh
     ls command foo
+    ```
 
 - sudo commands with infix redirections
   (#221, be006aded590, 86e924970911)
 
+    ```zsh
     sudo -u >/tmp/foo.out user ls
+    ```
 
 - subshells; anonymous functions
   (#166, #194, 0d1bfbcbfa67, 9e178f9f3948)
 
+    ```zsh
     (true)
     () { true }
+    ```
 
 - parameter assignment statements with no command
   (#205, 01d7eeb3c713)
 
+    ```zsh
     A=1;
+    ```
 
     (The semicolon used to be highlighted as a mistake)
 
@@ -467,69 +491,95 @@ in this area.
 
 - suffix aliases (requires zsh 5.1.1 or newer):
 
+    ```zsh
     alias -s png=display
     foo.png
+    ```
 
 - prefix redirections:
 
+    ```zsh
     <foo.txt cat
+    ```
 
 - redirection operators:
 
+    ```zsh
     echo > foo.txt
+    ```
 
 - arithmetic evaluations:
 
+    ```zsh
     (( 42 ))
+    ```
 
 - $'' strings, including \x/\octal/\u/\U escapes
 
+    ```zsh
     : $'foo\u0040bar'
+    ```
 
 - multiline strings:
 
+    ```zsh
     % echo "line 1
     line 2"
+    ```
 
 - string literals that haven't been finished:
 
+    ```zsh
     % echo "Hello, world
-
+    ```
 - command words that involve tilde expansion:
 
+    ```zsh
     % ~/bin/foo
-
+    ```
 
 ## Fixed highlighting of:
 
 - quoted command words:
 
+    ```zsh
     % \ls
+    ```
 
 - backslash escapes in "" strings:
 
+    ```zsh
     % echo "\x41"
+    ```
 
 - noglob after command separator:
 
+    ```zsh
     % :; noglob echo *
+    ```
 
 - glob after command separator, when the first command starts with 'noglob':
 
+    ```zsh
     % noglob true; echo *
+    ```
 
 - the region (vi visual mode / set-mark-command) (issue #165)
 
 - redirection and command separators that would be highlighted as `path_approx`
 
+    ```zsh
     % echo foo;‸
     % echo <‸
+    ```
 
     (where `‸` represents the cursor location)
 
 - escaped globbing (outside quotes)
 
+    ```zsh
     % echo \*
+    ```
 
 
 ## Other changes:

docs/highlighters.md

@@ -24,7 +24,9 @@ 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)
+```zsh
+ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern cursor)
+```
 
 By default, `$ZSH_HIGHLIGHT_HIGHLIGHTERS` is unset and only the `main`
 highlighter is active.
@@ -58,10 +60,12 @@ To create your own `acme` highlighter:
   This function must return 0 when the highlighter needs to be called and
   non-zero otherwise, for example:
 
+    ```zsh
     _zsh_highlight_highlighter_acme_predicate() {
       # Call this highlighter in SVN working copies
       [[ -d .svn ]]
     }
+    ```
 
 * Implement the `_zsh_highlight_highlighter_acme_paint` function.
   This function does the actual syntax highlighting, by calling
@@ -71,18 +75,22 @@ To create your own `acme` highlighter:
   `: ${ZSH_HIGHLIGHT_STYLES[key]:=value}`, being sure to prefix
   the key with your highlighter name and a colon. For example:
 
+    ```zsh
     : ${ZSH_HIGHLIGHT_STYLES[acme:aurora]:=fg=green}
 
     _zsh_highlight_highlighter_acme_paint() {
       # Colorize the whole buffer with the 'aurora' style
       _zsh_highlight_add_highlight 0 $#BUFFER acme:aurora
     }
+    ```
 
   If you need to test which options the user has set, test `zsyh_user_options`
   with a sensible default if the option is not present in supported zsh
   versions. For example:
 
+    ```zsh
     [[ ${zsyh_user_options[ignoreclosebraces]:-off} == on ]]
+    ```
 
   The option name must be all lowercase with no underscores and not an alias.
 
@@ -100,6 +108,8 @@ To create your own `acme` highlighter:
 
 * Activate your highlighter in `~/.zshrc`:
 
+    ```zsh
     ZSH_HIGHLIGHT_HIGHLIGHTERS+=(acme)
+    ```
 
 * [Write tests](../tests/README.md).

docs/highlighters/brackets.md

@@ -16,11 +16,13 @@ This highlighter defines the following styles:
 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'
+```zsh
+# 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 values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`

docs/highlighters/cursor.md

@@ -13,7 +13,9 @@ This highlighter defines the following styles:
 To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
 for example in `~/.zshrc`:
 
-    ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
+```zsh
+ZSH_HIGHLIGHT_STYLES[cursor]='bg=blue'
+```
 
 The syntax for values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`

docs/highlighters/line.md

@@ -13,7 +13,9 @@ This highlighter defines the following styles:
 To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
 for example in `~/.zshrc`:
 
-    ZSH_HIGHLIGHT_STYLES[line]='bold'
+```zsh
+ZSH_HIGHLIGHT_STYLES[line]='bold'
+```
 
 The syntax for values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`

docs/highlighters/main.md

@@ -65,17 +65,19 @@ This highlighter defines the following styles:
 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
+```zsh
+# Declare the variable
+typeset -A ZSH_HIGHLIGHT_STYLES
 
-    # To differentiate aliases from other command types
-    ZSH_HIGHLIGHT_STYLES[alias]='fg=magenta,bold'
+# 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 have paths colored instead of underlined
+ZSH_HIGHLIGHT_STYLES[path]='fg=cyan'
 
-    # To disable highlighting of globbing expressions
-    ZSH_HIGHLIGHT_STYLES[globbing]='none'
+# To disable highlighting of globbing expressions
+ZSH_HIGHLIGHT_STYLES[globbing]='none'
+```
 
 The syntax for values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`
@@ -86,7 +88,9 @@ manual page][zshzle-Character-Highlighting].
 To avoid partial path lookups on a path, add the path to the `X_ZSH_HIGHLIGHT_DIRS_BLACKLIST` array.
 This interface is still experimental.
 
-    X_ZSH_HIGHLIGHT_DIRS_BLACKLIST+=(/mnt/slow_share)
+```zsh
+X_ZSH_HIGHLIGHT_DIRS_BLACKLIST+=(/mnt/slow_share)
+```
 
 ### Useless trivia
 

docs/highlighters/pattern.md

@@ -9,11 +9,13 @@ This is the `pattern` highlighter, that highlights user-defined patterns.
 To use this highlighter, associate patterns with styles in the
 `ZSH_HIGHLIGHT_PATTERNS` associative array, for example in `~/.zshrc`:
 
-    # Declare the variable
-    typeset -A ZSH_HIGHLIGHT_PATTERNS
+```zsh
+# Declare the variable
+typeset -A ZSH_HIGHLIGHT_PATTERNS
 
-    # To have commands starting with `rm -rf` in red:
-    ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
+# To have commands starting with `rm -rf` in red:
+ZSH_HIGHLIGHT_PATTERNS+=('rm -rf *' 'fg=white,bold,bg=red')
+```
 
 The syntax for values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`

docs/highlighters/regexp.md

@@ -10,8 +10,10 @@ patterns.
 To use this highlighter, associate regular expressions with styles in the
 `ZSH_HIGHLIGHT_REGEXP` associative array, for example in `~/.zshrc`:
 
-    typeset -A ZSH_HIGHLIGHT_PATTERNS
-    ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
+```zsh
+typeset -A ZSH_HIGHLIGHT_PATTERNS
+ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
+```
 
 This will highlight "sudo" only as a complete word, i.e., "sudo cmd", but not
 "sudoedit"

docs/highlighters/root.md

@@ -14,7 +14,9 @@ This highlighter defines the following styles:
 To override one of those styles, change its entry in `ZSH_HIGHLIGHT_STYLES`,
 for example in `~/.zshrc`:
 
-    ZSH_HIGHLIGHT_STYLES[root]='bg=red'
+```zsh
+ZSH_HIGHLIGHT_STYLES[root]='bg=red'
+```
 
 The syntax for values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`

tests/README.md

@@ -38,17 +38,19 @@ 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. For example:
 
-    setopt PATH_DIRS
-    mkdir -p foo/bar
-    touch foo/bar/testing-issue-228
-    chmod  +x foo/bar/testing-issue-228
-    path+=( "$PWD"/foo )
+```zsh
+setopt PATH_DIRS
+mkdir -p foo/bar
+touch foo/bar/testing-issue-228
+chmod  +x foo/bar/testing-issue-228
+path+=( "$PWD"/foo )
 
-    BUFFER='bar/testing-issue-228'
+BUFFER='bar/testing-issue-228'
 
-    expected_region_highlight=(
+expected_region_highlight=(
   "1 21 command" # bar/testing-issue-228
-    )
+)
+```
 
 
 Writing new tests
@@ -56,7 +58,9 @@ Writing new tests
 
 An experimental tool is available to generate test files:
 
-    zsh -f tests/generate.zsh 'ls -x' acme newfile
+```zsh
+zsh -f tests/generate.zsh 'ls -x' acme newfile
+```
 
 This generates a `highlighters/acme/test-data/newfile.zsh` test file based on
 the current highlighting of the given `$BUFFER` (in this case, `ls -x`).
@@ -71,11 +75,15 @@ Highlighting test
 [`test-highlighting.zsh`](tests/test-highlighting.zsh) tests the correctness of
 the highlighting. Usage:
 
-    zsh test-highlighting.zsh <HIGHLIGHTER NAME>
+```zsh
+zsh test-highlighting.zsh <HIGHLIGHTER NAME>
+```
 
 All tests may be run with
 
-    make test
+```zsh
+make test
+```
 
 which will run all highlighting tests and report results in [TAP format][TAP].
 By default, the results of all tests will be printed; to show only "interesting"
@@ -91,8 +99,12 @@ Performance test
 [`test-perfs.zsh`](tests/test-perfs.zsh) measures the time spent doing the
 highlighting. Usage:
 
-    zsh test-perfs.zsh <HIGHLIGHTER NAME>
+```zsh
+zsh test-perfs.zsh <HIGHLIGHTER NAME>
+```
 
 All tests may be run with
 
-    make perf
+```zsh
+make perf
+```