From 509d152e5407856ce00833b931ef29c3d98c3573 Mon Sep 17 00:00:00 2001 From: Mark Griffiths Date: Fri, 8 Aug 2014 03:44:37 +0100 Subject: Tutorial auto colouring, Man page and Make fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completely fixes #1557 and the underlying Doxygen changes that caused it. Should make fish docs simpler and more robust, more consistent and generally prettier. todo: - trap unmarked text as arguments in context - test & fix sed portability - see in particular. (so far tested on BSD (Mac) and GNU sed). - test Makefile changes - last round of aesthetic changes and getting that ascii fish in there… --- .gitignore | 5 +- Doxyfile | 44 +++- Doxyfile.help | 79 +++---- Doxyfile.user | 79 +++---- Makefile.in | 26 ++- doc_src/alias.txt | 4 +- doc_src/commands.hdr.in | 4 +- doc_src/design.hdr | 6 +- doc_src/echo.txt | 2 +- doc_src/faq.hdr | 4 +- doc_src/fish.txt | 2 +- doc_src/fish_indent.txt | 2 +- doc_src/fish_lexicon_filter.in | 411 ----------------------------------- doc_src/fish_prompt.txt | 3 +- doc_src/functions.txt | 2 +- doc_src/if.txt | 5 +- doc_src/index.hdr.in | 69 +++--- doc_src/nextd.txt | 2 +- doc_src/psub.txt | 8 +- doc_src/set.txt | 18 +- doc_src/set_color.txt | 2 +- doc_src/source.txt | 7 +- doc_src/trap.txt | 7 +- doc_src/tutorial.hdr | 356 +++++++++++++++--------------- doc_src/type.txt | 6 +- doc_src/user_doc.css | 3 +- doc_src/while.txt | 7 +- lexicon_filter.in | 475 +++++++++++++++++++++++++++++++++++++++++ 28 files changed, 888 insertions(+), 750 deletions(-) delete mode 100644 doc_src/fish_lexicon_filter.in create mode 100644 lexicon_filter.in diff --git a/.gitignore b/.gitignore index 492c5758..2fe2f215 100644 --- a/.gitignore +++ b/.gitignore @@ -30,14 +30,15 @@ share/man/ toc.txt user_doc/ xcuserdata +fish.xccheckout tests/*tmp.* tests/foo.txt FISH-BUILD-VERSION-FILE version messages.pot lexicon.txt -doc_src/fish_lexicon_filter -debug-lexicon.log +lexicon_filter +lexicon-debug.log Fish-Shell.sublime-workspace Fish-Shell.sublime-project diff --git a/Doxyfile b/Doxyfile index 3cd01663..38cbd687 100644 --- a/Doxyfile +++ b/Doxyfile @@ -228,8 +228,48 @@ TAB_SIZE = 8 # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. -ALIASES = "fish=\n
\verbatim" -ALIASES += "endfish=\endverbatim
" +ALIASES = "key{1}=\1" +ALIASES += "key{2}=\1-\2" +ALIASES += "key{3}=\1-\3" +ALIASES += "cursor_key{2}=\2" + +ALIASES += "fish=\htmlonly[block] \n
"
+ALIASES += "fish{1}=\htmlonly[block] \n
"
+ALIASES += "endfish=
\endhtmlonly \n"
+
+ALIASES += "asis{1}=\1"
+ALIASES += "outp{1}=\1"
+ALIASES += "blah{1}=#\1"
+ALIASES += "cmnd{1}=\1"
+ALIASES += "func{1}=\1"
+ALIASES += "sbin{1}=\1"
+ALIASES += "args{1}=\1"
+ALIASES += "opts{1}=\1"
+ALIASES += "vars{1}=\1"
+ALIASES += "optr{1}=\1"
+ALIASES += "redr{1}=\1"
+ALIASES += "fsfo{1}=\1"
+ALIASES += "path{1}=\1"
+ALIASES += "clrv{1}=\1"
+
+ALIASES += "strg{1}=\1"
+ALIASES += "sglq{1}='\1'"
+ALIASES += "dblq{1}=\"\1\""
+
+ALIASES += "prmt=>"
+ALIASES += "prmt{1}=\1>"
+ALIASES += "sgst{1}=\1"
+ALIASES += "mtch{1}=\1"
+ALIASES += "smtc{1}=\1"
+ALIASES += "eror{1}=\1"
+ALIASES += "curs=_"
+ALIASES += "curs{1}=\1"
+
+ALIASES += "bold{1}=\1"
+ALIASES += "emph{1}=\1"
+ALIASES += "undr{1}=\1"
+ALIASES += "span{2}=\2"
+ALIASES += "spcl{2}=\2"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
diff --git a/Doxyfile.help b/Doxyfile.help
index 74673382..7b905572 100644
--- a/Doxyfile.help
+++ b/Doxyfile.help
@@ -230,43 +230,48 @@ TAB_SIZE               = 4
 
 # Simplify Fish output from Doxygen for man pages. (see fish_lexicon_filter)
 
-ALIASES                = "key{1}=\1"
-ALIASES               += "key{2}=\1-\2"
-ALIASES               += "key{3}=\1-\3"
-ALIASES               += "cursor_key{2}=\2"
-
-ALIASES               += "fish=
"
-ALIASES               += "fish{1}=
"
-ALIASES               += "endfish=
"
-
-ALIASES               += "asis{1}=\1"
-ALIASES               += "blah{1}=\1"
-ALIASES               += "cmnd{1}=\b \1"
-ALIASES               += "func{1}=\b \1"
-ALIASES               += "sbin{1}=\b \1"
-ALIASES               += "args{1}=\1"
-ALIASES               += "opts{1}=\1"
-ALIASES               += "vars{1}=\1"
-ALIASES               += "optr{1}=\1"
-ALIASES               += "redr{1}=\1"
-ALIASES               += "fsfo{1}=\1"
-ALIASES               += "path{1}=\1"
-ALIASES               += "clrv{1}=\1"
-
-ALIASES               += "strg{1}=\1"
-ALIASES               += "sglq{1}=\'\1\'"
-ALIASES               += "dblq{1}=\"\1\""
-
-ALIASES               += "prmt{1}=\1"
-ALIASES               += "sgst{1}=\1"
-ALIASES               += "eror{1}=\1"
-ALIASES               += "curs{1}=\1"
-
-ALIASES               += "bold{1}=\1"
-ALIASES               += "emph{1}=\1"
-ALIASES               += "undr{1}=\1"
-ALIASES               += "span{2}=\1"
-ALIASES               += "spcl{2}=\1"
+ALIASES  = "key{1}=\1"
+ALIASES += "key{2}=\1-\2"
+ALIASES += "key{3}=\1-\3"
+ALIASES += "cursor_key{2}=\2"
+
+ALIASES += "fish=
"
+ALIASES += "fish{1}=
"
+ALIASES += "endfish=
"
+
+ALIASES += "asis{1}=\1"
+ALIASES += "outp{1}=\1"
+ALIASES += "blah{1}= \1"
+ALIASES += "cmnd{1}=\1"
+ALIASES += "func{1}=\1"
+ALIASES += "sbin{1}=\1"
+ALIASES += "args{1}=\1"
+ALIASES += "opts{1}=\1"
+ALIASES += "vars{1}=\1"
+ALIASES += "optr{1}=\1"
+ALIASES += "redr{1}=\1"
+ALIASES += "fsfo{1}=\1"
+ALIASES += "path{1}=\1"
+ALIASES += "clrv{1}=\1"
+
+ALIASES += "strg{1}=\1"
+ALIASES += "sglq{1}='\1'"
+ALIASES += "dblq{1}=\"\1\""
+
+ALIASES += "prmt=>"
+ALIASES += "prmt{1}=\1>"
+ALIASES += "sgst{1}=\1"
+ALIASES += "mtch{1}=\1"
+ALIASES += "smtc{1}=\1"
+ALIASES += "eror{1}=\1"
+ALIASES += "curs=_"
+ALIASES += "curs{1}=\1"
+
+ALIASES += "bold{1}=\1"
+ALIASES += "emph{1}=\1"
+ALIASES += "undr{1}=\1"
+ALIASES += "span{2}=\2"
+ALIASES += "spcl{2}=\2"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
diff --git a/Doxyfile.user b/Doxyfile.user
index 09683abd..b1319a78 100644
--- a/Doxyfile.user
+++ b/Doxyfile.user
@@ -230,43 +230,48 @@ TAB_SIZE               = 4
 
 # Enhance Fish docs output from Doxygen. (See fish_lexicon_filter.in)
 
