shells: move shells into own group

4 files changed, 0 insertions, 913 deletions

diff --git a/src/tools/README.md b/src/tools/README.md
index 89b6c39..41584d0 100644
--- a/src/tools/README.md
+++ b/src/tools/README.md
@@ -1,8 +1,5 @@
 # Tools
 
-- [zsh](./zsh.md)
-- [bash](./bash.md)
-- [fish](./fish.md)
 - [tmux](./tmux.md)
 - [git](./git.md)
 - [awk](./awk.md)
diff --git a/src/tools/bash.md b/src/tools/bash.md
deleted file mode 100644
index f27b3a2..0000000
--- a/src/tools/bash.md
+++ /dev/null
@@ -1,259 +0,0 @@
-# bash(1)
-
-## Expansion
-
-### Generator
-
-```bash
-# generate sequence from n to m
-{n..m}
-# generate sequence from n to m step by s
-{n..m..s}
-
-# expand cartesian product
-{a,b}{c,d}
-```
-
-### Parameter
-```bash
-# default value
-bar=${foo:-some_val}  # if $foo set, then bar=$foo else bar=some_val
-
-# alternate value
-bar=${foo:+bla $foo}  # if $foo set, then bar="bla $foo" else bar=""
-
-# check param set
-bar=${foo:?msg}  # if $foo set, then bar=$foo else exit and print msg
-
-# indirect
-FOO=foo
-BAR=FOO
-bar=${!BAR}  # deref value of BAR -> bar=$FOO
-
-# prefix
-${foo#prefix}  # remove prefix when expanding $foo
-# suffix
-${foo%suffix}  # remove suffix when expanding $foo
-
-# substitute
-${foo/pattern/string}  # replace pattern with string when expanding foo
-# pattern starts with
-# '/'   replace all occurences of pattern
-# '#'   pattern match at beginning
-# '%'   pattern match at end
-
-# set programmatically with priintf builtin
-printf -v "VAR1" "abc"
-NAME=VAR2
-printf -v "$NAME" "%s" "def"
-```
-
-> Note: `prefix`/`suffix`/`pattern` are expanded as [pathnames](#pathname).
-
-### Pathname
-
-```bash
-*           match any string
-?           match any single char
-\\          match backslash
-[abc]       match any char of 'a' 'b' 'c'
-[a-z]       match any char between 'a' - 'z'
-[^ab]       negate, match all not 'a' 'b'
-[:class:]   match any char in class, available:
-              alnum,alpha,ascii,blank,cntrl,digit,graph,lower,
-              print,punct,space,upper,word,xdigit
-```
-
-With `extglob` shell option enabled it is possible to have more powerful
-patterns. In the following `pattern-list` is one ore more patterns separated
-by `|` char.
-
-```bash
-?(pattern-list)   matches zero or one occurrence of the given patterns
-*(pattern-list)   matches zero or more occurrences of the given patterns
-+(pattern-list)   matches one or more occurrences of the given patterns
-@(pattern-list)   matches one of the given patterns
-!(pattern-list)   matches anything except one of the given patterns
-```
-> Note: `shopt -s extglob`/`shopt -u extglob` to enable/disable `extglob`
-> option.
-
-## I/O redirection
-
-> Note: The trick with bash I/O redirection is to interpret from left-to-right.
-
-```bash
-# stdout & stderr to file
-command >file 2>&1
-# equivalent
-command &>file
-
-# stderr to stdout & stdout to file
-command 2>&1 >file
-```
-> The article [Bash One-Liners Explained, Part III: All about
-> redirections](https://catonmat.net/bash-one-liners-explained-part-three)
-> contains some nice visualization to explain bash redirections.
-
-### Explanation
-
-```bash
-j>&i
-```
-Duplicate `fd i` to `fd j`, making `j` a copy of `i`. See [dup2(2)][dup2].
-
-Example:
-```bash
-command 2>&1 >file
-```
-1. duplicate `fd 1` to `fd 2`, effectively redirecting `stderr` to `stdout`
-2. redirect `stdout` to `file`
-
-## Process substitution ([ref][psub])
-
-Process substitution allows to redirect the stdout of multiple processes at
-once.
-```bash
-vim -d <(grep foo bar) <(grep foo moose)
-```
-
-## Command grouping
-
-Execute commands in a group with or without subshell. Can be used to easily
-redirect stdout/stderr of all commands in the group into one file.
-```bash
-# Group commands without subshell.
-v=abc ; { v=foo; echo $v; } ; echo $v
-# foo
-# foo
-
-# Group commands with subshell.
-v=abc ; ( v=foo; echo $v; ) ; echo $v
-# foo
-# abc
-```
-
-## Argument parsing with `getopts`
-
-The `getopts` builtin uses following global variables:
-- `OPTARG`, value of last option argument
-- `OPTIND`, index of the next argument to process (user must reset)
-- `OPTERR`, display errors if set to `1`
-
-```bash
-getopts <optstring> <param> [<args>]
-```
-- `<optstring>` specifies the names of supported options, eg `f:c`
-  - `f:` means `-f` option with an argument
-  - `c` means `-c` option without an argument
-- `<param>` specifies a variable name which `getopts` fills with the last parsed option argument
-- `<args>` optionally specify argument string to parse, by default `getopts` parses `$@`
-
-### Example
-```bash
-#!/bin/bash
-function parse_args() {
-    while getopts "f:c" PARAM; do
-        case $PARAM in
-            f) echo "GOT -f $OPTARG";;
-            c) echo "GOT -c";;
-            *) echo "ERR: print usage"; exit 1;;
-        esac
-    done
-    # users responsibility to reset OPTIND
-    OPTIND=1
-}
-
-parse_args -f xxx -c
-parse_args -f yyy
-```
-
-## Regular Expressions
-
-Bash supports regular expression matching with the binary operator `=~`.
-The match results can be accessed via the `$BASH_REMATCH` variable:
-- `${BASH_REMATCH[0]}` contains the full match
-- `${BASH_REMATCH[1]}` contains match of the first capture group
-
-```bash
-INPUT='title foo : 1234'
-REGEX='^title (.+) : ([0-9]+)$'
-if [[ $INPUT =~ $REGEX ]]; then
-    echo "${BASH_REMATCH[0]}"    # title foo : 1234
-    echo "${BASH_REMATCH[1]}"    # foo
-    echo "${BASH_REMATCH[2]}"    # 1234
-fi
-```
-> **Caution**: When specifying a `regex` in the `[[ ]]` block directly, quotes will be treated as part of the pattern.
-> `[[ $INPUT =~ "foo" ]]` will match against `"foo"` not `foo`!
-
-## Completion
-
-The `complete` builtin is used to interact with the completion system.
-```bash
-complete                    # print currently installed completion handler
-complete -F <func> <cmd>    # install <func> as completion handler for <cmd>
-complete -r <cmd>           # uninstall completion handler for <cmd>
-```
-
-Variables available in completion functions:
-```bash
-# in
-$1              # <cmd>
-$2              # current word
-$3              # privous word
-
-COMP_WORDS      # array with current command line words
-COMP_CWORD      # index into COMP_WORDS with current cursor position
-
-# out
-COMPREPLY       # array with possible completions
-```
-
-The `compgen` builtin is used to generate possible matches by comparing `word`
-against words generated by `option`.
-```bash
-compgen <option> <word>
-
-# usefule options:
-# -W <list>    specify list of possible completions
-# -d           generate list with dirs
-# -f           generate list with files
-# -u           generate list with users
-# -e           generate list with exported variables
-
-# compare "f" against words "foo" "foobar" "bar" and generate matches
-compgen -W "foo foobar bar" "f"
-
-# compare "hom" against file/dir names and generate matches
-compgen -d -f "hom"
-```
-
-### Example
-Skeleton to copy/paste for writing simple completions.
-
-Assume a program `foo` with the following interface:
-```bash
-foo -c green|red|blue -s low|high -f <file> -h
-```
-
-The completion handler could be implemented as follows:
-```bash
-function _foo() {
-    local curr=$2
-    local prev=$3
-
-    local opts="-c -s -f -h"
-    case $prev in
-        -c) COMPREPLY=( $(compgen -W "green red blue" -- $curr) );;
-        -s) COMPREPLY=( $(compgen -W "low high" -- $curr) );;
-        -f) COMPREPLY=( $(compgen -f -- $curr) );;
-        *)  COMPREPLY=( $(compgen -W "$opts" -- $curr) );;
-    esac
-}
-
-complete -F _foo foo
-```
-
-[dup2]: http://man7.org/linux/man-pages/man2/dup.2.html
-[psub]: https://tldp.org/LDP/abs/html/process-sub.html
diff --git a/src/tools/fish.md b/src/tools/fish.md
deleted file mode 100644
index a499e10..0000000
--- a/src/tools/fish.md
+++ /dev/null
@@ -1,280 +0,0 @@
-# fish(1)
-
-## Quick Info
-Fish initialization file `~/.config/fish/config.fish`
-
-Switch between different key bindings:
-- `fish_default_key_bindings` to use default key bindings
-- `fish_vi_key_bindings` to use vi key bindings
-
-## Variables
-Available scopes
-- `local` variable local to a block
-- `global` variable global to shell instance
-- `universal` variable universal to all shell instances + preserved across
-  shell restart
-
-### Set/Unset Variables
-```text
-set <name> [<values>]
-    -l  local scope
-    -g  global scope
-    -U  universal scope
-    -e  erase variable
-    -S  show verbose info
-    -x  export to ENV
-    -u  unexport from ENV
-```
-
-### Special Variables [ref](https://fishshell.com/docs/current/language.html#special-variables)
-```sh
-$status      # exit code of last command
-$pipestatus  # list of exit codes of pipe chain
-
-$fish_pid    # pid of parent fish shell    ($$ in bash)
-$last_pid    # pid of last started process ($! in bash)
-
-$CMD_DURATION   # runtime of last command in ms
-```
-
-### Lists
-In `fish` all variables are lists (start with index `1`, but lists can't
-contain lists.
-```sh
-set foo a b c d
-
-echo $foo[1]      # a
-echo $foo[-1]     # d
-echo $foo[2..3]   # b c
-echo $foo[1 3]    # a c
-```
-
-`$` can be seen as dereference operator.
-```sh
-set foo a; set a 1337
-echo $$foo  # outputs 1337
-```
-
-Cartesian product.
-```sh
-echo file.{h,cc}
-# file.h file.cc
-
-echo {a,b}{1,2}
-# a1 b1 a2 b2
-```
-
-#### `*PATH` [ref](https://fishshell.com/docs/current/language.html#path-variables)
-Lists ending with `PATH` are automatically split at `:` when used and joined
-with `:` when quoted or exported to the environment.
-```sh
-set -x BLA_PATH a:b:c:d
-echo $BLA_PATH           # a b c d
-echo "$BLA_PATH"         # a:b:c:d          (quoted)
-env | grep BLA_PATH      # BLA_PATH=a:b:c:d (env)
-
-set FOO_PATH x y z
-echo $FOO_PATH           # x y z
-echo "$FOO_PATH"         # x:y:z
-```
-
-## Command Handling
-```sh
-# sub-commands are not run in quotes
-echo "ls output: "(ls)
-```
-
-### I/O redirection
-```sh
-# 'noclobber', fail if 'log' already exists
-echo foo >? log
-```
-
-### Process substitution
-Redirect output of multiple processes. Same as `<(..)` in bash.
-```sh
-diff (sort a | psub) (sort b | psub)
-```
-
-## Control Flow
-### `if` / `else`
-```sh
-if grep foo bar
-    # do sth
-else if grep foobar bar
-    # do sth else
-else
-    # do sth else
-end
-```
-
-### `switch`
-```sh
-switch (echo foo)
-case 'foo*'
-    # do start with foo
-case bar dudel
-    # do bar and dudel
-case '*'
-    # do else
-end
-```
-
-### `while` Loop
-```sh
-while true
-    echo foo
-end
-```
-
-### `for` Loop
-```sh
-for f in (ls)
-    echo $f
-end
-```
-
-## Functions
-Function arguments are passed via `$argv` list.
-```sh
-function fn_foo
-    echo $argv
-end
-```
-
-### Autoloading
-When running a command fish attempts to autoload a function. The shell looks
-for `<cmd>.fish` in the locations defined by `$fish_function_path` and loads
-the function lazily if found.
-
-This is the preferred way over monolithically defining all functions in a
-startup script.
-
-### Helper
-```sh
-functions         # list al functions
-functions foo     # describe function 'foo'
-functions -e foo  # erase function 'foo'
-
-funced foo        # edit function 'foo'
-                  # '-e vim' to edit in vim
-```
-
-### Argument parsing and completion
-`argparse` puts options into variables of name `_flag_NAME`.
-
-References:
-- [Argument Handling](https://fishshell.com/docs/current/language.html#argument-handling)
-- [`argparse`](https://fishshell.com/docs/current/cmds/argparse.html)
-- [Writing your own completions](https://fishshell.com/docs/current/completions.html)
-- [`complete`](https://fishshell.com/docs/current/cmds/complete.html)
-
-```sh
-function moose --d "my moose fn"
-    # h/help   : short / long option (boolean)
-    # color    : only long option (boolean)
-    # u/user=  : option with required argument, only last specified is taken
-    # f/file+= : option with required argument, can be specified multiple times
-    #
-    argparse h/help color= u/user= f/file=+ -- $argv
-    or return
-
-    if set -ql _flag_help
-        echo "usage ..."
-        return 0
-    end
-
-    set -ql _flag_file
-    and echo "file=$_flag_file | cnt:" (count $_flag_file)
-
-    set -ql _flag_color
-    and echo "color=$_flag_color"
-
-    set -ql _flag_user
-    and echo "user=$_flag_user"
-end
-
-# Delete all previous defined completions for 'moose'.
-complete -c moose -e
-
-# Don't complete files for command.
-complete -c moose --no-files
-
-# Help completion.
-#   -n specifies a conditions. The completion is only active if the command
-#      returns 0.
-complete -c moose -s h -l help -n "not __fish_contains_opt -s h help" \
-    --description "Print usage help and exit"
-
-# File completion.
-#   -F force complete files (overwrite --no-files).
-#   -r requires argument.
-complete -c moose -s f -l file -F -r \
-    --description "Specify file (can be passed multiple times)"
-
-# Color completion.
-#    -a options for completion.
-#    -x short for -r and --no-files (-f)
-complete -c moose -x -l color -a "red blue" \
-    --description "Specify a color."
-
-# User completion.
-#    -a options for completion. Call a function to generate arguments.
-complete -c moose -x -s u -l user -a "(__fish_complete_users)" \
-    --description "Specify a user"
-```
-
-## Prompt
-The prompt is defined by the output of the `fish_prompt` function.
-```sh
-function fish_prompt
-    set -l cmd_ret
-    echo "> "(pwd) $cmd_ret" "
-end
-```
-> Use `set_color` to manipulate terminal colors and `set_color -c` to print the
-> current colors.
-
-
-## Useful Builtins
-List all builtins with `builtins -n`.
-
-```sh
-# history
-history search <str>   # search history for <str>
-history merge          # merge histories from fish sessions
-
-# list
-count $var             # count elements in list
-
-contains /bin $PATH    # return 0 (true) 1 (false)
-contains -i /bin $PATH # additionally print index on stdout
-
-# string
-string split SEP STRING
-
-# math
-math -b hex 4096       # output dec as hex
-math 0x1000            # output hex as dec
-math "log2(1024)"      # call functions
-math -s0 7/3           # integer division (by default float)
-
-# status
-status -f              # abs path of current file
-```
-
-## Keymaps
-```text
-  Shift-Tab .............. tab-completion with search
-  Alt-Up / Alt-Down ...... search history with token under the cursor
-  Alt-l .................. list content of dir under cursor
-  Alt-p .................. append '2>&1 | less;' to current cmdline
-  Alt-Left / Alt - Right . prevd / nextd, walk dir history
-```
-
-## Debug
-```text
-  status print-stack-trace .. prints function stacktrace (can be used in scripts)
-  breakpoint ................ halt script execution and gives shell (C-d | exit
-                              to continue)
-```
diff --git a/src/tools/zsh.md b/src/tools/zsh.md
deleted file mode 100644
index f702655..0000000
--- a/src/tools/zsh.md
+++ /dev/null
@@ -1,371 +0,0 @@
-# zsh(1)
-
-## Keybindings
-
-Change input mode:
-```zsh
-bindkey -v              change to vi keymap
-bindkey -e              change to emacs keymap
-```
-
-Define key-mappings:
-```zsh
-bindkey                 list mappings in current keymap
-bindkey in-str cmd      create mapping for `in-str` to `cmd`
-bindkey -r in-str       remove binding for `in-str`
-
-# C-v <key>             dump <key> code, which can be used in `in-str`
-# zle -l                list all functions for keybindings
-# man zshzle(1)         STANDARD WIDGETS: get description of functions
-```
-
-Access edit buffer in zle widget:
-```zsh
-$BUFFER       # Entire edit buffer content
-$LBUFFER      # Edit buffer content left to cursor
-$RBUFFER      # Edit buffer content right to cursor
-
-# create zle widget which adds text right of the cursor
-function add-text() {
-    RBUFFER="some text $RBUFFER"
-}
-zle -N add-text
-
-bindkey "^p" add-text
-```
-
-## Parameter
-
-Default value:
-```zsh
-# default value
-echo ${foo:-defval}   # defval
-foo=bar
-echo ${foo:-defval}   # bar
-```
-
-Alternative value:
-```zsh
-echo ${foo:+altval}   # ''
-foo=bar
-echo ${foo:+altval}   # altval
-```
-
-Check variable set, error if not set:
-```zsh
-echo ${foo:?msg}      # print `msg` and return errno `1`
-foo=bar
-echo ${foo:?msg}      # bar
-```
-
-Sub-string `${var:offset:length}`:
-```zsh
-foo=abcdef
-echo ${foo:1:3}       # bcd
-```
-
-Trim prefix `${var#prefix}`:
-```zsh
-foo=bar.baz
-echo ${foo#bar}       # .baz
-```
-
-Trim suffix `${var%suffix}`:
-```zsh
-foo=bar.baz
-echo ${foo%.baz}      # bar
-```
-
-Substitute pattern `${var/pattern/replace}`:
-```zsh
-foo=aabbccbbdd
-echo ${foo/bb/XX}    # aaXXccbbdd
-echo ${foo//bb/XX}   # aaXXccXXdd
-# replace prefix
-echo ${foo/#bb/XX}   # aabbccbbdd
-echo ${foo/#aa/XX}   # XXbbccbbdd
-# replace suffix
-echo ${foo/%bb/XX}   # aabbccbbdd
-echo ${foo/%dd/XX}   # aabbccbbXX
-```
-
-> Note: `prefix`/`suffix`/`pattern` are expanded as pathnames.
-
-## Variables
-
-```zsh
-# Variable with local scope
-local var=val
-
-# Read-only variable
-readonly var=bal
-```
-
-Indexed arrays:
-```zsh
-arr=(aa bb cc dd)
-echo $arr[1]           # aa
-echo $arr[-1]          # dd
-
-arr+=(ee)
-echo $arr[-1]          # ee
-
-echo $arr[1,3]         # aa bb cc
-```
-
-Associative arrays:
-```zsh
-typeset -A arr
-arr[x]='aa'
-arr[y]='bb'
-echo $arr[x]           # aa
-```
-
-Tied arrays:
-```zsh
-typeset -T VEC vec=(1 2 3) '|'
-
-echo $vec              # 1 2 3
-echo $VEC              # 1|2|3
-```
-
-Unique arrays (set):
-```
-typeset -U vec=(1 2 3)
-
-echo $vec             # 1 2 3
-vec+=(1 2 4)
-echo $vec             # 1 2 3 4
-```
-
-### Expansion Flags
-
-Join array to string `j:sep:`:
-```zsh
-foo=(1 2 3 4)
-echo ${(j:-:)foo}     # 1-2-3-4
-echo ${(j:\n:)foo}    # join with new lines
-```
-
-Split string to array `s:sep`:
-```zsh
-foo='1-2-3-4'
-bar=(${(s:-:)foo})    # capture as array
-echo $bar             # 1 2 3 4
-echo $bar[2]          # 2
-```
-
-Upper/Lower case string:
-```zsh
-foo=aaBB
-echo ${(L)foo}        # aabb
-echo ${(U)foo}        # AABB
-```
-
-Key/values in associative arrays:
-```zsh
-typeset -A vec; vec[a]='aa'; vec[b]='bb'
-
-echo ${(k)vec}        # a b
-echo ${(v)vec}        # aa bb
-echo ${(kv)vec}       # a aa b bb
-
-# Iterate over key value pairs.
-for k v in ${(kv)vec)}; do ...; done
-```
-
-## I/O redirections
-
-See [bash - I/O redirection](bash.md#io-redirection)
-
-## Process substitution
-
-Process substitution allows to redirect the stdout of multiple processes at
-once.
-```bash
-vim -d <(grep foo bar) <(grep foo moose)
-```
-
-## Argument parsing with `zparseopts`
-
-```zsh
-zparseopts [-D] [-E] [-A assoc] specs
-```
-Arguments are copied into the associative array `assoc` according to `specs`.
-Each spec is described by an entry as `opt[:][=array]`.
-- `opt` is the option without the `-` char. Passing `-f` is matched against `f`
-  opt, `--long` is matched against `-long`.
-- Using `:` means the option will take an argument.
-- The optional `=array` specifies an alternate storage container where this
-  option should be stored.
-> Documentation can be found in `man zshmodules`.
-
-### Example
-```zsh
-#!/bin/zsh
-function test() {
-    zparseopts -D -E -A opts f=flag o: -long:
-    echo "flag $flag"
-    echo "o    $opts[-o]"
-    echo "long $opts[--long]"
-    echo "pos  $1"
-}
-
-test -f -o OPTION --long LONG_OPT POSITIONAL
-
-# Outputs:
-#   flag -f
-#   o    OPTION
-#   long LONG_OPT
-#   pos  POSITIONAL
-```
-
-## Regular Expressions
-
-Zsh supports regular expression matching with the binary operator `=~`.
-The match results can be accessed via the `$MATCH` variable and
-`$match` indexed array:
-- `$MATCH` contains the full match
-- `$match[1]` contains match of the first capture group
-
-```zsh
-INPUT='title foo : 1234'
-REGEX='^title (.+) : ([0-9]+)$'
-if [[ $INPUT =~ $REGEX ]]; then
-    echo "$MATCH"       # title foo : 1234
-    echo "$match[1]"    # foo
-    echo "$match[2]"    # 1234
-fi
-```
-
-## Completion
-
-### Installation
-
-Completion functions are provided via files and need to be placed in a location
-covered by `$fpath`. By convention the completion files are names as `_<CMD>`.
-
-A completion skeleton for the command `foo`, stored in `_foo`
-```zsh
-#compdef _foo foo
-
-function _foo() {
-    ...
-}
-```
-
-Alternatively one can install a completion function explicitly by calling `compdef <FUNC> <CMD>`.
-
-### Completion Variables
-
-Following variables are available in Completion functions:
-```zsh
-$words              # array with command line in words
-$#words             # number words
-$CURRENT            # index into $words for cursor position
-$words[CURRENT-1]   # previous word (relative to cursor position)
-```
-
-### Completion Functions
-- `_describe`     simple completion, just words + description
-- `_arguments`    sophisticated completion, allow to specify actions
-
-#### Completion with [`_describe`][zsh-comp-fn]
-```zsh
-_describe MSG COMP
-```
-- `MSG` simple string with header message
-- `COMP` array of completions where each entry is `"opt:description"`
-
-```zsh
-function _foo() {
-    local -a opts
-    opts=('bla:desc for bla' 'blu:desc for blu')
-    _describe 'foo-msg' opts
-}
-compdef _foo foo
-
-foo <TAB><TAB>
- -- foo-msg --
-bla  -- desc for bla
-blu  -- desc for blu
-```
-
-#### Completion with [`_arguments`][zsh-comp-fn]
-```zsh
-_arguments SPEC [SPEC...]
-```
-where `SPEC` can have one of the following forms:
-- `OPT[DESC]:MSG:ACTION` for option flags
-- `N:MSG:ACTION` for positional arguments
-
-Available actions
-```zsh
-(op1 op2)   list possible matches
-->VAL       set $state=VAL and continue, `$state` can be checked later in switch case
-FUNC        call func to generate matches
-{STR}       evaluate `STR` to generate matches
-```
-
-### Example
-Skeleton to copy/paste for writing simple completions.
-
-Assume a program `foo` with the following interface:
-```zsh
-foo -c green|red|blue -s low|high -f <file> -d <dir> -h
-```
-
-The completion handler could be implemented as follows in a file called `_foo`:
-```zsh
-#compdef _foo foo
-
-function _foo_color() {
-    local colors=()
-    colors+=('green:green color')
-    colors+=('red:red color')
-    colors+=('blue:blue color')
-    _describe "color" colors
-}
-
-function _foo() {
-    _arguments                              \
-        "-c[define color]:color:->s_color"  \
-        "-s[select sound]:sound:(low high)" \
-        "-f[select file]:file:_files"       \
-        "-d[select dir]:dir:_files -/"      \
-        "-h[help]"
-
-    case $state in
-        s_color) _foo_color;;
-    esac
-}
-```
-
-### Example with optional arguments
-For this example we assume that the command `foo` takes at least three optional
-arguments such as
-```zsh
-foo arg1 arg2 arg3 [argN..]
-```
-
-```zsh
-function _foo() {
-    _arguments              \
-        "1:opt 1:(a b c)"   \
-        ":opt next:(d e f)" \
-        "*:opt all:(u v w)"
-}
-```
-Explanation:
-- `1:MSG:ACTION` sets completion for the **first** optional argument
-- `:MSG:ACTION` sets completion for the **next** optional argument
-- `*:MSG:ACTION` sets completion for the optional argument where none of the
-  previous rules apply, so in our example for `arg3, argN..`.
-
-> `_files` is a zsh builtin utility function to complete files/dirs see
-> - [zsh completion functions][zsh-comp-fn]
-> - [zsh completion utility functions][zsh-comp-utility-fn]
-
-
-[zsh-comp-fn]: http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions
-[zsh-comp-utility-fn]: https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#utility-functions