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>
This commit is contained in:
Mark Griffiths 2016-04-04 13:43:37 +01:00 committed by Kurtis Rader
parent 47f1a92cc4
commit cb6d5d76c8
13 changed files with 180 additions and 171 deletions

View File

@ -274,6 +274,8 @@ ALIASES += "span{2}=\2"
ALIASES += "spcl{2}=\2"
ALIASES += "bksl{1}=\\\1"
ALIASES += "pcnt{1}=\%\1"
ALIASES += "atat{1}=\@"
# 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"

View File

@ -274,6 +274,8 @@ ALIASES += "span{2}=\2"
ALIASES += "spcl{2}=\2"
ALIASES += "bksl{1}=\\\1"
ALIASES += "pcnt{1}=\%\1"
ALIASES += "atat{1}=\@"
# 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"

View File

@ -274,6 +274,8 @@ ALIASES += "span{2}=<span style=\"\1\">\2</span>"
ALIASES += "spcl{2}=<span class=\"\1\">\2</span>"
ALIASES += "bksl{1}=<span>\</span>\1"
ALIASES += "pcnt{1}=<span>%</span>\1"
ALIASES += "atat{1}=<span>@</span>"
# 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"

View File

@ -276,9 +276,9 @@ doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h \
(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
cd user_doc/html && rm -f arrow*.png bc_s.png bdwn.png closed.png \
doc.png folder*.png ftv2*.png nav*.png open.png splitbar.png \
sync_*.png tab*.* doxygen.* dynsections.js jquery.js pages.html
#
# PDF version of the source code documentation.

View File

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

View File

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

View File

@ -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
# 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'
>_ set -l a x y z
>_ set -l b 1 2 3
echo {x,y,z}$b
# Outputs 'x1 y1 z1 x2 y2 z2 x3 y3 z3'
>_ echo $a$b
<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
echo {$b}word
# Outputs '1word 2word 3word'
>_ 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
<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
>_ 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`).

View File

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

View File

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

View File

@ -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
\fish{cli-dark}
>_ string split . example.com
<outp>example</outp>
<outp>com</outp>
string split -r -m1 / /usr/local/bin/fish
# Output:
# /usr/local/bin
# fish
>_ string split -r -m1 / /usr/local/bin/fish
<outp>/usr/local/bin</outp>
<outp>fish</outp>
string split '' abc
# Output:
# a
# b
# c
>_ 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
\subsection string-example-match-glob Match Glob Examples
string match '?' a
# Output:
# a
\fish{cli-dark}
>_ string match '?' a
<outp>a</outp>
string match 'a*b' axxb
# Output:
# axxb
>_ string match 'a*b' axxb
<outp>axxb</outp>
string match -i 'a??B' Axxb
# Output:
# Axxb
>_ string match -i 'a??B' Axxb
<outp>Axxb</outp>
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
>_ echo 'ok?' | string match '*\\?'
>_ <outp>ok?</outp>
\endfish
\fish
\subsection string-example-match-regex Match Regex Examples
# string replace literal examples
\fish{cli-dark}
>_ string match -r 'cat|dog|fish' 'nice dog'
<outp>dog</outp>
string replace is was 'blue is my favorite'
# Output:
# blue was my favorite
>_ 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 3rd last 1st 2nd 3rd
# Output:
# 1st
# 2nd
# last
>_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur
<outp>papa</outp>
<outp>pa</outp>
<outp>murmur</outp>
<outp>mur</outp>
string replace -a ' ' _ 'spaces to underscores'
# Output:
# spaces_to_underscores
>_ string match -r -a -n at ratatat
<outp>2 2</outp>
<outp>4 2</outp>
<outp>6 2</outp>
# string replace regex examples
string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x'
# Output:
# 0 3.14 5
string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right'
# Output:
# right left $
string replace -r '\\s*newline\\s*' '\n' 'put a newline here'
# Output:
# put a
# here
>_ 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
\subsection string-example-replace-Regex Replace Regex Examples
\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'
<outp>right left $</outp>
>_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here'
<outp>put a</outp>
<outp>here</outp>
\endfish

View File

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

View File

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

View File

@ -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. #####
#.