-ALIASES                = "key{1}=\1"
-ALIASES               += "key{2}=\1-\2"
-ALIASES               += "key{3}=\1-\2"
-ALIASES               += "cursor_key{2}=\1"
-
-ALIASES               += "fish=\htmlonly[block] \n
"
-ALIASES               += "fish{1}=\htmlonly[block] \n
"
-ALIASES               += "endfish=
\endhtmlonly \n"
-
-ALIASES               += "asis{1}=\1"
-ALIASES               += "blah{1}=\1"
-ALIASES               += "cmnd{1}=\1"
-ALIASES               += "func{1}=\1"
-ALIASES               += "sbin{1}=\1"
-ALIASES               += "args{1}=\1"
-ALIASES               += "opts{1}=\1"
-ALIASES               += "vars{1}=\1"
-ALIASES               += "optr{1}=\1"
-ALIASES               += "redr{1}=\1"
-ALIASES               += "fsfo{1}=\1"
-ALIASES               += "path{1}=\1"
-ALIASES               += "clrv{1}=\1"
-
-ALIASES               += "strg{1}=\1"
-ALIASES               += "sglq{1}='\1'"
-ALIASES               += "dblq{1}=\"\1\""
-
-ALIASES               += "prmt{1}="
-ALIASES               += "sgst{1}="
-ALIASES               += "eror{1}="
-ALIASES               += "curs{1}="
-
-ALIASES               += "bold{1}=\1"
-ALIASES               += "emph{1}=\1"
-ALIASES               += "undr{1}=\1"
-ALIASES               += "span{2}=\2"
-ALIASES               += "spcl{2}=\2"
+ALIASES  = "key{1}=\1"
+ALIASES += "key{2}=\1-\2"
+ALIASES += "key{3}=\1-\2"
+ALIASES += "cursor_key{2}=\1"
+
+ALIASES += "fish=\htmlonly[block] \n
"
+ALIASES += "fish{1}=\htmlonly[block] \n
"
+ALIASES += "endfish=
\endhtmlonly \n"
+
+ALIASES += "asis{1}=\1"
+ALIASES += "outp{1}=\1"
+ALIASES += "blah{1}=#\1"
+ALIASES += "cmnd{1}=\1"
+ALIASES += "func{1}=\1"
+ALIASES += "sbin{1}=\1"
+ALIASES += "args{1}=\1"
+ALIASES += "opts{1}=\1"
+ALIASES += "vars{1}=\1"
+ALIASES += "optr{1}=\1"
+ALIASES += "redr{1}=\1"
+ALIASES += "fsfo{1}=\1"
+ALIASES += "path{1}=\1"
+ALIASES += "clrv{1}=\1"
+
+ALIASES += "strg{1}=\1"
+ALIASES += "sglq{1}='\1'"
+ALIASES += "dblq{1}=\"\1\""
+
+ALIASES += "prmt=>"
+ALIASES += "prmt{1}=\1>"
+ALIASES += "sgst{1}=\1"
+ALIASES += "mtch{1}=\1"
+ALIASES += "smtc{1}=\1"
+ALIASES += "eror{1}=\1"
+ALIASES += "curs= "
+ALIASES += "curs{1}=\1"
+
+ALIASES += "bold{1}=\1"
+ALIASES += "emph{1}=\1"
+ALIASES += "undr{1}=\1"
+ALIASES += "span{2}=\2"
+ALIASES += "spcl{2}=\2"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
diff --git a/Makefile.in b/Makefile.in
index cd1c5738..afcba3c9 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -259,8 +259,8 @@ prof: all
 # The sed command deletes everything including and after the first -, for simpler version numbers
 # Cleans up the user_doc/html directory once Doxygen is done.
 
-user_doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h $(HDR_FILES) doc_src/fish_lexicon_filter
-	(cat Doxyfile.user; echo INPUT_FILTER=doc_src/fish_lexicon_filter; \
+user_doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h $(HDR_FILES) lexicon_filter
+	(cat Doxyfile.user; echo INPUT_FILTER=./lexicon_filter; \
 	echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | sed "s/-.*//") | doxygen - && touch user_doc; \
 	cd user_doc/html; rm -f bc_s.png bdwn.png closed.png ftv2*.png nav*.png open.png sync_*.png tab*.* doxygen.* dynsections.js jquery.js pages.html
 
@@ -276,8 +276,8 @@ doc_src/user_doc.css: doc_src/user_doc.css.in doc_src/fish_lexicon_filter
 # Source code documentation. Also includes user documentation.
 #
 
-doc: *.h *.cpp doc.h Doxyfile
-	(cat Doxyfile; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION)) | doxygen - ;
+doc: *.h *.cpp doc.h Doxyfile lexicon_filter
+	(cat Doxyfile; echo INPUT_FILTER=./lexicon_filter; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION)) | doxygen - ;
 
 
 #
