update lexicon for latest docs

Closes #2699

Fixes issues with:
* 'string' function synopsis
* Redirection display issues
* Better file & path detection
* Rendering of % & @ chars in both html and man
* @ symbol in tutorial

Improves robustness by implementing an @EOL marker to prevent hold buffer dumping extra chars after the end of an expression.

Added new '{{' and '}}' meta-chars for when you want curly braces in a regexp that was previously tripping up the lexicon.

Improve man/html presentation consistency for
* string
* printf
* prompt_pwd
* type

Use cli-styling for 'practical' examples.

Add <bs> tag for presenting content with preceding backslash.

Signed-off-by: Mark Griffiths <mark@thebespokepixel.com>

8 files changed, 134 insertions, 153 deletions

diff --git a/doc_src/FORMATTING.md b/doc_src/FORMATTING.md
index 0ae1c81e..df6de6f8 100644
--- a/doc_src/FORMATTING.md
+++ b/doc_src/FORMATTING.md
@@ -160,6 +160,8 @@ The following can be used in \\fish blocks to render some fish scenarios. These
 - `<error>`: \<error\>This would be shown as an error.\</error\>
 - `<asis>`: \<asis\>This test will not be parsed for fish markup.\</asis\>
 - `<outp>`: \<outp\>This would be rendered as command/script output.\</outp\>
+- `<bs>`: Render the contents with a preceding backslash. Useful when presenting output.
+- `{{` and `}}`: Required when wanting curly braces in regular expression example.
 
 ### Prompts and cursors
 
diff --git a/doc_src/fish_right_prompt.txt b/doc_src/fish_right_prompt.txt
index 21b4a195..87de3113 100644
--- a/doc_src/fish_right_prompt.txt
+++ b/doc_src/fish_right_prompt.txt
@@ -20,7 +20,7 @@ A simple right prompt:
 
 \fish
 function fish_right_prompt -d "Write out the right prompt"
-    date "+%m/%d/%y"
+    date '+%m/%d/%y'
 end
 \endfish
 
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index 15c67c37..a42fb649 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -528,22 +528,24 @@ The above code demonstrates how to use multiple '`$`' symbols to expand the valu
 Lists adjacent to other lists or strings are expanded as cartesian products:
 
 Examples:
-\fish
-echo {good,bad}" apples"
-# Outputs 'good apples bad apples'
+\fish{cli-dark}
+>_ echo {good,bad}" apples"
+<outp>good apples bad apples</outp>
+
+>_ set -l a x y z
+>_ set -l b 1 2 3
+
+>_ echo $a$b
+<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
 
-set -l a x y z
-set -l b 1 2 3
-echo $a$b
-# Outputs 'x1 y1 z1 x2 y2 z2 x3 y3 z3'
-echo $a"-"$b
-# Outputs 'x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3'
+>_ echo $a"-"$b
+<outp>x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3</outp>
 
-echo {x,y,z}$b
-# Outputs 'x1 y1 z1 x2 y2 z2 x3 y3 z3'
+>_ echo {x,y,z}$b
+<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
 
-echo {$b}word
-# Outputs '1word 2word 3word'
+>_ echo {$b}word
+<outp>1word 2word 3word</outp>
 \endfish
 
 Be careful when you try to use braces to separate variable names from text. The dangers noted in the last example above can be avoided by wrapping the variable in double quotes instead of braces (`echo "$b"word`).
diff --git a/doc_src/printf.txt b/doc_src/printf.txt
index ce7796c8..5e22db98 100644
--- a/doc_src/printf.txt
+++ b/doc_src/printf.txt
@@ -60,7 +60,7 @@ This file has been imported from the printf in GNU Coreutils version 6.9. If you
 \subsection printf-example Example
 
 \fish
-printf '\%s\\t\%s\n' flounder fish
+printf '%s\\t%s\\n' flounder fish
 \endfish
 Will print "flounder	fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.
 
diff --git a/doc_src/prompt_pwd.txt b/doc_src/prompt_pwd.txt
index 7161d8aa..0eafbf99 100644
--- a/doc_src/prompt_pwd.txt
+++ b/doc_src/prompt_pwd.txt
@@ -13,16 +13,19 @@ To change the number of characters per path component, set $fish_prompt_pwd_dir_
 
 \subsection prompt_pwd-example Examples
 
-\fish
+\fish{cli-dark}
 >_ cd ~/
 >_ echo $PWD
