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>

lexicon_filter.in

@@ -46,7 +46,12 @@
     # Then if it's inline. Remove and process immediately...
     /^\\fish.*$/ {
         # Catch @ symbol
-        s/@/(at)/
+        s/@/@at/g
+        # Catch & symbol
+        s/&\([^a-z]\)/@amp\1/g
+        # Catch {{ & }} symbols
+        s/{{/@curlyL/g
+        s/}}/@curlyR/g
         s/^\\fish//
         s/\\endfish//
         b html
@@ -56,7 +61,12 @@
     # Inside \fish block. Process...
     /\\endfish/!{
         # Catch @ symbol
-        s/@/((d))/
+        s/@/@at/g
+        # Catch & symbol
+        s/&\([^a-z]\)/@amp\1/g
+        # Catch {{ & }} symbols
+        s/{{/@curlyL/g
+        s/}}/@curlyR/g
         # Preprocess HTML and HTML-like formatting
         /<[^>]*>/ {
             b html
@@ -103,6 +113,9 @@ s|</i>|}|
 s|<u>|@undr{|
 s|<u [^>]*>|@undr{|
 s|</u>|}|
+# Backslash (when escaping output)
+s|<bs>|@bksl{|
+s|</bs>|}|
 t html
 #.
 # Some handy non-standard extensions
@@ -224,11 +237,11 @@ s/ \\$/ @bksl{ }/
 #.
 # Normal Directory
 s|mkdir |mkdir :|
-s|\([~/:][/]*[.A-Za-z_0-9/-]*\)\\ |\1=|g
-s| \([~/][/]*[.A-Za-z_0-9/=-]*\)| \\\
+s|\([~/:][/]*[.A-Za-z_0-9*/-]*\)\\ |\1=|g
+s| \([~/][/]*[.A-Za-z_0-9*/=-]*\)| \\\
 <@path{\1}\
 |g
-s| \(:[/]*[.A-Za-z_0-9/=-]*\)| \\\
+s| \(:[/]*[.A-Za-z_0-9*/=-]*\)| \\\
 <@path{\1}\
 |g
 t protect
@@ -255,6 +268,7 @@ s|^\([a-zA-Z][{},a-zA-Z0-9%*._/?!-]*\)|@args{\1}|g
 # Pick up loose text after markup.
 s/\([})]\)\([a-zA-Z0-9+%*.,][,a-zA-Z0-9%*._/?!-]*\);/\1@args{\2};/g
 s/\([})]\)\([a-zA-Z0-9+%*.,][,a-zA-Z0-9%*._/?!-]*\)$/\1@args{\2}/g
+s/\([})]\)\([a-zA-Z0-9+%*.,][,a-zA-Z0-9%*._/?!-]*\)@EOL/\1@args{\2}/g
 #.
 # Uncomment the following 2 lines (ss) to log the pattern buffer.
 s/^.*$/Pattern : &/w lexicon.log
@@ -279,6 +293,8 @@ s,\([^\\ ]*\)\\\n\([^<]*\)<\(@[^}]*[}\\]\),\1\3\2,
 t join
 # Clean up stray new lines
 s/\n//g
+# Clean up past @EOL
+s/@EOL.*$//g
 #.
 # Uncomment the folowing two lines (ss) to log the buffer before 'cleaning'.
 s/^.*$/PreClean: &/w lexicon.log
@@ -475,16 +491,17 @@ x
 #.
 # Mark up sesitive character entities.
 #.
-# We comment out this target because it isn't referenced and if we don't we
-# get warnings about "unused label 'entities'".
-#:entities
 s/</\&lt;/g
 s/>/\&gt;/g
-s/((d))/@/g
+s/@amp/\&amp;/g
+s/@curlyL/\{/g
+s/@curlyR/\}/g
+s/@at/@atat{ }/g
 #.
 # Final post processing
 s/};\([^]]\)/}@redr{;}\1/g
 s/};$/}@redr{;}/
+s/@sglq{}/''/
 s/ \[\([@(]\)/ @args{[}\1/g
 s/ \[\([A-Z]*\) / @args{[\1} /g
 s/@args{\([a-zA-Z0-9_.]*\)}\]/@args{\1]}/g
@@ -496,7 +513,9 @@ s/ \]$/ @args{]}/g
 s/\]}\]$/]]}/
 s/\\\([()]\)/@optr{@bksl{\1}}/g
 s/\([()]\)/@optr{\1}/g
+s/\\\\\([cdgnstwx?]\)/@bksl{\1}/g
 s/\\n/@bksl{n}/
+s/%\([diouxXfgGeEsbmy]\)/@pcnt{\1}/g
 s/ \\$//
 #.
 # Uncomment the folowing two lines (ss) to log the final output, sent to Doxygen.
@@ -516,6 +535,8 @@ b
 #.
 # Move protected content to hold space and mark up other entities.
 :protect
+# Add an 'End of Line' marker
+s/$/@EOL/
 s/^.*$/Input   : &/w lexicon.log
 s/^Input   : //
 h
@@ -536,6 +557,7 @@ x
     s/[^\<]*//
     s/^ *\\\n//g
     s/\n *\\//g
+    s/\n@EOL//g
     s/[()] \\//g
     s/^[^\<][^@][^\\]*//
     s/\n[]|;) ][^\\]*\\//
@@ -559,11 +581,13 @@ s/^[a-z][a-z]* \n//
 # Swap the buffers back.
 x
 #.
-# A special case. Tidy up after commands.
+# A special case. Tidy up after performing command substitution.
 # Redirectors
 s/\([^{|] *\)|/\1@redr{|}/g
-s/&$/@redr{\&amp;}/
-s/\([^{&] *\)&[^a-z]/\1@redr{\&amp;}/g
+s/\&@EOL$/@redr{@amp}@EOL/g
+s/@amp@EOL$/@redr{@amp}@EOL/g
+s/\([<>]\)@amp\([0-9]\)/@redr{\1@amp\2}/g
+s/\([^{&] *\)&[^@a-z]/\1@redr{\&amp;}/g
 s/\([^{<>^] *\)\([0-9]* *[<>^][<>^]*[^@][a-zA-Z0-9./_-]*\)/\1@redr{\2}/g
 s/\\}/}\\/g
 #.
@@ -575,11 +599,9 @@ s/[[][0-9$a-zA-Z_;. -]*]/@args{&}/g
 s/\($[$]*\)\([A-Za-z_0-9][A-Za-z_0-9]*\)/@vars{@optr{\1}\2}/g
 #.
 # Files
-s/\([^@]\)\([A-Za-z0-9_-][A-Za-z0-9_-]*\.[a-z0-9*][a-z0-9*]*\)/\1@fsfo{\2}/g
-#.
-# We comment out this target because it isn't referenced and if we don't we
-# get warnings about "unused label 'commands'".
-#:commands
+/@at/ ! {
+    s/\([A-Za-z0-9_*-][A-Za-z0-9_*-]*\.[a-z0-9*][a-z0-9*]*\)/@fsfo{\1}/g
+}
 #.
 #### This section is built in the Makefile. Just some formatting examples. #####
 #.