@@ -368,6 +368,7 @@ lexicon.txt: doc_src/commands.hdr $(FUNCTIONS_DIR_FILES) $(COMPLETIONS_DIR_FILES
 		-e "s|'\(.*\)'|func \1|p"; \
 	sed >lexicon.tmp -n \
 		-e '/set_default/s/.*\(fish_[a-z][a-z_]*\).*$$/clrv \1/p'; \
+	echo "sbin whoami\nsbin mkdir\nsbin basename" >> lexicon.tmp; \
 	mv lexicon.tmp lexicon.txt; rm -f lexicon_catalog.tmp lexicon_catalog.txt;
 
 #
@@ -381,14 +382,19 @@ lexicon.txt: doc_src/commands.hdr $(FUNCTIONS_DIR_FILES) $(COMPLETIONS_DIR_FILES
 # providing suitable CSS in user_doc.css.in
 #
 
-doc_src/fish_lexicon_filter: lexicon.txt doc_src/fish_lexicon_filter.in
+lexicon_filter: lexicon.txt lexicon_filter.in
 	-rm $@.tmp $@
 	# Clean the filter input comments and set the shebang as sed can reside in
 	# /bin or /usr/bin and some versions dont allow more than one comment!.
-	sed <$@.in >$@.tmp -e 's|@sed@|'"`command -v sed`"'|' -e '/^[ ]*#[^!]/d'
+	sed <$@.in >$@.tmp -e 's|@sed@|'"`which sed`"'|' -e '/^[ ]*#[^!]/d'
 	# Scan through the lexicon, transforming each line to something useful to Doxygen.
+	if `echo "x" | sed "/[[:<:]]x/d"`; then \
+		WORDBL='[[:<:]]'; WORDBR='[[:>:]]'; \
+	else\
+		WORDBL='\\<'; WORDBR='\\>'; \
+	fi; \
 	sed >$@.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,$$WORDBL\2$$WORDBR,@\1{\2},g|p" \
 		-e '$$G;s/.*\n/b tidy/p'; \
 	mv $@.tmp $@; if test -x $@; then true; else chmod a+x $@; fi
 
@@ -493,11 +499,11 @@ common.o: $(COMMON_FILES)
 # There ought to be something simpler.
 #
 
-share/man: $(HELP_SRC) doc_src/fish_lexicon_filter
+share/man: $(HELP_SRC) lexicon_filter
 	-mkdir share/man
 	touch share/man
 	-rm -Rf share/man/man1
-	PROJECT_NUMBER=`echo $(FISH_BUILD_VERSION)| sed "s/-.*//"` INPUT_FILTER=doc_src/fish_lexicon_filter \
+	PROJECT_NUMBER=`echo $(FISH_BUILD_VERSION)| sed "s/-.*//"` INPUT_FILTER=./lexicon_filter \
 	./build_tools/build_documentation.sh Doxyfile.help ./doc_src ./share
 
 #
@@ -812,7 +818,7 @@ clean:
 	rm -f $(PROGRAMS) fish_tests key_reader
 	rm -f command_list.txt command_list_toc.txt toc.txt
 	rm -f doc_src/index.hdr doc_src/commands.hdr
-	rm -f doc_src/fish_lexicon_filter lexicon.txt debug-lexicon.log
+	rm -f lexicon_filter lexicon.txt lexicon.log
 	rm -f FISH-BUILD-VERSION-FILE
 	if test "$(HAVE_DOXYGEN)" = 1; then \
 		rm -rf doc user_doc share/man; \
diff --git a/doc_src/alias.txt b/doc_src/alias.txt
index c1450cc4..079cabff 100644
--- a/doc_src/alias.txt
+++ b/doc_src/alias.txt
@@ -23,11 +23,9 @@ The following code will create `rmi`, which runs `rm` with additional arguments
 
 \fish
 alias rmi "rm -i"
-\endfish
 
-This is equivalent to entering the following function:
+# This is equivalent to entering the following function:
 
-\fish
 function rmi
     rm -i $argv
 end
diff --git a/doc_src/commands.hdr.in b/doc_src/commands.hdr.in
index 12269b2b..fb9ebefa 100644
--- a/doc_src/commands.hdr.in
+++ b/doc_src/commands.hdr.in
@@ -1,5 +1,5 @@
-/** \page commands Commands
-
+/**
+\page commands Commands
 \htmlonly[block]
 

 

diff --git a/doc_src/design.hdr b/doc_src/design.hdr
index e055459f..714321d6 100644
--- a/doc_src/design.hdr
+++ b/doc_src/design.hdr
@@ -1,5 +1,5 @@
-/** \page design Design document
-
+/**
+\page design Design document
 \htmlonly[block]
 

 

@@ -41,7 +41,7 @@ Examples:
 - Here documents are too similar to using echo inside of a pipeline.
 - Subshells, command substitution and process substitution are strongly related. `fish` only supports command substitution, the others can be achieved either using a block or the psub shellscript function.
 - Having both aliases and functions is confusing, especially since both of them have limitations and problems. `fish` functions have none of the drawbacks of either syntax.
-- The many Posix quoting styles are silly, especially \$''.
+- The many Posix quoting styles are silly, especially $''.
 
 \section sep The law of responsiveness
 
diff --git a/doc_src/echo.txt b/doc_src/echo.txt
index 4ce96cb4..7b9b0318 100644
--- a/doc_src/echo.txt
+++ b/doc_src/echo.txt
@@ -2,7 +2,7 @@
 
 \subsection echo-synopsis Synopsis
 \fish{synopsis}
-echo [STRING]
+echo [OPTIONS] [STRING]
 \endfish
 
 \subsection echo-description Description
diff --git a/doc_src/faq.hdr b/doc_src/faq.hdr
index 5558d234..6d3ead30 100644
--- a/doc_src/faq.hdr
+++ b/doc_src/faq.hdr
@@ -1,5 +1,5 @@
-/** \page faq Frequently asked questions
-
+/**
+\page faq Frequently asked questions
 \htmlonly[block]
 

 

diff --git a/doc_src/fish.txt b/doc_src/fish.txt
index 80e7e4e5..ac100821 100644
--- a/doc_src/fish.txt
+++ b/doc_src/fish.txt
@@ -2,7 +2,7 @@
 
 \subsection fish-synopsis Synopsis
 \fish{synopsis}
-fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]]
+fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
 \endfish
 
 \subsection fish-description Description
diff --git a/doc_src/fish_indent.txt b/doc_src/fish_indent.txt
index 51cb5fa6..3a96b534 100644
--- a/doc_src/fish_indent.txt
+++ b/doc_src/fish_indent.txt
@@ -2,7 +2,7 @@
 
 \subsection fish_indent-synopsis Synopsis
 \fish{synopsis}
-fish_indent [options]
+fish_indent [OPTIONS]
 \endfish
 
 \subsection fish_indent-description Description
diff --git a/doc_src/fish_lexicon_filter.in b/doc_src/fish_lexicon_filter.in
deleted file mode 100644
index 9da7d173..00000000
--- a/doc_src/fish_lexicon_filter.in
+++ /dev/null
@@ -1,411 +0,0 @@
-#! @sed@ -f
-#.
-# A Doxygen filter for building Fish's lexicon, for documentation bling.
-#.
-# Written specially for Fish, the shell for the 90's, in sed, the state of the
-# art text processor from the 70's. Who's sed? sed's dead, baby, sed's dead.*
-# by Mark Griffiths              *but quite portable
-#.
-# Finds /fish../endfish blocks in documentation source files and enhances
-# 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
"
-# ALIASES  += "fish{1}=\htmlonly[block] \n
"
-# ALIASES  += "endfish=
\endhtmlonly \n"
-#.
-# ALIASES  += "blah{1}=\1"
-# ALIASES  += "cmnd{1}=\1" and so on...
-#.
-# And simplify for man pages (Doxyfile.help)…
-# ALIASES   = "fish=
"
-# ALIASES  += "fish{1}=
"
-# ALIASES  += "endfish=
"
-#.
-# ALIASES  += "blah{1}=\1"
-# ALIASES  += "cmnd{1}=\1"...
-#.
-# 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 "/fish 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
-# if it saves you a late night, do what you can to help rebalance karma. If it
-# doesn't work or breaks something, it's your fault for using it: if it seems
-# to work it's more likely a hallucination than anything based in reality.
-#.
-# Pattern flow control for scanning doc.h
-/\\fish/,/\\endfish/ {
-    # 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//
-        b process
-    }
-    # Output blank lines
-    /^$/b
-    # Inside \fish block. Process...
-    /\\endfish/!{
-        # Preprocess HTML and HTML-like formatting
-        /<[^>]*>/ {
-            b html
-        }
-        # Process the rest
-        b process
-    }
-    # End block
-    /\\endfish/b
-}
-#.
-# This is not the pattern we're looking for
-b
-#.
-# Process any HTML tags.
-# Structured to reduce sed's greediness.
-:html
-# Spans
-s||@span{\1,|
-s||@spcl{\1,|
-s||}|
-t html
-#.
-# Bold
-s||@bold{|
-s|]*>|@bold{|
-s||}|
-#.
-# Strong
-s||@bold{|
-s|]*>|@bold{|
-s||}|
-#.
-# Italic
-s||@emph{|
-s|]*>|@emph{|
-s||}|
-#.
-# Emphasis
-s||@emph{|
-s|]*>|@emph{|
-s||}|
-#.
-# Underline
-s||@undr{|
-s|]*>|@undr{|
-s||}|
-t html
-#.
-# Some handy non-standard extensions
-# Autosuggestion
-s||@sgst{|
-s|]*>|@sgst{|
-s||}|
-#.
-# Error
-s||@eror{|
-s|]*>|@eror{|
-s||}|
-#.
-# File declaration
-s||@fsfo{|
-s|]*>|@fsfo{|
-s||}|
-#.
-# AsIs - protect from auto-formatting
-s||@asis{|
-s||}|
-t html
-#.
-# Clean other unhandled html
-s|<\([A-Za-z][A-Za-z]*\)[^>]*>\([^<]*\)|\2|
-t html
-#.
-# Start processing entities
-:process
-#.
-# Comments:
-# Capture full line comments
-/^ *#.*$/ {
-    # Assume any line starting with a # is complete
-    s//@blah{&}/
-    t
-}
-# Match sub-line comments
-s/#\(.*$\)/\\\
-<@blah{#\1}\
-/
-#.
-# Protected entities These shouldn't allow nested structure, so we move them
-# to a marked, new line for a future extract/process/insert action.
-#.
-# AsIs block - resists formatting.
-s/@asis{\(.*\)}/\\\
-<@asis{\1}\
-/g
-#.
-# String Literals
-s/"\([^"]*\)"/\\\
-<@dblq{\1}\
-/g
-s/'\([^']*\)'/\\\
-<@sglq{\1}\
-/g
-#.
-# Command/Function options
-# Short options
-s/-\([A-Za-z]\)\([^A-Za-z}]\)/\\\
-<@opts{-\1}\
-\2/g
-#.
-# Long options
-s/--\([A-Za-z][A-Za-z0-9=_-]*\)\([^A-Za-z0-9=_-]*\)/\\\
-<@opts{--\1}\
-\2/g
-#.
-# Paths
-# Normal Directory
-s|\([^/~A-Za-z0-9]\)\([~/][/]*\)\([A-Za-z_0-9./-]*\)|\1\\\
-<@path{\2\3}\
-|g
-#.
-b protect
-#.
-# Tidy up. Merge back 'pure' entities from hold space.
-:tidy
-#.
-# Uncomment the following 2 lines (ss) to log the pattern buffer.
-# s/^.*$/PATT: &/w debug-lexicon.log
-# s/^PATT: //
-#.
-# Uncomment the following 4 lines (xssx) to log the hold buffer.
-# x
-# s/^.*$/HOLD: &/w debug-lexicon.log
-# s/^HOLD: //
-# x
-#.
-# Tack the hold space to the end of the pattern buffer.
-G
-#.
-# Uncomment the folowing two lines (ss) to log the buffer join.
-s/^.*$/JOIN: &/w debug-lexicon.log
-s/^JOIN: //
-#.
-# Iterate over alternate lines, matching '<' to '\'
-:join
-s,\([^\\ ]*\)\\\n\([^<]*\)<\(@[^}]*[}\\]\)[\n]*,\1\3\2,
-t join
-# Clean up stray new lines
-s/\n//g
-#.
-# Clean up special cases
-#.
-/@blah/{
-    s/\(blah{[^@]*\)@sglq{\([^}]*\)}/\1'\2'/
-    s/\(blah{[^@]*\)@dblq{\([^}]*\)}/\1"\2"/
-    s/\(blah{[^@]*\)@....{\([^}]*\)}/\1\2/
-}
-/@redr/{
-    :cleanredr
-    s/\(redr{[^@}]*\)@cmnd{\([^}]*\)}/\1\2/
-    s/\(redr{[^@}]*\)@func{\([^}]*\)}/\1\2/
-    s/\(redr{[^@}]*\)@sbin{\([^}]*\)}/\1\2/
-    s/\(redr{[^@}]*\)@fsfo{\([^}]*\)}/\1\2/
-    s/\(redr{[^}]*\)}\( *\)@path{\([^}]*\)/\1\2\3/
-    t cleanredr
-}
-/@fsfo/{
-    :cleanfsfo
-    s/\(fsfo{[^@}]*\)@cmnd{\([^}]*\)}/\1\2/
-    s/\(fsfo{[^@}]*\)@func{\([^}]*\)}/\1\2/
-    s/\(fsfo{[^@}]*\)@sbin{\([^}]*\)}/\1\2/
-    t cleanfsfo
-}
-#.
-# 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.
-#.
-# 'if' and 'for' seem to be special cases
-/@cmnd{if}/ {
-s//@xcmd\
-{if}/
-s/@cmnd{else}/@xcmd\
-{else}/
-s/@cmnd{not}/@xcmd\
-{not}/
-s/$}@cmnd{status}/$}status/
-b nextcmnd
-}
-/@cmnd{for}/ {
-s/@cmnd{for}/@xcmd\
-{for}/
-s/[[:<:]]in[[:>:]]/@args{in}/
-b castargs
-}
-
-#.
-# Find initial command
-#.
-s/^\( *\)@cmnd\(.*\)/\1@xcmd\
-\2/
-t castargs
-s/^\( *\)@func\(.*\)/\1@xfnc\
-\2/
-t castargs
-s/^\( *\)@sbin\(.*\)/\1@xbin\
-\2/
-t castargs
-: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/
-s/\n\([^@]*@redr{|}\)/\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
-s/\n\([^@]*\)@\(....\)\(.*\)/\1@\2\
-\3/
-t castargs
-:cleancmd
-s/xcmd/cmnd/g
-s/xfnc/func/g
-s/xbin/sbin/g
-s/\n//g
-#.
-# Remove any args after echo
-#.
-/@cmnd{echo}/ {
-s//\
-&\
-/
-:cleanecho
-s/\n\([^@]*\)@args{\([^}]*\)}/\1\2/
-t cleanecho
-s/\n//g
-w debug-lexicon.log
-}
-#.
-# Mark up sesitive character entities.
-#.
-:entities
-s//\>/g
-#.
-# Uncomment the folowing two lines (ss) to log the final output, sent to Doxygen.
-# s/^.*$/OUT : &/w debug-lexicon.log
-# s/^OUT : //
-#.
-# Lines are reassembled, so branch to end
-b
-#.
-# Move protected content to hold space and mark up other entities.
-:protect
-h
-# Clear out any content that has already been marked up, to prevent futher
-# markup on words that should be left alone.
-#.
-:patternflush
-s/\n<@[^}]*}//
-s/\n[}]//
-t patternflush
-s/\n$//
-#.
-# Swap the pattern and hold buffers and remove unmarked lines and extra
-# characters. Basically the inverse of the 'patternflush' action, with
-# additional trailing characters stripped.
-x
-s/^ *[^<][^@][^}]*$//
-s/^ *[^<][^@][^\\]*[\\ ()]*\n//
-:holdflush
-s/}[)(\\ ][)(\\ ]*/}/
-s/\n[];)|* -][^\\]*[\\]*//
-t holdflush
-s/\n$//
-#.
-# Swap the buffers back.
-x
-#.
-# A special case. Tidy up after commands.
-# Redirectors
-s/\([^{|] *\)|/\1@redr{|}/g
-s/\([^{<>^] *\)\([0-9]* *[<>^][<>^]*[a-zA-z0-9._-]*\)/\1@redr{\2}/g
-s/\\}/}\\/g
-#.
-# Now we can add in 'unsafe' entities that would be too greedy.
-# Declared Variables
-#:vars
-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
-#.
-:commands
-#.
-# Manually add a few commands not harvested from source files.
-#.
-s,[[:<:]]whoami[[:>:]],@sbin{whoami},g
-s,[[:<:]]fishd[[:>:]],@sbin{fishd},g
-#.
-#### This section is built in the Makefile. Just some formatting examples. #####
-#.
-#   fish commands (cmnd) <- 4 character code that has a Doxygen alias counterpart
-#   template : s/[[:<:]]function[[:>:]]/@cmnd{&}/
-#.
-#   s,[[:<:]]function[[:>:]],@cmnd{function},g
-#   s,[[:<:]]begin[[:>:]],@cmnd{begin},g
-#   ...
-#.
-#   fish functions (func)
-#   Populated by 'public' functions' filename.
-#.
-#   s,[[:<:]]fish_pwd[[:>:]],@func{fish_pwd},g
-#   s,[[:<:]]fish_prompt[[:>:]],@func{fish_prompt},g
-#   ...
-#.
-#   Shell Binary (sbin)
-#   Populated from completion filenames
-#.
-#   s,[[:<:]]seq[[:>:]],@sbin{seq},g
-#   s,[[:<:]]rm[[:>:]],@sbin{rm},g
-#   ...
-#.
-#   Color Variable (clrv)
-#   Populated from __fish_config_interactive.fish
-#   Allows fish's 'special' color variables to be identified
-#.
-#   s,[[:<:]]fish_color_normal[[:>:]],@clrv{fish_color_normal},g
-#   s,[[:<:]]fish_color_command[[:>:]],@clrv{fish_color_command},g
-#.
-# Once all of the commands/functions/variables/special's have been marked up,
-# branch back to tidy up and collapse the pattern/hold buffers back to a
-# single line.
-#.
-# b tidy
diff --git a/doc_src/fish_prompt.txt b/doc_src/fish_prompt.txt
index 53da848e..57cc5c24 100644
--- a/doc_src/fish_prompt.txt
+++ b/doc_src/fish_prompt.txt
@@ -25,7 +25,8 @@ A simple prompt:
 
 \fish
 function fish_prompt -d "Write out the prompt"