-/home/alfa
+<outp>/home/alfa</outp>
+
 >_ prompt_pwd
-~
+<outp>~</outp>
+
 >_ cd /tmp/banana/sausage/with/mustard
 >_ prompt_pwd
-/t/b/s/w/mustard
+<outp>/t/b/s/w/mustard</outp>
+
 >_ set -g fish_prompt_pwd_dir_length 3
 >_ prompt_pwd
-/tmp/ban/sau/wit/mustard
+<outp>/tmp/ban/sau/wit/mustard</outp>
 \endfish
diff --git a/doc_src/string.txt b/doc_src/string.txt
index 37d24435..fd77da94 100644
--- a/doc_src/string.txt
+++ b/doc_src/string.txt
@@ -3,18 +3,13 @@
 \subsection string-synopsis Synopsis
 \fish{synopsis}
 string length [(-q | --quiet)] [STRING...]
-string sub [(-s | --start) START] [(-l | --length) LENGTH]
-           [(-q | --quiet)] [STRING...]
-string split [(-m | --max) MAX] [(-r | --right)] [(-q | --quiet)]
-             SEP [STRING...]
+string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] [STRING...]
+string split [(-m | --max) MAX] [(-r | --right)] [(-q | --quiet)] SEP [STRING...]
 string join [(-q | --quiet)] SEP [STRING...]
-string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)]
-            [(-q | --quiet)] [STRING...]
+string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...]
 string escape [(-n | --no-quoted)] [STRING...]
