Merged in latest changes to docs and formatting tweaks

Addresses issue #1557 as well as fixing many typos, HTML errors and
inconsistencies. Also introduces automatic syntax colouring and enables
new documentation to be written in Markdown. TODO fix Tutorial.

4 files changed, 66 insertions, 25 deletions

diff --git a/Makefile.in b/Makefile.in
index ca4a33ab..39cbd8d7 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -388,7 +388,8 @@ doc_src/fish_lexicon_filter: lexicon.txt doc_src/fish_lexicon_filter.in
 	sed <$@.in >$@.tmp -e 's|@sed@|'"`command -v sed`"'|' -e '/^[ ]*#[^!]/d'
 	# Scan through the lexicon, transforming each line to something usefue to Doxygen.
 	sed <lexicon.txt >>$@.tmp -n \
-		-e 's|^\([a-z][a-z][a-z][a-z]\) \([a-z_-]*\)$$|s,[[:<:]]\2[[:>:]],@\1{\2},g|p';
+		-e 's|^\([a-z][a-z][a-z][a-z]\) \([a-z_-]*\)$$|s,[[:<:]]\2[[:>:]],@\1{\2},g|p' \
+		-e '$$G;s/.*\n/b tidy/p'; \
 	mv $@.tmp $@; if test -x $@; then true; else chmod a+x $@; fi
 
 #
diff --git a/doc_src/fish_lexicon_filter.in b/doc_src/fish_lexicon_filter.in
index 47ee345e..8a8c46b2 100644
--- a/doc_src/fish_lexicon_filter.in
+++ b/doc_src/fish_lexicon_filter.in
@@ -7,8 +7,8 @@
 # by Mark Griffiths <mark@thebespokepixel.com>             *but quite portable
 #.
 # Finds /fish../endfish blocks in documentation source files and enhances
-# markup. Requires that the short tags declared here are added to Doxyfiles as
-# aliases i.e.:
+# markup. Requires that the four character word 'classes' declared here are
+# added to Doxyfiles as aliases i.e.:
 #.
 # Enhance for HTML Help pages (Doxyfile.user)…
 # ALIASES   = "fish=\htmlonly[block] \n<pre class=\"fish\">"
@@ -26,6 +26,16 @@
 # ALIASES  += "blah{1}=\1"
 # ALIASES  += "cmnd{1}=<em>\1</em>"...
 #.
+# It's meant to only ever be run once, during make, as Doxygen's 'INPUT
+# FILTER', though can be run interactively by passing a file in via stdin. It
+# wont respond to arguments.
+#.
+# It's most easily tested by passing test strings into the compiled script:
+#.
+# echo "Line to test" | ./fish_lexicon_filter
+#.
+# The, at times, archiac looking regex is down to ensuring portable sed BREs
+#.
 # Licensed under whatever terms are most compatible with Fish's GPLv2 license,
 # bascially free to use/reuse/redistribute/laugh at/be inspired by. Don't
 # pretend it's your code unless you've spent more late nights on it than me but
@@ -35,9 +45,10 @@
 #.
 # Pattern flow control for scanning doc.h
 /\\fish/,/\\endfish/ {
-    # Open \fish block
+    # Open \fish block, firstly it it's on it's own line
     /^\\fish$/b
     /^\\fish{[^}]*}$/b
+    # Then if it's inline. Remove and process immediately...
     /^\\fish.*$/ {
         s/^\\fish//
         s/\\endfish//
@@ -172,6 +183,7 @@ s|\([^/~A-Za-z0-9]\)\([~/][/]*\)\([A-Za-z_0-9./-]*\)|\1\\\
 |g
 #.
 b protect
+#.
 # Tidy up. Merge back 'pure' entities from hold space.
 :tidy
 #.
@@ -207,6 +219,7 @@ s/\n//g
     s/\(redr{[^@]*\)@func{\([^}]*\)}/\1\2/
     s/\(redr{[^@]*\)@sbin{\([^}]*\)}/\1\2/
     s/\(redr{[^@]*\)@fsfo{\([^}]*\)}/\1\2/
+    s/\(redr{[^}]*\)}\( *\)@path{\([^}]*\)/\1\2\3/
     t cleanredr
 }
 /@fsfo/{
@@ -216,13 +229,44 @@ s/\n//g
     s/\(fsfo{[^@]*\)@sbin{\([^}]*\)}/\1\2/
     t cleanfsfo
 }