-    printf '%s@%s%s%s%s> ' (whoami) (hostname|cut -d . -f 1) (set_color $fish_color_cwd) (prompt_pwd) (set_color normal)
+    printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \
+    		(set_color $fish_color_cwd) (prompt_pwd) (set_color normal)
 end
 \endfish
 
diff --git a/doc_src/functions.txt b/doc_src/functions.txt
index 520b55b7..24e375c4 100644
--- a/doc_src/functions.txt
+++ b/doc_src/functions.txt
@@ -2,7 +2,7 @@
 
 \subsection functions-synopsis Synopsis
 \fish{synopsis}
-functions [-a|--all] [-n|--names]
+functions [-a | --all] [-n | --names]
 functions -c OLDNAME NEWNAME
 functions -d DESCRIPTION FUNCTION
 functions [-eq] FUNCTIONS...
diff --git a/doc_src/if.txt b/doc_src/if.txt
index b1ca88f5..c5373801 100644
--- a/doc_src/if.txt
+++ b/doc_src/if.txt
@@ -2,7 +2,10 @@
 
 \subsection if-synopsis Synopsis
 \fish{synopsis}
-if CONDITION; COMMANDS_TRUE...; [else if CONDITION2; COMMANDS_TRUE2...;] [else; COMMANDS_FALSE...;] end
+if CONDITION; COMMANDS_TRUE...;
+[else if CONDITION2; COMMANDS_TRUE2...;]
+[else; COMMANDS_FALSE...;]
+end
 \endfish
 
 \subsection if-description Description
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index 94929b74..1f3a9cc3 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -1,4 +1,5 @@
-/** \mainpage Documentation
+/**
+\mainpage Documentation
 \htmlonly[block]
 

 

@@ -188,7 +189,7 @@ When you start a job in `fish`, `fish` itself will pause, and give control of th
 Example:
 
 \fish
-emacs &
+emacs &
 \endfish
 
 will start the emacs text editor in the background.
@@ -260,14 +261,14 @@ The other conditionals use the exit status of a
 
 This is a short explanation of some of the commonly used words in fish.
 
-- argument, a parameter given to a command
-- builtin, a command that is implemented in the shell. Builtins are commands that are so closely tied to the shell that it is impossible to implement them as external commands.
-- command, a program that the shell can run.
-- function, a block of commands that can be called as if they where a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command.
-- job, a running pipeline or command
-- pipeline, a set of commands stringed together so that the output of one command is the input of the next command
-- redirection, a operation that changes one of the input/output streams associated with a job
-- switch, a special flag sent as an argument to a command that will alter the behavior of the command. A switch almost always begins with one or two hyphens.
+- argument a parameter given to a command
+- builtin a command that is implemented in the shell. Builtins are commands that are so closely tied to the shell that it is impossible to implement them as external commands.
+- command a program that the shell can run.
+- function a block of commands that can be called as if they where a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command.
+- job a running pipeline or command
+- pipeline a set of commands stringed together so that the output of one command is the input of the next command
+- redirection a operation that changes one of the input/output streams associated with a job
+- switch a special flag sent as an argument to a command that will alter the behavior of the command. A switch almost always begins with one or two hyphens.
 
 
 \section docs Help
@@ -393,6 +394,9 @@ The exit status of the last run command substitution is available in the index range expansion for details.
 
 Examples:
+\fish
+echo (basename image.jpg .jpg).png
+# Outputs 'image.png'.
 
 The command `echo (basename image.jpg .jpg).png` will output 'image.png'.
 
@@ -406,13 +410,14 @@ splitting it into an array.
 
 A comma separated list of characters enclosed in curly braces will be expanded so each element of the list becomes a new parameter.
 
-Example:
-
+Examples:
 \fish
-echo input.{c,h,txt} # Outputs 'input.c input.h input.txt'
-\endfish
+echo input.{c,h,txt}
+# Outputs 'input.c input.h input.txt'
 
-The command `mv *.{c,h} src/` moves all files with the suffix '.c' or '.h' to the subdirectory src.
+mv *.{c,h} src/
+# Moves all files with the suffix '.c' or '.h' to the subdirectory src.
+\endfish
 
 \subsection expand-variable Variable expansion
 
@@ -423,12 +428,18 @@ Undefined and empty variables expand to nothing.
 To separate a variable name from text it should immediately be followed by, encase the variable within braces.
 
 Examples:
+\fish
+echo $HOME
+# Prints the home directory of the current user.
 
-`echo $HOME` prints the home directory of the current user.
+echo $nonexistentvariable
+# Prints no output.
 
-`echo $nonexistentvariable` prints no output.
+echo The plural of $WORD is {$WORD}s
+# Prints "The plural of cat is cats" when $WORD is set to cat.
+\endfish
 
-`echo The plural of $WORD is {$WORD}s` prints "The plural of cat is cats" when `$WORD` is set to cat. Note that without the braces, fish will try to expand a variable called `$WORDs`, which may not exist.
+Note that without the braces, fish will try to expand a variable called `$WORDs`, which may not exist.
 
 The latter syntax works by exploiting brace expansion; care should be taken with array variables and undefined variables, as these behave very differently to POSIX shells.
 
@@ -461,24 +472,19 @@ Some examples:
 \fish
 # Limit the command substitution output
 echo (seq 10)[2..5]
-# will use elements from 2 to 5
-
-# Output is:
-# 2 3 4 5
+# Uses elements from 2 to 5
+# Output is: 2 3 4 5
 
 # Use overlapping ranges:
 echo (seq 10)[2..5 1..3]
-# will take elements from 2 to 5 and then elements from 1 to 3
-
-# Output is:
-# 2 3 4 5 1 2 3
+# Takes elements from 2 to 5 and then elements from 1 to 3
+# Output is: 2 3 4 5 1 2 3
 
 # Reverse output
 echo (seq 10)[-1..1]
-# will use elements from the last output line to the first one in reverse direction
-
-# Output is:
-# 10 9 8 7 6 5 4 3 2 1
+# Uses elements from the last output line to
+# the first one in reverse direction
+# Output is: 10 9 8 7 6 5 4 3 2 1
 \endfish
 
 The same works when setting or expanding variables:
@@ -604,14 +610,11 @@ end
 
 function avast
     set phrase 'Avast, mateys'
-
     # Calling the shiver function here can not
     # change any variables in the local scope
     shiver
-
     echo $phrase
 end
-
 avast
 \endfish
 
diff --git a/doc_src/nextd.txt b/doc_src/nextd.txt
index a098c0a7..217042b1 100644
--- a/doc_src/nextd.txt
+++ b/doc_src/nextd.txt
@@ -2,7 +2,7 @@
 
 \subsection nextd-synopsis Synopsis
 \fish{synopsis}
-nextd [ -l | --list ] [POS]
+nextd [-l | --list] [POS]
 \endfish
 
 \subsection nextd-description Description
diff --git a/doc_src/psub.txt b/doc_src/psub.txt
index d0caafba..be812f4a 100644
--- a/doc_src/psub.txt
+++ b/doc_src/psub.txt
@@ -2,7 +2,7 @@
 
 \subsection psub-synopsis Synopsis
 \fish{synopsis}
-COMMAND1 (COMMAND2|psub [-f])
+COMMAND1 (COMMAND2 | psub [-f])
 \endfish
 
 \subsection psub-description Description
@@ -24,5 +24,7 @@ process can seek in the stream.
 
 \subsection psub-example Example
 
-`diff (sort a.txt|psub) (sort b.txt|psub)` shows the difference
-between the sorted versions of files a.txt and b.txt.
+\fish
+diff (sort a.txt | psub) (sort b.txt | psub)
+# shows the difference between the sorted versions of files `a.txt` and `b.txt`.
+\endfish
\ No newline at end of file
diff --git a/doc_src/set.txt b/doc_src/set.txt
index 4acbbf17..cbdd0f15 100644
--- a/doc_src/set.txt
+++ b/doc_src/set.txt
@@ -82,19 +82,21 @@ success, with a non-zero exit status if the commandline was invalid, if the
 variable was write-protected or if the variable did not exist.
 
 \subsection set-example Example
+\fish
+set -xg
+# Prints all global, exported variables.
 
-`set -xg` will print all global, exported variables.
-
-`set foo hi` sets the value of the variable foo to be hi.
+set foo hi
+# Sets the value of the variable $foo to be 'hi'.
 
-`set -e smurf` removes the variable `smurf`.
+set -e smurf
+# Removes the variable $smurf
 
-`set PATH[4] ~/bin` changes the fourth element of the `PATH` array to `~/bin`
+set PATH[4] ~/bin
+# Changes the fourth element of the $PATH array to ~/bin
 
-\fish
 if set python_path (which python)
     echo "Python is at $python_path"
 end
+# Outputs the path to Python if `which` returns true.
 \endfish
-
-The above outputs the path to Python if `which` returns true.
diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt
index 0597114b..41c58d9e 100644
--- a/doc_src/set_color.txt
+++ b/doc_src/set_color.txt
@@ -2,7 +2,7 @@
 
 \subsection set_color-synopsis Synopsis
 \fish{synopsis}
-set_color [-h|--help] [-b|--background COLOR] [COLOR]
+set_color [OPTIONS] [COLOR]
 \endfish
 
 \subsection set_color-description Description
diff --git a/doc_src/source.txt b/doc_src/source.txt
index 5efb6740..8e051a8a 100644
--- a/doc_src/source.txt
+++ b/doc_src/source.txt
@@ -27,6 +27,7 @@ is deprecated in favour of `source`, and `.` will be removed in a future
 version of fish.
 
 \subsection source-example Example
-
-`source ~/.config/fish/config.fish` causes fish to re-read its initialization file.
-
+\fish
+source ~/.config/fish/config.fish
+# Causes fish to re-read its initialization file.
+\endfish
diff --git a/doc_src/trap.txt b/doc_src/trap.txt
index fdccd178..9c607ad4 100644
--- a/doc_src/trap.txt
+++ b/doc_src/trap.txt
@@ -40,6 +40,7 @@ The return status is 1 if any `SIGSPEC` is invalid; otherwise trap
 returns 0.
 
 \subsection trap-example Example
-
-`trap "status --print-stack-trace" SIGUSR1` prints a stack trace
-each time the `SIGUSR1` signal is sent to the shell.
+\fish
+trap "status --print-stack-trace" SIGUSR1
+# Prints a stack trace each time the SIGUSR1 signal is sent to the shell.
+\endfish
\ No newline at end of file
diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr
index 0f011efc..c228c11f 100644
--- a/doc_src/tutorial.hdr
+++ b/doc_src/tutorial.hdr
@@ -1,5 +1,5 @@
-/** \page tutorial Tutorial
-
+/**
+\page tutorial Tutorial
 \htmlonly[block]
 

 

@@ -23,7 +23,10 @@
 - Functions
 - Loops
 - Prompt
+- $PATH
 - Startup
+- Autoloading Functions
+- Ready for more?
 
 \htmlonly[block]
 

@@ -33,7 +36,6 @@
 
fish tutorial

 \endhtmlonly
 
-
 \section tut_why_fish Why fish?
 
 `fish` is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. `fish` supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure.
@@ -45,14 +47,14 @@ If you want to make your command line more productive, more useful, and more fun
 
 This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of `fish`.
 
-If you have a strong understanding of other shells, and want to know what `fish` does differently, search for the magic phrase unlike other shells, which is used to call out important differences.
+If you have a strong understanding of other shells, and want to know what `fish` does differently, search for the magic phrase unlike other shells, which is used to call out important differences.
 
 When you start `fish`, you should see this:
 
 \fish{cli-dark}
-Welcome to fish, the friendly interactive shell
-Type help for instructions on how to use fish
-you@hostname ~>
+Welcome to fish, the friendly interactive shell
+Type help for instructions on how to use fish
+you@hostname ~>___
 \endfish
 
 `fish` comes with a default prompt that shows your username, hostname, and working directory. You'll see how to change your prompt further down. From now on, we'll pretend your prompt is just a '`>`' to save space.
@@ -63,17 +65,17 @@ you@hostname ~>
 `fish` runs commands like other shells: you type a command, followed by its arguments. Spaces are separators:
 
 \fish{cli-dark}
-> echo hello world
-hello world
+>_ echo hello world
+hello world
 \endfish
 
 You can include a literal space in an argument with a backslash, or by using single or double quotes:
 
 \fish{cli-dark}
-> mkdir My\ Files
-> cp ~/Some\ File 'My Files'
-> ls "My Files"
-Some File
+>_ mkdir My\ Files
+>_ cp ~/Some\ File 'My Files'
+>_ ls "My Files"
+Some File
 \endfish
 
 Commands can be chained with semicolons.
@@ -84,9 +86,9 @@ Commands can be chained with semicolons.
 `fish` has excellent help and man pages. Run `help` to open help in a web browser, and `man` to open it in a man page. You can also ask for help with a specific command, for example, `help set` to open in a web browser, or `man set` to see it in the terminal.
 
 \fish{cli-dark}
-> man set
-set - handle shell variables
-  Synopsis...
+>_ man set
+set - handle shell variables
+  Synopsis...
 \endfish
 
 
@@ -95,19 +97,19 @@ set - handle shell variables
 You'll quickly notice that `fish` performs syntax highlighting as you type. Invalid commands are colored red by default:
 
 \fish{cli-dark}
-> /bin/mkd
+>_ /bin/mkd
 \endfish
 
 A command may be invalid because it does not exist, or refers to a file that you cannot execute. When the command becomes valid, it is shown in a different color:
 
 \fish{cli-dark}
-> /bin/mkdir
+>_ /bin/mkdir
 \endfish
 
 `fish` will underline valid file paths as you type them:
 
 \fish{cli-dark}
-> cat ~/somefi
+>_ cat ~/somefi__
 \endfish
 
 This tells you that there exists a file that starts with '`somefi`', which is useful feedback as you type.
@@ -117,29 +119,29 @@ These colors, and many more, can be changed by running `fish_config`, or by modi
 
 \section tut_wildcards Wildcards
 
-`fish` supports the familiar wildcard *. To list all JPEG files:
+`fish` supports the familiar wildcard `*`. To list all JPEG files:
 
 \fish{cli-dark}
-> ls *.jpg
-lena.jpg
-meena.jpg
-santa maria.jpg
+>_ ls *.jpg
+lena.jpg
+meena.jpg
+santa maria.jpg
 \endfish
 
 You can include multiple wildcards:
 
 \fish{cli-dark}
-> ls l*.p*
-lena.png
-lesson.pdf
+>_ ls l*.p*
+lena.png
+lesson.pdf
 \endfish
 
-Especially powerful is the recursive wildcard ** which searches directories recursively:
+Especially powerful is the recursive wildcard ** which searches directories recursively:
 
 \fish{cli-dark}
-> ls /var/\**.log
-/var/log/system.log
-/var/run/sntp.log
+>_ ls /var/**.log
+/var/log/system.log
+/var/run/sntp.log
 \endfish
 
 If that directory traversal is taking a long time, you can @key{Control,C} out of it.
@@ -150,14 +152,14 @@ If that directory traversal is taking a long time, you can @key{Control,C} out o
 You can pipe between commands with the usual vertical bar:
 
 \fish{cli-dark}
-> echo hello world | wc
-       1       2      12
+>_ echo hello world | wc
+       1       2      12
 \endfish
 
 stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^
 
 \fish{cli-dark}
-> grep fish < /etc/shells > ~/output.txt ^ ~/errors.txt
+>_ grep fish < /etc/shells > ~/output.txt ^ ~/errors.txt
 \endfish
 
 
@@ -166,24 +168,23 @@ stdin and stdout can be redirected via the familiar < and >. Unlike other
 `fish` suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example:
 
 \fish{cli-dark}
-> /bin/hostname
+>_ /bin/h__ostname
 \endfish
 
 It knows about paths and options:
 
 \fish{cli-dark}
-> grep --ignore-case
+>_ grep --i__gnore-case
 \endfish
 
 And history too. Type a command once, and you can re-summon it by just typing a few letters:
 
 \fish{cli-dark}
-> rsync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo
+>_ r__sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo
 \endfish
 
 To accept the autosuggestion, hit right arrow or @key{Control,F}. To accept a single word of the autosuggestion, @key{Alt,→} (right arrow). If the autosuggestion is not what you want, just ignore it.
 
-
 \section tut_tab_completions Tab Completions
 
 `fish` comes with a rich set of tab completions, that work "out of the box."
@@ -191,14 +192,14 @@ To accept the autosuggestion, hit right arrow or @key{Control,F}. To accept a si
 Press tab, and `fish` will attempt to complete the command, argument, or path:
 
 \fish{cli-dark}
-> /pri<tab> → /private/
+>_ /pri @key{Tab} → /private/
 \endfish
 
 If there's more than one possibility, it will list them:
 
 \fish{cli-dark}
-> ~/stuff/s<tab>
-~/stuff/script.sh  (Executable, 4.8kB)  ~/stuff/sources/  (Directory)
+>_ ~/stuff/s @key{Tab}
+~/stuff/script.sh  (Executable, 4.8kB)  ~/stuff/sources/  (Directory)
 \endfish
 
 Hit tab again to cycle through the possibilities.
@@ -206,51 +207,50 @@ Hit tab again to cycle through the possibilities.
 `fish` can also complete many commands, like git branches:
 
 \fish{cli-dark}
-> git merge pr<tab> → git merge prompt_designer
-> git checkout b<tab>
-builtin_list_io_merge  (Branch)  builtin_set_color  (Branch)  busted_events  (Tag)
+>_ git merge pr @key{Tab} → git merge prompt_designer
+>_ git checkout b @key{Tab}
+builtin_list_io_merge (Branch) builtin_set_color (Branch) busted_events (Tag)
 \endfish
 
 Try hitting tab and see what `fish` can do!
 
-
 \section tut_variables Variables
 
-Like other shells, a dollar sign performs variable substitution:
+Like other shells, a dollar sign performs variable substitution:
 
 \fish{cli-dark}
-> echo My home directory is $HOME
-My home directory is /home/tutorial
+>_ echo My home directory is $HOME
+My home directory is /home/tutorial
 \endfish
 
 Variable substitution also occurs in double quotes, but not single quotes:
 
 \fish{cli-dark}
-> echo "My current directory is $PWD"
-My current directory is /home/tutorial
-> echo 'My current directory is $PWD'
-My current directory is $PWD
+>_ echo "My current directory is $PWD"
+My current directory is /home/tutorial
+>_ echo 'My current directory is $PWD'
+My current directory is $PWD
 \endfish
 
 Unlike other shells, `fish` has no dedicated syntax for setting variables. Instead it has an ordinary command: `set`, which takes a variable name, and then its value.
 
 \fish{cli-dark}
-> set name 'Mister Noodle'
-> echo $name
-Mister Noodle
+>_ set name 'Mister Noodle'
+>_ echo $name
+Mister Noodle
 \endfish
 
-(Notice the quotes: without them, `Mister` and `Noodle` would have been separate arguments, and `$name` would have been made into a list of two elements.)
+(Notice the quotes: without them, `Mister` and `Noodle` would have been separate arguments, and `$name` would have been made into a list of two elements.)
 
-Unlike other shells, variables are not further split after substitution:
+Unlike other shells, variables are not further split after substitution:
 
 \fish{cli-dark}
-> mkdir $name
-> ls
-Mister Noodle
+>_ mkdir $name
+>_ ls
+Mister Noodle
 \endfish
 
-In bash, this would have created two directories "Mister" and "Noodle". In `fish`, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to mkdir, spaces and all.
+In bash, this would have created two directories "Mister" and "Noodle". In `fish`, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to `mkdir`, spaces and all.
 
 
 \section tut_exit_status Exit Status
@@ -258,43 +258,44 @@ In bash, this would have created two directories "Mister" and "Noodle". In `fish
 Unlike other shells, `fish` stores the exit status of the last command in `$status` instead of `$?`.
 
 \fish{cli-dark}
-> false
-> echo $status
-1
+>_ false
+>_ echo $status
+1
 \endfish
 
 Zero is considered success, and non-zero is failure.
 
-
Exports (Shell Variables)

+
+\section tut_exports Exports (Shell Variables)
 
 Unlike other shells, `fish` does not have an export command. Instead, a variable is exported via an option to `set`, either `--export` or just `-x`.
 
 \fish{cli-dark}
-> set -x MyVariable SomeValue
-> env | grep MyVariable
-MyVariable=SomeValue
+>_ set -x MyVariable SomeValue
+>_ env | grep MyVariable
+MyVariable=SomeValue
 \endfish
 
 You can erase a variable with `-e` or `--erase`
 
 \fish{cli-dark}
-> set -e MyVariable
-> env | grep MyVariable
-(no output)
+>_ set -e MyVariable
+>_ env | grep MyVariable
+(no output)
 \endfish
 
 
 \section tut_lists Lists
 
-The `set` command above used quotes to ensure that `Mister Noodle` was one argument. If it had been two arguments, then `name` would have been a list of length 2.  In fact, all variables in `fish` are really lists, that can contain any number of values, or none at all.
+The `set` command above used quotes to ensure that `Mister Noodle` was one argument. If it had been two arguments, then `name` would have been a list of length 2.  In fact, all variables in `fish` are really lists, that can contain any number of values, or none at all.
 
-Some variables, like `$PWD`, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value.
+Some variables, like `$PWD`, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value.
 
-Other variables, like `$PATH`, really do have multiple values. During variable expansion, the variable expands to become multiple arguments:
+Other variables, like `$PATH`, really do have multiple values. During variable expansion, the variable expands to become multiple arguments:
 
 \fish{cli-dark}
-> echo $PATH
-/usr/bin /bin /usr/sbin /sbin /usr/local/bin
+>_ echo $PATH
+/usr/bin /bin /usr/sbin /sbin /usr/local/bin
 \endfish
 
 Lists cannot contain other lists: there is no recursion.  A variable is a list of strings, full stop.
@@ -302,48 +303,48 @@ Lists cannot contain other lists: there is no recursion.  A variable is a list o
 Get the length of a list with `count`:
 
 \fish{cli-dark}
-> count $PATH
-5
+>_ count $PATH
+5
 \endfish
 
 You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH:
 
 \fish{cli-dark}
-> set PATH $PATH /usr/local/bin
+>_ set PATH $PATH /usr/local/bin
 \endfish
 
 
 You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end:
 
 \fish{cli-dark}
-> echo $PATH
-/usr/bin /bin /usr/sbin /sbin /usr/local/bin
-> echo $PATH[1]
-/usr/bin
-> echo $PATH[-1]
-/usr/local/bin
+>_ echo $PATH
+/usr/bin /bin /usr/sbin /sbin /usr/local/bin
+>_ echo $PATH[1]
+/usr/bin
+>_ echo $PATH[-1]
+/usr/local/bin
 \endfish
 
 You can also access ranges of elements, known as "slices:"
 
 \fish{cli-dark}
-> echo $PATH[1..2]
-/usr/bin /bin
-> echo $PATH[-1..2]
-/usr/local/bin /sbin /usr/sbin /bin
+>_ echo $PATH[1..2]
+/usr/bin /bin
+>_ echo $PATH[-1..2]
+/usr/local/bin /sbin /usr/sbin /bin
 \endfish
 
-You can iterate over a list (or a slice) with a for loop:
+You can iterate over a list (or a slice) with a for loop:
 
 \fish{cli-dark}
-> for val in $PATH
-    echo "entry: $val"
-  end
-entry: /usr/bin/
-entry: /bin
-entry: /usr/sbin
-entry: /sbin
-entry: /usr/local/bin
+>_ for val in $PATH
+    echo "entry: $val"
+  end
+entry: /usr/bin/
+entry: /bin
+entry: /usr/sbin
+entry: /sbin
+entry: /usr/local/bin
 \endfish
 
 
@@ -352,62 +353,64 @@ entry: /usr/local/bin
 Command substitutions use the output of one command as an argument to another. Unlike other shells, `fish` does not use backticks ` for command substitutions. Instead, it uses parentheses:
 
 \fish{cli-dark}
-> echo In (pwd), running (uname)
-In /home/tutorial, running FreeBSD
+>_ echo In (pwd), running (uname)
+In /home/tutorial, running FreeBSD
 \endfish
 
 A common idiom is to capture the output of a command in a variable:
 
 \fish{cli-dark}
-> set os (uname)
-> echo $os
-Linux
+>_ set os (uname)
+>_ echo $os
+Linux
 \endfish
 
 Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument:
 
 \fish{cli-dark}
-> touch "testing_"(date +%s)".txt"
-> ls *.txt
-testing_1360099791.txt
+>_ touch "testing_"(date +%s)".txt"
+>_ ls *.txt
+testing_1360099791.txt
 \endfish
 
-
Combiners (And, Or, Not)

+
+\section tut_combiners Combiners (And, Or, Not)
 
 Unlike other shells, `fish` does not have special syntax like && or || to combine commands. Instead it has commands `and`, `or`, and `not`.
 
 \fish{cli-dark}
-> cp file1.txt file1_bak.txt; and echo "Backup successful"; or echo "Backup failed"
-Backup failed
+>_ cp file1.txt file1_bak.txt; and echo "Backup successful"; or echo "Backup failed"
+Backup failed
 \endfish
 
-
Conditionals (If, Else, Switch)

+
+\section tut_conditionals Conditionals (If, Else, Switch)
 
 Use `if`, `else if`, and `else` to conditionally execute code, based on the exit status of a command.
 
 \fish{cli-dark}
-if grep fish /etc/shells
-    echo Found fish
-else if grep bash /etc/shells
-    echo Found bash
-else
-    echo Got nothing
-end
+if grep fish /etc/shells
+    echo Found fish
+else if grep bash /etc/shells
+    echo Found bash
+else
+    echo Got nothing
+end
 \endfish
 
 There is also a `switch` command:
 
 \fish{cli-dark}
-switch (uname)
-case Linux
-    echo Hi Tux!
-case Darwin
-    echo Hi Hexley!
-case FreeBSD NetBSD DragonFly
-    echo Hi Beastie!
-case '*'
-    echo Hi, stranger!
-end
+switch (uname)
+case Linux
+    echo Hi Tux!
+case Darwin
+    echo Hi Hexley!
+case FreeBSD NetBSD DragonFly
+    echo Hi Beastie!
+case '*'
+    echo Hi, stranger!
+end
 \endfish
 
 Note that `case` does not fall through, and can accept multiple arguments or (quoted) wildcards.
@@ -418,13 +421,13 @@ Note that `case` does not fall through, and can accept multiple arguments or (qu
 A `fish` function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like `$1`, but instead in a single list `$argv`. To create a function, use the `function` builtin:
 
 \fish{cli-dark}
-> function say_hello
-     echo Hello $argv
-  end
-> say_hello
-Hello
-> say_hello everybody!
-Hello everybody!
+>_ function say_hello
+     echo Hello $argv
+  end
+>_ say_hello
+Hello
+>_ say_hello everybody!
+Hello everybody!
 \endfish
 
 Unlike other shells, `fish` does not have aliases or special prompt syntax. Functions take their place.
@@ -432,14 +435,14 @@ Unlike other shells, `fish` does not have aliases or special prompt syntax. Func
 You can list the names of all functions with the `functions` keyword (note the plural!). `fish` starts out with a number of functions:
 
 \fish{cli-dark}
-> functions
-alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, sgrep, trap, type, umask, up-or-search, vared
+>_ functions
+alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, sgrep, trap, type, umask, up-or-search, vared
 \endfish
 
 You can see the source for any function by passing its name to `functions`:
 
 \fish{cli-dark}
-> functions ls
+>_ functions ls
 function ls --description 'List contents of directory'
     command ls -G $argv
 end
@@ -451,29 +454,29 @@ end
 While loops:
 
 \fish{cli-dark}
-> while true
-    echo "Loop forever"
-end
-Loop forever
-Loop forever
-Loop forever
-...
+>_ while true
+    echo "Loop forever"
+end
+Loop forever
+Loop forever
+Loop forever
+...
 \endfish
 
 For loops can be used to iterate over a list. For example, a list of files:
 
 \fish{cli-dark}
-> for file in *.txt
-    cp $file $file.bak
-end
+>_ for file in *.txt
+    cp $file $file.bak
+end
 \endfish
 
 Iterating over a list of numbers can be done with `seq`:
 
 \fish{cli-dark}
-> for x in (seq 5)
-    touch file_$x.txt
-end
+>_ for x in (seq 5)
+    touch file_$x.txt
+end
 \endfish
 
 
@@ -484,48 +487,49 @@ Unlike other shells, there is no prompt variable like PS1. To display your promp
 You can define your own prompt:
 
 \fish{cli-dark}
-> function fish_prompt
-    echo "New Prompt % "
-end
-New Prompt %  
+>_ function fish_prompt
+    echo "New Prompt % "
+end
+New Prompt % __
 \endfish
 
 Multiple lines are OK. Colors can be set via `set_color`, passing it named ANSI colors, or hex RGB values:
 
 \fish{cli-dark}
-> function fish_prompt
-      set_color purple
-      date "+%m/%d/%y"
-      set_color FF0
-      echo (pwd) '>'
-      set_color normal
-  end
+>_ function fish_prompt
+      set_color purple
+      date "+%m/%d/%y"
+      set_color FF0
+      echo (pwd) '>'
+      set_color normal
+  end
 02/06/13
-/home/tutorial > 
+/home/tutorial >__
 \endfish
 
 You can choose among some sample prompts by running `fish_config prompt`. `fish` also supports RPROMPT through `fish_right_prompt`.
 
-\subsection tut-path $PATH
+\section tut-path $PATH
 
 `$PATH` is an environment variable containing the directories in which `fish` searches for commands. Instead of separating entries with a colon, $PATH is a list. You can modify $PATH in a few ways:
 
 -# By modifying the `$fish_user_paths` variable, which is automatically appended to `$PATH`. For example, to permanently add `/usr/local/bin` to your `$PATH`, you could write:
 
 \fish{cli-dark}
-> set -U fish_user_paths $fish_user_paths /usr/local/bin
+>_ set -U fish_user_paths $fish_user_paths /usr/local/bin
 \endfish
 
 -# Directly in config.fish (see below).
 
-
Startup (Where's .bashrc?)

+
+\section tut_startup Startup (Where's .bashrc?)
 
 `fish` starts by executing commands in `~/.config/fish/config.fish`. You can create it if it does not exist.
 
 It is possible to directly create functions and variables in `config.fish` file, using the commands shown above. For example:
 
 \fish{cli-dark}
-> cat ~/.config/fish/config.fish
+>_ cat ~/.config/fish/config.fish
 
 set -x PATH $PATH /sbin/
 
@@ -534,16 +538,16 @@ function ll
 end
 \endfish
 
-However, it is more common and efficient to use  autoloading functions and universal variables.
+However, it is more common and efficient to use  autoloading functions and universal variables.
 
-\subsection tut-autoload Autoloading Functions
+\section tut-autoload Autoloading Functions
 
-When `fish` encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in `~/.config/fish/functions/`.
+When `fish` encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in `~/.config/fish/functions/`.
 
 For example, if you wanted to have a function `ll`, you would add a text file `ll.fish` to `~/.config/fish/functions`:
 
 \fish{cli-dark}
-> cat ~/.config/fish/functions/ll.fish
+>_ cat ~/.config/fish/functions/ll.fish
 function ll
     ls -lh $argv
 end
@@ -552,30 +556,30 @@ end
 This is the preferred way to define your prompt as well:
 
 \fish{cli-dark}
-> cat ~/.config/fish/functions/fish_prompt.fish
+>_ cat ~/.config/fish/functions/fish_prompt.fish
 function fish_prompt
-    echo (pwd) '> '
+    echo (pwd) "> "
 end
 \endfish
 
 See the documentation for funced and funcsave for ways to create these files automatically.
 
-\subsection tut-universal Universal Variables
+\section tut-universal Universal Variables
 
 A universal variable is a variable whose value is shared across all instances of `fish`, now and in the future - even after a reboot. You can make a variable universal with `set -U`:
 
 \fish{cli-dark}
-> set -U EDITOR vim
+>_ set -U EDITOR vim
 \endfish
 
 Now in another shell:
 
 \fish{cli-dark}
-> echo $EDITOR
+>_ echo $EDITOR
 vim
 \endfish
 
-\subsection tut-more  Ready for more?
+\section tut-more  Ready for more?
 
 If you want to learn more about fish, there is lots of detailed documentation, an official mailing list, the IRC channel \#fish on `irc.oftc.net`, and the github page.
 
diff --git a/doc_src/type.txt b/doc_src/type.txt
index c72520a1..c3265f38 100644
--- a/doc_src/type.txt
+++ b/doc_src/type.txt
@@ -23,5 +23,7 @@ The following options are available:
 and 1 if it could not be found.
 
 \subsection type-example Example
-
-`type fg` outputs the string '`fg is a shell builtin`'.
+\fish
+type fg
+# Outputs the string 'fg is a shell builtin'.
+\endfish
diff --git a/doc_src/user_doc.css b/doc_src/user_doc.css
index d91f5dde..c64a8665 100644
--- a/doc_src/user_doc.css
+++ b/doc_src/user_doc.css
@@ -135,7 +135,6 @@ h3 {
 }
 .key em {
     margin-right: 2px;
-    font-style: normal;
 }
 .key em, .key b {
     padding: 0 4px;
@@ -148,7 +147,7 @@ h3 {
 tt, code, pre, .fish {
     font-family: "DejaVu Sans Mono", Menlo, Monaco, "Source Code Pro", "Ubuntu Mono", "Consolas", "Lucida Console", monospace, fixed;
     font-weight: 500;
-    text-shadow: 0 0 0 rgba(0,0,0,1); /* Stronger anti-aliasing */
+    text-shadow: 0 0 0 rgba(0,0,0,0.2);
 }
 tt {
     color: red; /*REMOVE THIS*/
diff --git a/doc_src/while.txt b/doc_src/while.txt
index 80ec959b..3de3f54a 100644
--- a/doc_src/while.txt
+++ b/doc_src/while.txt
@@ -18,6 +18,7 @@ complex control can be achieved with `while true` containing a
 
 \subsection while-example Example
 
-`while test -f foo.txt; echo file exists; sleep 10; end`
-outputs 'file exists' at 10 second intervals as long as
-the file foo.txt exists.
+\fish
+while test -f foo.txt; echo file exists; sleep 10; end
+# outputs 'file exists' at 10 second intervals as long as the file foo.txt exists.
+\endfish
\ No newline at end of file
diff --git a/lexicon_filter.in b/lexicon_filter.in
new file mode 100644
index 00000000..7e49651e
--- /dev/null
+++ b/lexicon_filter.in
@@ -0,0 +1,475 @@
+#! @sed@ -f
+#.
+# A Doxygen filter for building Fish's lexicon, for documentation bling.
+#.
+# Written specially for Fish, the shell for the 90's, in sed, the state of the
+# art text processor from the 70's. Who's sed? sed's dead, baby, sed's dead.*
+# by Mark Griffiths              *but quite portable
+#.
+# Finds /fish../endfish blocks in documentation source files and enhances
+# 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
"
+# ALIASES  += "fish{1}=\htmlonly[block] \n
"
+# ALIASES  += "endfish=
\endhtmlonly \n"
+#.
+# ALIASES  += "blah{1}=\1"
+# ALIASES  += "cmnd{1}=\1" and so on...
+#.
+# And simplify for man pages (Doxyfile.help)…
+# ALIASES   = "fish=
"
+# ALIASES  += "fish{1}=
"
+# ALIASES  += "endfish=
"
+#.
+# ALIASES  += "blah{1}=\1"
+# ALIASES  += "cmnd{1}=\1"...
+#.
+# 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 "/fish 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
+# if it saves you a late night, do what you can to help rebalance karma. If it
+# doesn't work or breaks something, it's your fault for using it: if it seems
+# to work it's more likely a hallucination than anything based in reality.
+#.
+# Pattern flow control for scanning doc.h
+/\\fish/,/\\endfish/ {
+    # 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.*$/ {
+        # Catch @ symbol
+        s/@/(at)/
+        s/^\\fish//
+        s/\\endfish//
+        b html
+    }
+    # Output blank lines
+    /^$/b
+    # Inside \fish block. Process...
+    /\\endfish/!{
+        # Catch @ symbol
+        s/@/((d))/
+        # Preprocess HTML and HTML-like formatting
+        /<[^>]*>/ {
+            b html
+        }
+        # Process the rest
+        b process
+    }
+    # End block
+    /\\endfish/b
+}
+#.
+# This is not the pattern we're looking for
+b
+#.
+# Process any HTML tags.
+# Structured to reduce sed's greediness.
+:html
+# Spans
+s||@span{\1,|
+s||@spcl{\1,|
+s||}|
+#.
+# Bold
+s||@bold{|
+s|]*>|@bold{|
+s||}|
+#.
+# Strong (synonimous with emphasis)
+s||@bold{|
+s|]*>|@bold{|
+s||}|
+#.
+# EMPHasis
+s||@emph{|
+s|]*>|@emph{|
+s||}|
+#.
+# Italic (synonimous with emphasis)
+s||@emph{|
+s|]*>|@emph{|
+s||}|
+#.
+# UNDeRline
+s||@undr{|
+s|]*>|@undr{|
+s||}|
+t html
+#.
+# Some handy non-standard extensions
+# autoSuGgeSTion
+s||@sgst{|
+s|]*>|@sgst{|
+s||}|
+#.
+# MaTCH
+s||@mtch{|
+s|]*>|@mtch{|
+s||}|
+#.
+# SearchMaTCh
+s||@smtc{|
+s|]*>|@smtc{|
+s||}|
+#.
+# ERrOR
+s||@eror{|
+s|]*>|@eror{|
+s||}|
+#.
+# AsIs - protect from auto-formatting
+s||@asis{|
+s||}|
+#.
+# OUTPut - protect from auto-formatting
+s||@outp{|
+s||}|
+t html
+#.
+# Clean other unhandled html
+s|<\([A-Za-z][A-Za-z]*\)[^>]*>\([^<]*\)|\2|
+t html
+#.
+# Start processing entities
+:process
+# Output:
+# Line marked as output pass through
+/@outp/ {
+    b
+}
+# Comments:
+# Capture full line comments
+/^\( *\)#\(.*\)$/ {
+    # Assume any line starting with a # is complete
+    s//\1@blah{\2}/
+    t
+}
+# Match sub-line comments
+/#[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]/ ! {
+    s/#\(.*$\)/\\\
+<@blah{#\1}\
+/
+}
+#.
+# Protected entities These shouldn't allow nested structure, so we move them
+# to a marked, new line for a future extract/process/insert action.
+#.
+# AsIs block - resists formatting.
+s/@asis{\(.*\)}/\\\
+<@asis{\1}\
+/g
+#.
+# Manual 
+s/@span{\(.*\)}/\\\
+<@span{\1}\
+/g
+#.
+# String Literals
+s/"\([^"]*\)"/\\\
+<@dblq{\1}\
+/g
+s/'\([^']*\)'/\\\
+<@sglq{\1}\
+/g
+#.
+# AutoSuggestions.
+s/@sgst{\([^}]*\)}/\\\
+<@sgst{\1}\
+/
+#.
+# Command/Function options
+# Short options
+s/-\([A-Za-z]\)\([^A-Za-z}]\)/\\\
+<@opts{-\1}\
+\2/g
+#.
+# Long options
+s/--\([A-Za-z][A-Za-z0-9=_-]*\)\([^A-Za-z0-9=_-]*\)/\\\
+<@opts{--\1}\
+\2/g
+#.
+# Prompt
+s/~>_/\\\
+<@prmt{~}\
+/
+s/^>_/@prmt/
+#.
+# Cursor
+#.
+s/__$/@curs/
+s/__\(.\)/\\\
+<@curs{\1}\
+/
+#.
+# Paths
+/\n<@dblq[^}]*[~/]/b protect
+/\n<@sglq[^}]*[~/]/b protect
+/\n<@span[^}]*[~/]/b protect
+#.
+# Normal Directory
+s|mkdir |mkdir :|
+s|\([~/:][/]*[.A-Za-z_0-9/-]*\)\\ |\1=|g
+s|\([~/][/]*[.A-Za-z_0-9/=-]*\)|\\\
+<@path{\1}\
+|g
+t protect
+s| \(:[/]*[.A-Za-z_0-9/=-]*\)|\\\
+<@path{\1}\
+|g
+t protect
+#.
+# Dot Relative Directory (no spaces in path)
+s| *\(./[A-Za-z_0-9/-]*\)| \\\
+<@path{\1}\
+|g
+b protect
+#.
+# Tidy up. Merge back 'pure' entities from hold space.
+:tidy
+#.
+# Uncomment the following 2 lines (ss) to log the pattern buffer.
+s/^.*$/PATT: &/w lexicon.log
+s/^PATT: //
+#.
+# Uncomment the following 4 lines (xssx) to log the hold buffer.
+x
+s/^.*$/HOLD: &/w lexicon.log
+s/^HOLD: //
+x
+#.
+# Tack the hold space to the end of the pattern buffer.
+G
+#.
+# Uncomment the folowing two lines (ss) to log the buffer join.
+s/^.*$/JOIN: &/w debug-lexicon.log
+s/^JOIN: //
+#.
+# Iterate over alternate lines, matching '<' to '\'
+:join
+s,\([^\\ ]*\)\\\n\([^<]*\)<\(@[^}]*[}\\]\),\1\3\2,
+t join
+# Clean up stray new lines
+s/\n//g
+#.
+# Uncomment the folowing two lines (ss) to log the buffer join.
+s/^.*$/PCLN: &/w lexicon.log
+s/^PCLN: //
+# Clean up special cases
+#.
+/@blah/{
+    s/\(blah{[^@]*\)@sglq{\([^}]*\)}/\1'\2'/
+    s/\(blah{[^@]*\)@dblq{\([^}]*\)}/\1"\2"/
+    s/\(blah{[^@]*\)@....{\([^}]*\)}/\1\2/
+}
+/@redr/{
+    :cleanredr
+    s/\(redr{[^@}]*\)@cmnd{\([^}]*\)}/\1\2/
+    s/\(redr{[^@}]*\)@func{\([^}]*\)}/\1\2/
+    s/\(redr{[^@}]*\)@sbin{\([^}]*\)}/\1\2/
+    s/\(redr{[^@}]*\)@fsfo{\([^}]*\)}/\1\2/
+    s/\(redr{[^}]*\)}\( *\)@path{\([^}]*\)/\1\2\3/
+    t cleanredr
+}
+/@sgst/ {
+    :cleansgst
+    s/\(sgst{@curs{.}[^@]*\)@cmnd{\([^}]*\)}/\1\2/
+    s/\(sgst{@curs{.}[^@]*\)@sbin{\([^}]*\)}/\1\2/
+    s/\(sgst{@curs{.}[^@]*\)@path{\([^}]*\)}/\1\2/
+    t cleansgst
+}
+/@fsfo/{
+    :cleanfsfo
+    s/\(fsfo{[^@}]*\)@cmnd{\([^}]*\)}/\1\2/
+    s/\(fsfo{[^@}]*\)@func{\([^}]*\)}/\1\2/
+    s/\(fsfo{[^@}]*\)@sbin{\([^}]*\)}/\1\2/
+    t cleanfsfo
+}
+#.
+# Restore Paths
+/@fsfo/ {
+    s/\(@fsfo{[^=]*\)=/\1 /
+}
+/@path/ {
+    :cleanpath
+    s/\(@path{[^:]*\):/\1/
+    s/\(@path{[^=]*\)=/\1\\ /
+    t cleanpath
+    s/@path{}//
+}
+#.
+# 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.
+#.
+# 'if' and 'for' seem to be special cases
+#.
+# Uncomment the folowing two lines (ss) to log the buffer join.
+s/^.*$/PREQ: &/w lexicon.log
+s/^PREQ: //
+#.
+# Find initial commands/functions/binaries
+#.
+# Store prmt, if present
+#.
+/@prmt/ {
+h
+s/^\(@prmt *\).*$/\1/
+x
+s/^@prmt *//
+}
+#.
+s/^\( *\)@sbin/\1@xbin/
+s/\( *[;()] *\)@sbin/\1@xbin/
+s/\( *@redr{|} *\)@sbin/\1@xbin/
+s/^\( *\)@cmnd/\1@xcmd/
+s/\( *[;()] *\)@cmnd/\1@xcmd/
+s/\( *@redr{|} *\)@cmnd/\1@xcmd/
+s/^\( *\)@func/\1@xfnc/
+s/\( *[;()] *\)@func/\1@xfnc/
+s/\( *@redr{|} *\)@func/\1@xfnc/
+
+s/@cmnd/@args/g
+s/@func/@args/g
+s/@sbin/@args/g
+
+s/^.*$/PSTQ: &/w lexicon.log
+s/^PSTQ: //
+#.
+s/xcmd/cmnd/g
+s/xfnc/func/g
+s/xbin/sbin/g
+x
+/^@prmt/ {
+G
+s/^@prmt \n/@prmt /
+}
+/^@prmt/ ! {
+x
+}
+#.
+# Mark up sesitive character entities.
+#.
+:entities
+s//\>/g
+s/((d))/@/g
+#.
+# Uncomment the folowing two lines (ss) to log the final output, sent to Doxygen.
+s/^.*$/OUT : &/w lexicon.log
+s/^OUT : //
+#.
+# Lines are reassembled, so branch to end
+b
+# === Main End ===
+#.
+#.
+# === Subroutines ===
+# Branched to when content requires.
+#.
+# Move protected content to hold space and mark up other entities.
+:protect
+h
+# Clear out any content that has already been marked up, to prevent futher
+# markup on words that should be left alone.
+#.
+:patternflush
+s/\n<@[^}]*[}\\]//
+s/\\ [^\\]*$/\\/
+t patternflush
+s/\n$//g
+#.
+# Swap the pattern and hold buffers and remove unmarked lines and extra
+# characters. Basically the inverse of the 'patternflush' action, with
+# additional trailing characters stripped.
+x
+/^\<@[^}]*$/ ! {
+s/[^\<]*//
+s/^ *\\\n//
+s/[()] \\//
+s/\n *\\//
+s/^[^\<][^@][^\\]*//
+s/\n[]|;) ][^\\]*\\//
+s/\n[]|;) a-zA-z0-9-][^\\]*$//
+s/\n[]|;)}]\\//
+s/\n[]|;)}]\n//
+s/\n[]|;)}]$//
+s/[()]$//
+s/}@curs/}/
+s/\n@curs$//
+s/\n[^\<@][^\\]*\\//
+s/\n[^\<@][^\\]*//
+s/^\\//
+s/\n$//g
+}
+#.
+# Swap the buffers back.
+x
+#.
+# A special case. Tidy up after commands.
+# Redirectors
+s/\([^{|] *\)|/\1@redr{|}/g
+s/\([^{&] *\)&[^a-z]/\1@redr{\&}/g
+s/\([^{<>^] *\)\([0-9]* *[<>^][<>^]*[^@][a-zA-Z0-9._-]*\)/\1@redr{\2}/g
+s/\\}/}\\/g
+#.
+# Now we can add in 'unsafe' entities that would be too greedy.
+# Declared Variables
+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
+#.
+# Fold Files into Paths
+s/\(@path{[^}]*\)}@fsfo/\1}@fsfo/
+#.
+:commands
+#.
+#### This section is built in the Makefile. Just some formatting examples. #####
+#.
+#   fish commands (cmnd) <- 4 character code that has a Doxygen alias counterpart
+#   template : s/[[:<:]]function[[:>:]]/@cmnd{&}/
+#.
+#   s,[[:<:]]function[[:>:]],@cmnd{function},g
+#   s,[[:<:]]begin[[:>:]],@cmnd{begin},g
+#   ...
+#.
+#   fish functions (func)
+#   Populated by 'public' functions' filename.
+#.
+#   s,[[:<:]]fish_pwd[[:>:]],@func{fish_pwd},g
+#   s,[[:<:]]fish_prompt[[:>:]],@func{fish_prompt},g
+#   ...
+#.
+#   Shell Binary (sbin)
+#   Populated from completion filenames
+#.
+#   s,[[:<:]]seq[[:>:]],@sbin{seq},g
+#   s,[[:<:]]rm[[:>:]],@sbin{rm},g
+#   ...
+#.
+#   Color Variable (clrv)
+#   Populated from __fish_config_interactive.fish
+#   Allows fish's 'special' color variables to be identified
+#.
+#   s,[[:<:]]fish_color_normal[[:>:]],@clrv{fish_color_normal},g
+#   s,[[:<:]]fish_color_command[[:>:]],@clrv{fish_color_command},g
+#.
+# Once all of the commands/functions/variables/special's have been marked up,
+# branch back to tidy up and collapse the pattern/hold buffers back to a
+# single line.
+#.
+# b tidy
-- 
cgit v1.2.3