Merge remote-tracking branch 'phy1729/doc-all'

* phy1729/doc-all:
  Remove broken links
  docs: Create all.md
  docs: Move docs into docs/
  docs: Remove duplicate 'How to activate it' sections
  docs: Move highlighter headers down one level

.gitignore

@@ -1,2 +1,3 @@
 *.zwc*
 .pc/
+docs/all.md

Makefile

@@ -6,11 +6,13 @@ SHARE_DIR?=$(DESTDIR)$(PREFIX)/share/$(NAME)
 DOC_DIR?=$(DESTDIR)$(PREFIX)/share/doc/$(NAME)
 ZSH?=zsh # zsh binary to run tests with
 
-# Have the default target do nothing.
 all:
-	@ :
+	cd docs && \
+	cp highlighters.md all.md && \
+	printf '\n\nIndividual highlighters documentation\n=====================================' >> all.md && \
+	for doc in highlighters/*.md; do printf '\n\n'; cat "$$doc"; done >> all.md
 
-install:
+install: all
 	$(INSTALL) -d $(SHARE_DIR)
 	$(INSTALL) -d $(DOC_DIR)
 	cp .version zsh-syntax-highlighting.zsh $(SHARE_DIR)
@@ -25,10 +27,12 @@ install:
 # equivalent of) NONOMATCH in effect, and highlighters/*.zsh has no matches.
 	for dirname in highlighters highlighters/*/ ; do \
 		$(INSTALL) -d $(SHARE_DIR)/"$$dirname"; \
-		$(INSTALL) -d $(DOC_DIR)/"$$dirname"; \
 		for fname in "$$dirname"/*.zsh ; do [ -e "$$fname" ] && cp "$$fname" $(SHARE_DIR)"/$$dirname"; done; \
-		for fname in "$$dirname"/*.md ; do  [ -e "$$fname" ] && cp "$$fname" $(DOC_DIR)"/$$dirname"; done; \
 	done
+	cp -R docs/* $(DOC_DIR)
+
+clean:
+	rm -f docs/all.md
 
 test:
 	@result=0; \
@@ -52,4 +56,4 @@ perf:
 	done; \
 	exit $$result
 
-.PHONY: all install test perf
+.PHONY: all install clean test perf

docs/highlighters.md

@@ -0,0 +1,59 @@
+zsh-syntax-highlighting / highlighters
+======================================
+
+Syntax highlighting is done by pluggable highlighters:
+
+* `main` - the base highlighter, and the only one active by default.
+* `brackets` - matches brackets and parenthesis.
+* `pattern` - matches user-defined patterns.
+* `cursor` - matches the cursor position.
+* `root` - triggered if the current user is root.
+* `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)

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).

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).

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).

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).

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).

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).

highlighters/README.md

@@ -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)

highlighters/README.md

@@ -0,0 +1 @@
+../docs/highlighters.md

highlighters/brackets/README.md

@@ -1,35 +0,0 @@
-zsh-syntax-highlighting / highlighters / brackets
-=================================================
-
-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)
-
-
-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).

highlighters/brackets/README.md

@@ -0,0 +1 @@
+../docs/highlighters/brackets.md

highlighters/cursor/README.md

@@ -1,28 +0,0 @@
-zsh-syntax-highlighting / highlighters / 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)
-
-
-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).

highlighters/cursor/README.md

@@ -0,0 +1 @@
+../docs/highlighters/cursor.md

highlighters/line/README.md

@@ -1,28 +0,0 @@
-zsh-syntax-highlighting / highlighters / 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)
-
-
-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).

highlighters/line/README.md

@@ -0,0 +1 @@
+../docs/highlighters/line.md

highlighters/main/README.md

@@ -1,71 +0,0 @@
-zsh-syntax-highlighting / highlighters / main
-=============================================
-
-This is the `main` highlighter, that highlights:
-
-* Commands
-* Options
-* Arguments
-* Paths
-* Strings
-
-How to activate it
-------------------
-
-To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
-
-    ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] main)
-
-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).

highlighters/main/README.md

@@ -0,0 +1 @@
+../docs/highlighters/main.md

highlighters/pattern/README.md

@@ -1,25 +0,0 @@
-zsh-syntax-highlighting / highlighters / pattern
-================================================
-
-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)
-
-
-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).

highlighters/pattern/README.md

@@ -0,0 +1 @@
+../docs/highlighters/pattern.md

highlighters/root/README.md

@@ -1,29 +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 activate it
-------------------
-
-To activate it, add it to `ZSH_HIGHLIGHT_HIGHLIGHTERS`:
-
-    ZSH_HIGHLIGHT_HIGHLIGHTERS=( [...] 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).

highlighters/root/README.md

@@ -0,0 +1 @@
+../docs/highlighters/root.md