-# Convert 2nd order commands/functions and binaries to arguments
-s/@cmnd/@args/g
-s/@args/@cmnd/1
+#.
+# Finally, restructure to follow Fish's command [arguments] semantics.
+# Find the initial command, and change any others to arguments, up to a ( or ;
+# Assumes that a valid line will start with either a builtin, a function or a binary.
+#.
+:nextcmnd
+s/@cmnd\(.*\)$/@xcmd\
+\1/
+t castargs
+s/@func\(.*\)$/@xfnc\
+\1/
+t castargs
+s/@sbin\(.*\)$/@xbin\
+\1/
+t castargs
+b cleancmd
+:castargs
+s/\n\([^;(]*[;(]\)/\1/
+t nextcmnd
+s/\n\([^@]*\)@cmnd\(.*\)/\1@args\
+\2/
+t castargs
+s/\n\([^@]*\)@func\(.*\)/\1@args\
+\2/
+t castargs
+s/\n\([^@]*\)@sbin\(.*\)/\1@args\
+\2/
+t castargs
+:cleancmd
+s/xcmd/cmnd/g
+s/xfnc/func/g
+s/xbin/sbin/g
+s/\n//g
 # Character Entities
 #.
 # Mark up a few sesitive characters.
 #.
+:entities
 s/</\&lt;/g
 s/>/\&gt;/g
 #.
@@ -274,12 +318,9 @@ s/\([$%][$%]*\)\([A-Za-z_0-9][A-Za-z_0-9]*\)/@vars{@optr{\1}\2}/g
 # Files
 s/\([A-Za-z*][A-Za-z]*\.[a-z0-9][a-z0-9]*\)/@fsfo{\1}/g
 #.
-# Operators
-# s/\([^^=|+*&%<>{-]\)\([=|+*&%<>^-][|+*&%<>^-]*\)\([^0-9A-Za-z]\)/\1@optr{\2}\3/g
-#.
 :commands
 #.
-# Manually add a few commands not harvested from source.
+# Manually add a few commands not harvested from source files.
 #.
 s,[[:<:]]in[[:>:]],@args{in},g
 s,[[:<:]]whoami[[:>:]],@sbin{whoami},g
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index 95b1559c..526954fc 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -605,8 +605,8 @@ end
 function avast
     set phrase 'Avast, mateys'
 
-    # Calling the shiver function here can not change any variables
-    # in the local scope
+    # Calling the shiver function here can not
+    # change any variables in the local scope
     shiver
 
     echo $phrase
diff --git a/doc_src/user_doc.css b/doc_src/user_doc.css
index d2f00642..abe70835 100644
--- a/doc_src/user_doc.css
+++ b/doc_src/user_doc.css
@@ -30,7 +30,6 @@ body {
     position: relative;
     width: 100%;
     height: 3.6rem;
-    overflow: hidden;
 }
 /* Don't show the header */
 .header { display: none; }
@@ -45,7 +44,7 @@ body {
     bottom: 0;
     overflow-y: scroll;
     -webkit-overflow-scrolling: touch; /* necessary for momentum scrolling */
-    font: 400 1.4rem/2.3rem "DejaVuSans", Roboto, "Helvetica Neue", Helvetica, Arial, sans-serif;
+    font: 400 1.3rem/2.1rem "DejaVuSans", Roboto, "Helvetica Neue", Helvetica, Arial, sans-serif;
 }
 .fish_left_bar {
     width: 250px;
@@ -54,16 +53,14 @@ body {
     background-color: #1f2d53;
 }
 .fish_left_little { width: 200px; }
-.fish_left_big { width: 380px; }
 .fish_right_bar {
     margin-left: 250px;
     margin-right: 0;
     padding: 0 3rem;
     -moz-box-shadow: -6px 0 6px 4px black;
     -webkit-box-shadow: -6px 0 6px 4px black;
-    box-shadow: -0.6rem 0 0.6rem 0.4rem rgba(0,0,0,0.4);
+    box-shadow: -0.3rem 0.3rem 1rem #000818;
 }
-.fish_right_little { margin-left: 380px; }
 .fish_right_big { margin-left: 200px; }
 .fish_only_bar {
     width: 100%;
@@ -90,7 +87,7 @@ a { color: #3d5cb3; }
 .fish_right_bar a:hover { text-decoration: underline; }
 /* Adjust lists */
 .fish_left_bar ul {
-    padding-left: 2rem;
+    padding-left: 1.4rem;
     padding-right: 1rem;
 }
 .fish_right_bar ul {
@@ -111,22 +108,23 @@ h1, h2, h3, h4, h5, h6 {
     font-family: Roboto, "DejaVuSansCondensed-Bold", "DejaVuSans-Bold", Verdana, sans-serif;
 }
 h1 {
-    margin: 2rem 0 1.4rem 0;
+    margin: 1.6rem 0 1rem 0;
     font-weight: 700;
-    font-size: 2rem;
+    font-size: 1.7rem;
 }
 h2 {
     margin: 1.6rem 0 1rem 0;
-    font-weight: 600;
+    font-weight: 700;
     font-size: 1.7rem;
 }
 h3 {
     margin: 1rem 0 0.4rem 0;
     font-weight: 500;
-    font-size: 1.6rem;
+    font-size: 1.5rem;
 }
 .interior_title {
     font-size: 2rem;
+    margin: 2rem 0 1.4rem 0;
     color: #414141;
     padding-bottom: 10px;
     border-bottom: 1px solid #AAA;
@@ -167,8 +165,9 @@ h1 > code, h2 > code, h3 > code {
     font-weight: 700;
 }
 .fish {
-    margin: 1rem;
-    padding: 0.4rem 1rem;
+    margin: 1rem 0;
+    padding: 0.6rem 1rem;
+    font-size: 1.3rem;
     line-height: 1.9rem;
     background-color: #fafafa;
     border: 1px solid #f0f0f0;