mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-25 04:13:08 +00:00
Fix documentation
Restores erroneous changes to lexicon_filter and changes to doc_src/ pages. Done by hand to ensure version history. Fixes display of % when misinterpreted by Doxygen.
This commit is contained in:
Mark Griffiths
Kurtis Rader
parent
190fb4a665
commit
b2be50f081
8 changed files with 174 additions and 165 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Formatting guide for fish docs
|
||||
|
||||
The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs, the developer docs and the man pages.
|
||||
The fish documentation has been updated to support Doxygen 1.8.7+, and while the main benefit of this change is extensive Markdown support, the addition of a fish lexicon and syntax filter, combined with semantic markup rules allows for automatic formatting enhancements across the HTML user_docs and man pages.
|
||||
|
||||
Initially my motivation was to fix a problem with long options ([Issue #1557](https://github.com/fish-shell/fish-shell/issues/1557) on GitHub), but as I worked on fixing the issue I realised there was an opportunity to simplify, reinforce and clarify the current documentation, hopefully making further contribution easier and cleaner, while allowing the documentation examples to presented more clearly with less author effort.
|
||||
|
||||
|
|
@ -60,14 +60,10 @@ which is then transformed by Doxygen into an HTML version (`make doc`):
|
|||
|
||||
`<span class="command">echo</span> <span class="argument">hello</span> <span class="argument">world</span>`
|
||||
|
||||
A man page version (`make share/man`):
|
||||
And a man page version (`make share/man`):
|
||||
|
||||
__echo__ hello world
|
||||
|
||||
And a simple HTML version for the developer docs (`make doc`) and the LATEX/PDF manual (`make doc/refman.pdf`):
|
||||
|
||||
`echo hello world`
|
||||
|
||||
### Fonts
|
||||
|
||||
In older browsers, it was easy to set the fonts used for the three basic type styles (serif, sans-serif and monospace). Modern browsers have removed these options in their respective quests for simplification, assuming the content author will provide suitable styles for the content in the site's CSS, or the end user will provide overriding styles manually. Doxygen's default styling is very simple and most users will just accept this default.
|
||||
|
|
@ -154,22 +150,25 @@ The following can be used in \\fish blocks to render some fish scenarios. These
|
|||
|
||||
### Custom formatting tags
|
||||
|
||||
- `{{` and `}}`: Required when wanting curly braces in regular expression example.
|
||||
- `\\asis`: \\asis\{This text will not be parsed for fish markup.\}
|
||||
- `\\bksl`: \\bksl\{Render the contents with a preceding backslash. Useful when presenting output.}
|
||||
- `\\eror`: \\eror\{This would be shown as an error.\}
|
||||
- `\\mtch`: \\mtch\{Matched\} items, such as tab completions.
|
||||
- `\\outp`: \\outp\{This would be rendered as command/script output.\}
|
||||
- `\\sgst`: auto\\sgst\{suggestion\}.
|
||||
- `\\smtc`: Matched items \\smtc\{searched\} for, like grep results.
|
||||
- `\\undr`: \\undr\{These words are underlined\}.
|
||||
```html
|
||||
<u>: <u>These words are underlined.</u>
|
||||
<s>: auto<s>suggestion</s>.
|
||||
<m>: <m>Matched</m> items, such as tab completions.
|
||||
<sm>: Matched items <sm>searched</sm> for, like grep results.
|
||||
<bs>: Render the contents with a preceding backslash. Useful when presenting output.
|
||||
<error>: <error>This would be shown as an error.</error>
|
||||
<asis>: <asis>This text will not be parsed for fish markup.</asis>
|
||||
<outp>: <outp>This would be rendered as command/script output.</outp>
|
||||
{{ and }}: Required when wanting curly braces in regular expression example.
|
||||
```
|
||||
|
||||
### Prompts and cursors
|
||||
|
||||
- `>_`: Display a basic prompt.
|
||||
- `~>_`: Display a prompt with a the home directory as the current working directory.
|
||||
- `___` (3 underscores): Display a cursor.
|
||||
|
||||
```html
|
||||
>_: Display a basic prompt.
|
||||
~>_: Display a prompt with a the home directory as the current working directory.
|
||||
___ (3 underscores): Display a cursor.
|
||||
```
|
||||
|
||||
### Keyboard shortcuts: @key{} and @cursor_key{}
|
||||
|
||||
|
|
@ -251,15 +250,4 @@ end
|
|||
# NOT PORTABLE! Paths would be need to be updated on other systems.
|
||||
```
|
||||
|
||||
### Developer docs and LATEX/PDF output
|
||||
|
||||
- HTML developer docs tested on Ubuntu 14.04, CentOS 6.5 and Mac OS X 10.9.
|
||||
- LATEX/PDF reference manual tested on Mac OS X 10.9 using MacTEX. PDF production returns an error (due to Doxygen's use of an outdated 'float' package), but manual PDF output is ok.
|
||||
|
||||
### Future changes
|
||||
|
||||
1. The documentation creation process would be better if it could be modularised further and moved out of the makefile into a number of supporting scripts. This would allow both the automake and Xcode build processes to use the documentation scripts directly.
|
||||
2. Remove the Doxygen dependency entirely for the user documentation. This would be very acheivable now that the bulk of the documentation is in Markdown.
|
||||
3. It would be useful to gauge what parts of the documentation are actually used by users. Judging by the amount of 'missing comment' errors during the developer docs build phase, this aspect of the docs has been rather neglected. If it is not longer used or useful, then this could change the future direction of the documentation and significantly streamline the process.
|
||||
|
||||
#### Author: Mark Griffiths [@GitHub](https://github.com/MarkGriffiths)
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ fg [PID]
|
|||
|
||||
`fg` brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
|
||||
|
||||
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.
|
||||
The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>. Fish is capable of expanding far more than just the numeric PID, including referencing itself and finding PIDs by name.
|
||||
|
||||
|
||||
\subsection fg-example Example
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ rm "cumbersome filename.txt"
|
|||
Will remove the file 'cumbersome filename.txt', while
|
||||
|
||||
\fish
|
||||
rm \asis{cumbersome filename.txt}
|
||||
rm <asis>cumbersome filename.txt</asis>
|
||||
\endfish
|
||||
|
||||
would remove the two files 'cumbersome' and 'filename.txt'.
|
||||
|
|
@ -553,22 +553,22 @@ Lists adjacent to other lists or strings are expanded as cartesian products:
|
|||
Examples:
|
||||
\fish{cli-dark}
|
||||
>_ echo {good,bad}" apples"
|
||||
\outp{good apples bad apples}
|
||||
<outp>good apples bad apples</outp>
|
||||
|
||||
>_ set -l a x y z
|
||||
>_ set -l b 1 2 3
|
||||
|
||||
>_ echo $a$b
|
||||
\outp{x1 y1 z1 x2 y2 z2 x3 y3 z3}
|
||||
<outp>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
|
||||
|
||||
>_ echo $a"-"$b
|
||||
\outp{x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3}
|
||||
<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>x1 y1 z1 x2 y2 z2 x3 y3 z3</outp>
|
||||
|
||||
>_ echo {$b}word
|
||||
\outp{1word 2word 3word}
|
||||
<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`).
|
||||
|
|
@ -639,7 +639,7 @@ This form of expansion is useful for commands like kill and fg, which take proce
|
|||
|
||||
Example:
|
||||
|
||||
`fg %ema` will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground.
|
||||
`fg %%ema` will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground.
|
||||
|
||||
`kill -s SIGINT %3` will send the SIGINT signal to the job with job ID 3.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,16 +16,16 @@ To change the number of characters per path component, set $fish_prompt_pwd_dir_
|
|||
\fish{cli-dark}
|
||||
>_ cd ~/
|
||||
>_ echo $PWD
|
||||
\outp{/home/alfa}
|
||||
<outp>/home/alfa</outp>
|
||||
|
||||
>_ prompt_pwd
|
||||
\outp{~}
|
||||
<outp>~</outp>
|
||||
|
||||
>_ cd /tmp/banana/sausage/with/mustard
|
||||
>_ prompt_pwd
|
||||
\outp{/t/b/s/w/mustard}
|
||||
<outp>/t/b/s/w/mustard</outp>
|
||||
|
||||
>_ set -g fish_prompt_pwd_dir_length 3
|
||||
>_ prompt_pwd
|
||||
\outp{/tmp/ban/sau/wit/mustard}
|
||||
<outp>/tmp/ban/sau/wit/mustard</outp>
|
||||
\endfish
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ In general, special characters are special by default, so `a+` matches one or mo
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ string length 'hello, world'
|
||||
\outp{12}
|
||||
<outp>12</outp>
|
||||
|
||||
>_ set str foo
|
||||
>_ string length -q $str; echo $status
|
||||
|
|
@ -68,125 +68,125 @@ In general, special characters are special by default, so `a+` matches one or mo
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ string sub --length 2 abcde
|
||||
\outp{ab}
|
||||
<outp>ab</outp>
|
||||
|
||||
>_ string sub -s 2 -l 2 abcde
|
||||
\outp{bc}
|
||||
<outp>bc</outp>
|
||||
|
||||
>_ string sub --start=-2 abcde
|
||||
\outp{de}
|
||||
<outp>de</outp>
|
||||
\endfish
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ string split . example.com
|
||||
\outp{example}
|
||||
\outp{com}
|
||||
<outp>example</outp>
|
||||
<outp>com</outp>
|
||||
|
||||
>_ string split -r -m1 / /usr/local/bin/fish
|
||||
\outp{/usr/local/bin}
|
||||
\outp{fish}
|
||||
<outp>/usr/local/bin</outp>
|
||||
<outp>fish</outp>
|
||||
|
||||
>_ string split '' abc
|
||||
\outp{a}
|
||||
\outp{b}
|
||||
\outp{c}
|
||||
<outp>a</outp>
|
||||
<outp>b</outp>
|
||||
<outp>c</outp>
|
||||
\endfish
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ seq 3 | string join ...
|
||||
\outp{1...2...3}
|
||||
<outp>1...2...3</outp>
|
||||
\endfish
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ string trim ' abc '
|
||||
\outp{abc}
|
||||
<outp>abc</outp>
|
||||
|
||||
>_ string trim --right --chars=yz xyzzy zany
|
||||
\outp{x}
|
||||
\outp{zan}
|
||||
<outp>x</outp>
|
||||
<outp>zan</outp>
|
||||
\endfish
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ echo \\x07 | string escape
|
||||
\bksl{cg}
|
||||
<bs>cg</bs>
|
||||
\endfish
|
||||
|
||||
\subsection string-example-match-glob Match Glob Examples
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ string match '?' a
|
||||
\outp{a}
|
||||
<outp>a</outp>
|
||||
|
||||
>_ string match 'a*b' axxb
|
||||
\outp{axxb}
|
||||
<outp>axxb</outp>
|
||||
|
||||
>_ string match -i 'a??B' Axxb
|
||||
\outp{Axxb}
|
||||
<outp>Axxb</outp>
|
||||
|
||||
>_ echo 'ok?' | string match '*\\?'
|
||||
>_ \outp{ok?}
|
||||
>_ <outp>ok?</outp>
|
||||
\endfish
|
||||
|
||||
\subsection string-example-match-regex Match Regex Examples
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ string match -r 'cat|dog|fish' 'nice dog'
|
||||
\outp{dog}
|
||||
<outp>dog</outp>
|
||||
|
||||
>_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4)
|
||||
\outp{dog1}
|
||||
\outp{dog2}
|
||||
\outp{cat3}
|
||||
\outp{dog3}
|
||||
\outp{cat4}
|
||||
\outp{dog4}
|
||||
\endfish
|
||||
<outp>dog1</outp>
|
||||
<outp>dog2</outp>
|
||||
<outp>cat3</outp>
|
||||
<outp>dog3</outp>
|
||||
<outp>cat4</outp>
|
||||
<outp>dog4</outp>
|
||||
|
||||
>_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' \asis{2:34:56}
|
||||
\outp{2:34:56}
|
||||
\outp{2}
|
||||
\outp{34}
|
||||
\outp{56}
|
||||
>_ 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 match -r '^(\\w{{2,4}})\\g1$' papa mud murmur
|
||||
\outp{papa}
|
||||
\outp{pa}
|
||||
\outp{murmur}
|
||||
\outp{mur}
|
||||
<outp>papa</outp>
|
||||
<outp>pa</outp>
|
||||
<outp>murmur</outp>
|
||||
<outp>mur</outp>
|
||||
|
||||
>_ string match -r -a -n at ratatat
|
||||
\outp{2 2}
|
||||
\outp{4 2}
|
||||
\outp{6 2}
|
||||
<outp>2 2</outp>
|
||||
<outp>4 2</outp>
|
||||
<outp>6 2</outp>
|
||||
|
||||
>_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;'
|
||||
\outp{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>blue was my favorite</outp>
|
||||
|
||||
>_ string replace 3rd last 1st 2nd 3rd
|
||||
\outp{1st}
|
||||
\outp{2nd}
|
||||
\outp{last}
|
||||
<outp>1st</outp>
|
||||
<outp>2nd</outp>
|
||||
<outp>last</outp>
|
||||
|
||||
>_ string replace -a ' ' _ 'spaces to underscores'
|
||||
\outp{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>0 3.14 5</outp>
|
||||
|
||||
>_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right'
|
||||
\outp{right left $}
|
||||
<outp>right left $</outp>
|
||||
|
||||
>_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here'
|
||||
\outp{put a}
|
||||
\outp{here}
|
||||
<outp>put a</outp>
|
||||
<outp>here</outp>
|
||||
\endfish
|
||||
|
|
|
|||
|
|
@ -54,9 +54,9 @@ If you have a strong understanding of other shells, and want to know what `fish`
|
|||
When you start `fish`, you should see this:
|
||||
|
||||
\fish{cli-dark}
|
||||
\outp{Welcome to fish, the friendly interactive shell}
|
||||
\outp{Type <span class="cwd">help</span> for instructions on how to use fish}
|
||||
\asis{you@hostname} ~>____
|
||||
<outp>Welcome to fish, the friendly interactive shell</outp>
|
||||
<outp>Type <span class="cwd">help</span> for instructions on how to use fish</outp>
|
||||
<asis>you@hostname</asis> ~>____
|
||||
\endfish
|
||||
|
||||
`fish` comes with a default prompt that shows your username, hostname, and working directory. You'll see <a href="#tut_prompt">how to change your prompt</a> further down. From now on, we'll pretend your prompt is just a '`>`' to save space.
|
||||
|
|
@ -68,7 +68,7 @@ When you start `fish`, you should see this:
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ echo hello world
|
||||
\outp{hello world}
|
||||
<outp>hello world</outp>
|
||||
\endfish
|
||||
|
||||
You can include a literal space in an argument with a backslash, or by using single or double quotes:
|
||||
|
|
@ -77,7 +77,7 @@ You can include a literal space in an argument with a backslash, or by using sin
|
|||
>_ mkdir My\ Files
|
||||
>_ cp ~/Some\ File 'My Files'
|
||||
>_ ls "My Files"
|
||||
\outp{Some File}
|
||||
<outp>Some File</outp>
|
||||
\endfish
|
||||
|
||||
Commands can be chained with semicolons.
|
||||
|
|
@ -89,8 +89,8 @@ Commands can be chained with semicolons.
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ man set
|
||||
\outp{set - handle shell variables}
|
||||
\outp{ Synopsis...}
|
||||
<outp>set - handle shell variables</outp>
|
||||
<outp> Synopsis...</outp>
|
||||
\endfish
|
||||
|
||||
|
||||
|
|
@ -99,7 +99,7 @@ Commands can be chained with semicolons.
|
|||
You'll quickly notice that `fish` performs syntax highlighting as you type. Invalid commands are colored red by default:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ \eror{/bin/mkd}
|
||||
>_ <eror>/bin/mkd</eror>
|
||||
\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:
|
||||
|
|
@ -111,7 +111,7 @@ A command may be invalid because it does not exist, or refers to a file that you
|
|||
`fish` will underline valid file paths as you type them:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ cat \undr{~/somefi}___
|
||||
>_ cat <u>~/somefi</u>___
|
||||
\endfish
|
||||
|
||||
This tells you that there exists a file that starts with '`somefi`', which is useful feedback as you type.
|
||||
|
|
@ -125,25 +125,25 @@ These colors, and many more, can be changed by running `fish_config`, or by modi
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ ls *.jpg
|
||||
\outp{lena.jpg}
|
||||
\outp{meena.jpg}
|
||||
\outp{santa maria.jpg}
|
||||
<outp>lena.jpg</outp>
|
||||
<outp>meena.jpg</outp>
|
||||
<outp>santa maria.jpg</outp>
|
||||
\endfish
|
||||
|
||||
You can include multiple wildcards:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ ls l*.p*
|
||||
\outp{lena.png}
|
||||
\outp{lesson.pdf}
|
||||
<outp>lena.png</outp>
|
||||
<outp>lesson.pdf</outp>
|
||||
\endfish
|
||||
|
||||
Especially powerful is the recursive wildcard ** which searches directories recursively:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ ls /var/**.log
|
||||
\outp{/var/log/system.log}
|
||||
\outp{/var/run/sntp.log}
|
||||
<outp>/var/log/system.log</outp>
|
||||
<outp>/var/run/sntp.log</outp>
|
||||
\endfish
|
||||
|
||||
If that directory traversal is taking a long time, you can @key{Control,C} out of it.
|
||||
|
|
@ -155,7 +155,7 @@ You can pipe between commands with the usual vertical bar:
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ echo hello world | wc
|
||||
\outp{ 1 2 12}
|
||||
<outp> 1 2 12</outp>
|
||||
\endfish
|
||||
|
||||
stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^
|
||||
|
|
@ -170,19 +170,19 @@ 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}
|
||||
>_ \eror{/bin/h}\sgst{___ostname}
|
||||
>_ <eror>/bin/h</eror><s>___ostname</s>
|
||||
\endfish
|
||||
|
||||
It knows about paths and options:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ grep --i\sgst{___gnore-case}
|
||||
>_ grep --i<s>___gnore-case</s>
|
||||
\endfish
|
||||
|
||||
And history too. Type a command once, and you can re-summon it by just typing a few letters:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ \eror{r<}\sgst{___sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo}
|
||||
>_ <eror>r<</eror><s>___sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo</s>
|
||||
\endfish
|
||||
|
||||
To accept the autosuggestion, hit @cursor_key{→,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.
|
||||
|
|
@ -194,14 +194,14 @@ To accept the autosuggestion, hit @cursor_key{→,right arrow} or @key{Contro
|
|||
Press @key{Tab}, and `fish` will attempt to complete the command, argument, or path:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ \eror{/pri} @key{Tab} → /private/
|
||||
>_ <eror>/pri</eror> @key{Tab} → /private/
|
||||
\endfish
|
||||
|
||||
If there's more than one possibility, it will list them:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ \eror{~/stuff/s} @key{Tab}
|
||||
\outp{\mtch{~/stuff/s}cript.sh <i>(Executable, 4.8kB)</i> \mtch{~/stuff/s}ources/ <i>(Directory)</i>}
|
||||
>_ <eror>~/stuff/s</eror> @key{Tab}
|
||||
<outp><mtch>~/stuff/s</outp>cript.sh <i>(Executable, 4.8kB)</i> \mtch{~/stuff/s</mtch>ources/ <i>(Directory)</i>}
|
||||
\endfish
|
||||
|
||||
Hit tab again to cycle through the possibilities.
|
||||
|
|
@ -211,7 +211,7 @@ Hit tab again to cycle through the possibilities.
|
|||
\fish{cli-dark}
|
||||
>_ git merge pr @key{Tab} → git merge prompt_designer
|
||||
>_ git checkout b @key{Tab}
|
||||
\outp{\mtch{b}uiltin_list_io_merge <i>(Branch)</i> \mtch{b}uiltin_set_color <i>(Branch)</i> \mtch{b}usted_events <i>(Tag)</i>}
|
||||
<outp><mtch>b</outp>uiltin_list_io_merge <i>(Branch)</i> \mtch{b</mtch>uiltin_set_color <i>(Branch)</i> <mtch>b</mtch>usted_events <i>(Tag)</i>}
|
||||
\endfish
|
||||
|
||||
Try hitting tab and see what `fish` can do!
|
||||
|
|
@ -222,16 +222,16 @@ Like other shells, a dollar sign performs variable substitution:
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ echo My home directory is $HOME
|
||||
\outp{My home directory is /home/tutorial}
|
||||
<outp>My home directory is /home/tutorial</outp>
|
||||
\endfish
|
||||
|
||||
Variable substitution also occurs in double quotes, but not single quotes:
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ echo "My current directory is $PWD"
|
||||
\outp{My current directory is /home/tutorial}
|
||||
<outp>My current directory is /home/tutorial</outp>
|
||||
>_ echo 'My current directory is $PWD'
|
||||
\outp{My current directory is $PWD}
|
||||
<outp>My current directory is $PWD</outp>
|
||||
\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.
|
||||
|
|
@ -239,7 +239,7 @@ Unlike other shells, `fish` has no dedicated syntax for setting variables. Inste
|
|||
\fish{cli-dark}
|
||||
>_ set name 'Mister Noodle'
|
||||
>_ echo $name
|
||||
\outp{Mister Noodle}
|
||||
<outp>Mister Noodle</outp>
|
||||
\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.)
|
||||
|
|
@ -249,7 +249,7 @@ Unlike other shells, variables are not further split after substitution:
|
|||
\fish{cli-dark}
|
||||
>_ mkdir $name
|
||||
>_ ls
|
||||
\outp{Mister Noodle}
|
||||
<outp>Mister Noodle</outp>
|
||||
\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. Other shells use the term "arrays", rather than lists.
|
||||
|
|
@ -262,7 +262,7 @@ Unlike other shells, `fish` stores the exit status of the last command in `$stat
|
|||
\fish{cli-dark}
|
||||
>_ false
|
||||
>_ echo $status
|
||||
\outp{1}
|
||||
<outp>1</outp>
|
||||
\endfish
|
||||
|
||||
Zero is considered success, and non-zero is failure.
|
||||
|
|
@ -275,7 +275,7 @@ Unlike other shells, `fish` does not have an export command. Instead, a variable
|
|||
\fish{cli-dark}
|
||||
>_ set -x MyVariable SomeValue
|
||||
>_ env | grep MyVariable
|
||||
\outp{\smtc{MyVariablem}=SomeValue}
|
||||
<outp><m>MyVariablem</outp>=SomeValue</m>
|
||||
\endfish
|
||||
|
||||
You can erase a variable with `-e` or `--erase`
|
||||
|
|
@ -283,7 +283,7 @@ You can erase a variable with `-e` or `--erase`
|
|||
\fish{cli-dark}
|
||||
>_ set -e MyVariable
|
||||
>_ env | grep MyVariable
|
||||
\outp{(no output)}
|
||||
<outp>(no output)</outp>
|
||||
\endfish
|
||||
|
||||
|
||||
|
|
@ -297,7 +297,7 @@ Other variables, like `$PATH`, really do have multiple values. During variable e
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ echo $PATH
|
||||
\outp{/usr/bin /bin /usr/sbin /sbin /usr/local/bin}
|
||||
<outp>/usr/bin /bin /usr/sbin /sbin /usr/local/bin</outp>
|
||||
\endfish
|
||||
|
||||
Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop.
|
||||
|
|
@ -306,7 +306,7 @@ Get the length of a list with `count`:
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ count $PATH
|
||||
\outp{5}
|
||||
<outp>5</outp>
|
||||
\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:
|
||||
|
|
@ -320,20 +320,20 @@ You can access individual elements with square brackets. Indexing starts at 1 fr
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ echo $PATH
|
||||
\outp{/usr/bin /bin /usr/sbin /sbin /usr/local/bin}
|
||||
<outp>/usr/bin /bin /usr/sbin /sbin /usr/local/bin</outp>
|
||||
>_ echo $PATH[1]
|
||||
\outp{/usr/bin}
|
||||
<outp>/usr/bin</outp>
|
||||
>_ echo $PATH[-1]
|
||||
\outp{/usr/local/bin}
|
||||
<outp>/usr/local/bin</outp>
|
||||
\endfish
|
||||
|
||||
You can also access ranges of elements, known as "slices:"
|
||||
|
||||
\fish{cli-dark}
|
||||
>_ echo $PATH[1..2]
|
||||
\outp{/usr/bin /bin}
|
||||
<outp>/usr/bin /bin</outp>
|
||||
>_ echo $PATH[-1..2]
|
||||
\outp{/usr/local/bin /sbin /usr/sbin /bin}
|
||||
<outp>/usr/local/bin /sbin /usr/sbin /bin</outp>
|
||||
\endfish
|
||||
|
||||
You can iterate over a list (or a slice) with a for loop:
|
||||
|
|
@ -342,11 +342,11 @@ You can iterate over a list (or a slice) with a for loop:
|
|||
>_ for val in $PATH
|
||||
echo "entry: $val"
|
||||
end
|
||||
\outp{entry: /usr/bin/}
|
||||
\outp{entry: /bin}
|
||||
\outp{entry: /usr/sbin}
|
||||
\outp{entry: /sbin}
|
||||
\outp{entry: /usr/local/bin}
|
||||
<outp>entry: /usr/bin/</outp>
|
||||
<outp>entry: /bin</outp>
|
||||
<outp>entry: /usr/sbin</outp>
|
||||
<outp>entry: /sbin</outp>
|
||||
<outp>entry: /usr/local/bin</outp>
|
||||
\endfish
|
||||
|
||||
Lists adjacent to other lists or strings are expanded as <a href="index.html#cartesian-product">cartesian products</a> unless quoted (see <a href="index.html#expand-variable">Variable expansion</a>):
|
||||
|
|
@ -355,11 +355,11 @@ Lists adjacent to other lists or strings are expanded as <a href="index.html#car
|
|||
>_ set -l a 1 2 3
|
||||
>_ set -l 1 a b c
|
||||
>_ echo $a$1
|
||||
\outp{1a 2a 3a 1b 2b 3b 1c 2c 3c}
|
||||
<outp>1a 2a 3a 1b 2b 3b 1c 2c 3c</outp>
|
||||
>_ echo $a" banana"
|
||||
\outp{1 banana 2 banana 3 banana}
|
||||
<outp>1 banana 2 banana 3 banana</outp>
|
||||
>_ echo "$a banana"
|
||||
\outp{1 2 3 banana}
|
||||
<outp>1 2 3 banana</outp>
|
||||
\endfish
|
||||
|
||||
This is similar to <a href="index.html#expand-brace">Brace expansion</a>.
|
||||
|
|
@ -370,7 +370,7 @@ Command substitutions use the output of one command as an argument to another. U
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ echo In (pwd), running (uname)
|
||||
\outp{In /home/tutorial, running FreeBSD}
|
||||
<outp>In /home/tutorial, running FreeBSD</outp>
|
||||
\endfish
|
||||
|
||||
A common idiom is to capture the output of a command in a variable:
|
||||
|
|
@ -378,7 +378,7 @@ A common idiom is to capture the output of a command in a variable:
|
|||
\fish{cli-dark}
|
||||
>_ set os (uname)
|
||||
>_ echo $os
|
||||
\outp{Linux}
|
||||
<outp>Linux</outp>
|
||||
\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:
|
||||
|
|
@ -386,7 +386,7 @@ Command substitutions are not expanded within quotes. Instead, you can temporari
|
|||
\fish{cli-dark}
|
||||
>_ touch <i class="quote">"testing_"</i>(date +%s)<i class="quote">".txt"</i>
|
||||
>_ ls *.txt
|
||||
\outp{testing_1360099791.txt}
|
||||
<outp>testing_1360099791.txt</outp>
|
||||
\endfish
|
||||
|
||||
|
||||
|
|
@ -396,7 +396,7 @@ Unlike other shells, `fish` does not have special syntax like && or || t
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ cp file1.txt file1_bak.txt; and echo "Backup successful"; or echo "Backup failed"
|
||||
\outp{Backup failed}
|
||||
<outp>Backup failed</outp>
|
||||
\endfish
|
||||
|
||||
|
||||
|
|
@ -441,9 +441,9 @@ A `fish` function is a list of commands, which may optionally take arguments. Un
|
|||
echo Hello $argv
|
||||
end
|
||||
>_ say_hello
|
||||
\outp{Hello}
|
||||
<outp>Hello</outp>
|
||||
>_ say_hello everybody!
|
||||
\outp{Hello everybody!}
|
||||
<outp>Hello everybody!</outp>
|
||||
\endfish
|
||||
|
||||
Unlike other shells, `fish` does not have aliases or special prompt syntax. Functions take their place.
|
||||
|
|
@ -452,7 +452,7 @@ You can list the names of all functions with the `functions` keyword (note the p
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ functions
|
||||
\outp{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, trap, type, umask, up-or-search, vared}
|
||||
<outp>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, trap, type, umask, up-or-search, vared</outp>
|
||||
\endfish
|
||||
|
||||
You can see the source for any function by passing its name to `functions`:
|
||||
|
|
@ -473,10 +473,10 @@ While loops:
|
|||
>_ while true
|
||||
echo <i class="quote">"Loop forever"</i>
|
||||
end
|
||||
\outp{Loop forever}
|
||||
\outp{Loop forever}
|
||||
\outp{Loop forever}
|
||||
\outp{...}
|
||||
<outp>Loop forever</outp>
|
||||
<outp>Loop forever</outp>
|
||||
<outp>Loop forever</outp>
|
||||
<outp>...</outp>
|
||||
\endfish
|
||||
|
||||
For loops can be used to iterate over a list. For example, a list of files:
|
||||
|
|
@ -506,7 +506,7 @@ You can define your own prompt:
|
|||
>_ function fish_prompt
|
||||
echo "New Prompt % "
|
||||
end
|
||||
\asis{New Prompt % }___
|
||||
<asis>New Prompt % </asis>___
|
||||
\endfish
|
||||
|
||||
Multiple lines are OK. Colors can be set via `set_color`, passing it named ANSI colors, or hex RGB values:
|
||||
|
|
|
|||
|
|
@ -28,5 +28,5 @@ The following options are available:
|
|||
|
||||
\fish{cli-dark}
|
||||
>_ type fg
|
||||
\outp{fg is a builtin}
|
||||
<outp>fg is a builtin</outp>
|
||||
\endfish
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
# art text processor from the 70's. Who's sed? sed's dead, baby, sed's dead.*
|
||||
# by Mark Griffiths <mark@thebespokepixel.com> *but quite portable
|
||||
#.
|
||||
# Finds /fish../endfish blocks in documentation source files and enhances
|
||||
# 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.:
|
||||
#.
|
||||
|
|
@ -71,17 +71,6 @@
|
|||
/<[^>]*>/ {
|
||||
b html
|
||||
}
|
||||
# Preprocess specially recognized commands.
|
||||
s/\\asis/@asis/g
|
||||
s/\\bksl/@bksl/g
|
||||
s/\\bold/@bold/g
|
||||
s/\\emph/@emph/g
|
||||
s/\\eror/@eror/g
|
||||
s/\\mtch/@mtch/g
|
||||
s/\\outp/@outp/g
|
||||
s/\\sgst/@sgst/g
|
||||
s/\\smtc/@smtc/g
|
||||
s/\\undr/@undr/g
|
||||
# Process the rest
|
||||
b process
|
||||
}
|
||||
|
|
@ -105,7 +94,7 @@ s|<b>|@bold{|
|
|||
s|<b [^>]*>|@bold{|
|
||||
s|</b>|}|
|
||||
#.
|
||||
# Strong (synonymous with emphasis)
|
||||
# Strong (synonimous with emphasis)
|
||||
s|<strong>|@bold{|
|
||||
s|<strong [^>]*>|@bold{|
|
||||
s|</strong>|}|
|
||||
|
|
@ -124,7 +113,39 @@ 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
|
||||
# autoSuGgeSTion
|
||||
s|<s>|@sgst{|
|
||||
s|<s [^>]*>|@sgst{|
|
||||
s|</s>|}|
|
||||
#.
|
||||
# MaTCH
|
||||
s|<m>|@mtch{|
|
||||
s|<m [^>]*>|@mtch{|
|
||||
s|</m>|}|
|
||||
#.
|
||||
# SearchMaTCh
|
||||
s|<sm>|@smtc{|
|
||||
s|<sm [^>]*>|@smtc{|
|
||||
s|</sm>|}|
|
||||
#.
|
||||
# ERrOR
|
||||
s|<error>|@eror{|
|
||||
s|<error [^>]*>|@eror{|
|
||||
s|</error>|}|
|
||||
#.
|
||||
# AsIs - protect from auto-formatting
|
||||
s|<asis>|@asis{|
|
||||
s|</asis>|}|
|
||||
#.
|
||||
# OUTPut - protect from auto-formatting
|
||||
s|<outp>|@outp{|
|
||||
s|</outp>|}|
|
||||
t html
|
||||
#.
|
||||
# Clean other unhandled html
|
||||
|
|
|
|||
Loading…
Reference in a new issue