-string match [(-a | --all)] [(-i | --ignore-case)] [(-r | --regex)]
-             [(-n | --index)] [(-q | --quiet)] PATTERN [STRING...]
-string replace [(-a | --all)] [(-i | --ignore-case)] [(-r | --regex)]
-               [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]
+string match [(-a | --all)] [(-i | --ignore-case)] [(-r | --regex)] [(-n | --index)] [(-q | --quiet)] PATTERN [STRING...]
+string replace [(-a | --all)] [(-i | --ignore-case)] [(-r | --regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]
 \endfish
 
 
@@ -51,150 +46,129 @@ The following subcommands are available:
 
 \subsection string-example Examples
 
-\fish
-string length 'hello, world'
-# Output:
-# 12
+\fish{cli-dark}
+>_ string length 'hello, world'
+<outp>12</outp>
 
-string length -q $str
+>_ set str foo
+>_ string length -q $str; echo $status
+1
 # Equivalent to test -n $str
 \endfish
 
-\fish
-string sub --length 2 abcde
-# Output:
-# ab
+\fish{cli-dark}
+>_ string sub --length 2 abcde
+<outp>ab</outp>
 
-string sub -s 2 -l 2 abcde
-# Output:
-# bc
+>_ string sub -s 2 -l 2 abcde
+<outp>bc</outp>
 
-string sub --start=-2 abcde
-# Output:
-# de
+>_ string sub --start=-2 abcde
+<outp>de</outp>
 \endfish
 
-\fish
-string split . example.com
-# Output:
-# example
-# com
-
-string split -r -m1 / /usr/local/bin/fish
-# Output:
-# /usr/local/bin
-# fish
-
-string split '' abc
-# Output:
-# a
-# b
-# c
+\fish{cli-dark}
+>_ string split . example.com
+<outp>example</outp>
+<outp>com</outp>
+
+>_ string split -r -m1 / /usr/local/bin/fish
+<outp>/usr/local/bin</outp>
+<outp>fish</outp>
+
+>_ string split '' abc
+<outp>a</outp>
+<outp>b</outp>
+<outp>c</outp>
 \endfish
 
-\fish
-seq 3 | string join ...
-# Output:
-# 1...2...3
+\fish{cli-dark}
+>_ seq 3 | string join ...
+<outp>1...2...3</outp>
 \endfish
 
-\fish
-string trim ' abc  '
-# Output:
-# abc
+\fish{cli-dark}
+>_ string trim ' abc  '
+<outp>abc</outp>
 
-string trim --right --chars=yz xyzzy zany
-# Output:
-# x
-# zan
+>_ string trim --right --chars=yz xyzzy zany
+<outp>x</outp>
+<outp>zan</outp>
 \endfish
 
-\fish
-echo \x07 | string escape
-# Output:
-# \\cg
+\fish{cli-dark}
+>_ echo \\x07 | string escape
+<bs>c</bs>g
 \endfish
 
-\fish
-# string match glob examples
-
-string match '?' a
-# Output:
-# a
-
-string match 'a*b' axxb
-# Output:
-# axxb
-
-string match -i 'a??B' Axxb
-# Output:
-# Axxb
-
-echo 'ok?' | string match '*\\?'
-# Output:
-# ok?
-
-# string match regex examples
-
-string match -r 'cat|dog|fish' 'nice dog'
-# Output:
-# dog
-
-string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56
-# Output:
-# 2:34:56
-# 2
-# 34
-# 56
-
-string match -r '^(\\w{2,4})\\g1$' papa mud murmur
-# Output:
-# papa
-# pa
-# murmur
-# mur
-
-string match -r -a -n at ratatat
-# Output:
-# 2 2
-# 4 2
-# 6 2
-
-string match -r -i '0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;'
-# Output:
-# 0xBadC0de
+\subsection string-example-match-glob Match Glob Examples
+
+\fish{cli-dark}
+>_ string match '?' a
+<outp>a</outp>
+
+>_ string match 'a*b' axxb
+<outp>axxb</outp>
+
+>_ string match -i 'a??B' Axxb
+<outp>Axxb</outp>
+
+>_ echo 'ok?' | string match '*\\?'
+>_ <outp>ok?</outp>
 \endfish
 
-\fish
+\subsection string-example-match-regex Match Regex Examples
+
+\fish{cli-dark}
+>_ string match -r 'cat|dog|fish' 'nice dog'
+<outp>dog</outp>
 
-# string replace literal examples
+>_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' <asis>2:34:56</asis>
+<outp>2:34:56</outp>
+<outp>2</outp>
+<outp>34</outp>
+<outp>56</outp>
 
-string replace is was 'blue is my favorite'
-# Output:
-# blue was my favorite
+>_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur
+<outp>papa</outp>
+<outp>pa</outp>
+<outp>murmur</outp>
+<outp>mur</outp>
 
-string replace 3rd last 1st 2nd 3rd
-# Output:
-# 1st
-# 2nd
-# last
+>_ string match -r -a -n at ratatat
+<outp>2 2</outp>
+<outp>4 2</outp>
+<outp>6 2</outp>
 
-string replace -a ' ' _ 'spaces to underscores'
-# Output:
-# spaces_to_underscores
+>_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;'
+<outp>0xBadC0de</outp>
+\endfish
+
+\subsection string-example-replace-literal Replace Literal Examples
+
+\fish{cli-dark}
+>_ string replace is was 'blue is my favorite'
+<outp>blue was my favorite</outp>
+
+>_ string replace 3rd last 1st 2nd 3rd
+<outp>1st</outp>
+<outp>2nd</outp>
+<outp>last</outp>
+
+>_ string replace -a ' ' _ 'spaces to underscores'
+<outp>spaces_to_underscores</outp>
+\endfish
 
-# string replace regex examples
+\subsection string-example-replace-Regex Replace Regex Examples
 
-string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x'
-# Output:
-# 0 3.14 5
+\fish{cli-dark}
+>_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x'
+<outp>0 3.14 5</outp>
 
-string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right'
-# Output:
-# right left $
+>_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right'
+<outp>right left $</outp>
 
-string replace -r '\\s*newline\\s*' '\n' 'put a newline here'
-# Output:
-# put a
-# here
+>_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here'
+<outp>put a</outp>
+<outp>here</outp>
 \endfish
diff --git a/doc_src/type.txt b/doc_src/type.txt
index 2f55d72a..2da88c94 100644
--- a/doc_src/type.txt
+++ b/doc_src/type.txt
@@ -26,7 +26,7 @@ The following options are available:
 
 \subsection type-example Example
 
-\fish
-type fg
-# Outputs the string 'fg is a shell builtin'.
+\fish{cli-dark}
+>_ type fg
+<outp>fg is a builtin</outp>
 \endfish
diff --git a/doc_src/user_doc.css b/doc_src/user_doc.css
index ba1362e2..2ac484ca 100644
--- a/doc_src/user_doc.css
+++ b/doc_src/user_doc.css
@@ -174,8 +174,8 @@ tt, code, pre, .fish {
 .comment, .suggest { color: #555; }
 .command, .function, .binary { color: #223aa4; }
 .argument, .path, .file  { color: #5961cf; }
-.string { color: #6c6d08; }
 .operator, .variable, .match, .history { color: #1c8885; }
+.string, .string .operator { color: #858904; }
 
 /* Synopsis variant */
 .synopsis {