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