refine docs

mitnk · May 27, 2020 · 0074d61 · 0074d61
1 parent 089c174
commit 0074d61
Show file tree

Hide file tree

Showing 11 changed files with 182 additions and 113 deletions.
diff --git a/README.md b/README.md
@@ -89,8 +89,8 @@ Read APIs here: [https://docs.rs/cicada/](https://docs.rs/cicada/).
 
 ## FAQs
 
-- [Why another shell?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#why-another-shell)
-- [Compare to bash/zsh/etc?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#compare-to-other-shells)
-- [Is cicada POSIX-compatible?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#is-cicada-posix-compatible)
-- [Will my bash/zsh scripts continue work in cicada?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#will-my-bashzsh-scripts-continue-work-in-cicada)
-- [Windows support?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#windows-support)
+- [Why another shell?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#user-content-why-another-shell)
+- [Compare to bash/zsh/etc?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#user-content-compare-to-other-shells)
+- [Is cicada POSIX-compatible?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#user-content-is-cicada-posix-compatible)
+- [Will my bash/zsh scripts continue work in cicada?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#user-content-will-my-bashzsh-scripts-continue-work-in-cicada)
+- [Windows support?](https://github.com/mitnk/cicada/blob/master/docs/faq.md#user-content-windows-support)
diff --git a/docs/README.md b/docs/README.md
@@ -6,6 +6,8 @@ Cicada is a simple bash-like Unix shell.
 - [Install cicada](https://github.com/mitnk/cicada/blob/master/docs/install.md)
 - [Environment Variables](https://github.com/mitnk/cicada/tree/master/docs/envs.md)
 - [Cicada Builtins](https://github.com/mitnk/cicada/tree/master/docs/builtins.md)
+- [Shell Expansions](https://github.com/mitnk/cicada/tree/master/docs/expansions.md)
+- [Arithmetic in Cicada](https://github.com/mitnk/cicada/tree/master/docs/arithmetic.md)
 - [Completion](https://github.com/mitnk/cicada/tree/master/docs/completion.md)
 - [RC File](https://github.com/mitnk/cicada/tree/master/docs/rc-file.md)
 - [History](https://github.com/mitnk/cicada/tree/master/docs/history.md)

diff --git a/docs/arithmetic.md b/docs/arithmetic.md
@@ -0,0 +1,46 @@
+# Arithmetic in Cicada
+
+Arithmetic is directly available in cicada.
+
+```
+$ 1 + 1
+2
+
+$ 3 * 7
+21
+
+$ 7 / 3
+2
+
+$ 2 ^ 16 - 1
+65535
+```
+
+## Using Parentheses
+
+```
+$ (1 + 1) * 7
+14
+```
+
+## Float Calculation
+
+Whenever there is a `.` in command, the whole calculation will be in float.
+
+```
+$ 7.0 / 3
+2.3333333333333335
+
+$ 7.0 / 3 + 10000
+10002.333333333334
+```
+
+## Single Numbers
+
+A single number will not be treated as arithmetic. It will be treated as
+a regular command.
+
+```
+$ 42
+cicada: 42: command not found
+```
diff --git a/docs/builtins.md b/docs/builtins.md
@@ -1,20 +1,19 @@
 # Cicada Shell Builtins
 
 - Builtin Commands
-    - [alias](#alias)
-    - [bg](#bg)
-    - [cd](#cd)
-    - [cinfo](#cinfo)
-    - [exec](#exec)
-    - [exit](#exit)
-    - [export](#export)
-    - [fg](#fg)
-    - [history](#history)
-    - [jobs](#jobs)
-    - [source](#source)
-    - [unalias](#unalias)
-    - [vox](#vox)
-- [Builtin Shell Expansions](#builtin-shell-expansions)
+    - [alias](#user-content-alias)
+    - [bg](#user-content-bg)
+    - [cd](#user-content-cd)
+    - [cinfo](#user-content-cinfo)
+    - [exec](#user-content-exec)
+    - [exit](#user-content-exit)
+    - [export](#user-content-export)
+    - [fg](#user-content-fg)
+    - [history](#user-content-history)
+    - [jobs](#user-content-jobs)
+    - [source](#user-content-source)
+    - [unalias](#user-content-unalias)
+    - [vox](#user-content-vox)
 
 ## alias
 
@@ -184,83 +183,3 @@ Exit (deactivate) your env:
 (my-project) $ vox exit
 $  # now you're clean
 ```
-
-## Builtin Shell Expansions
-
-### Brace Expansion
-
-```sh
-$ echo sp{el,il,al}l
-spell spill spall
-
-$ cp foo.txt{,.bak}
-# equal to `cp foo.txt foo.txt.bak`
-
-$ echo {1..5}
-1 2 3 4 5
-
-$ echo {1..5..2}
-1 3 5
-```
-
-### Tilde Expansion
-
-```
-$ echo ~/foo
-# equal to echo $HOME/foo
-```
-
-### Parameter Expansion
-
-Currently only works in scripting.
-
-```sh
-$ cat foo.sh
-echo "the args are: $@"
-echo $3 $1 $2
-echo $0
-
-$ cicada foo.sh a b c
-the args are: a b c
-c a b
-foo.sh
-```
-
-### Command Substitution
-
-Command substitution allows the output of a command to replace the command
-itself. Command substitution occurs when a command is enclosed as follows:
-
-```
-$(command)
-```
-
-or
-```
-`command`
-```
-
-### Filename Expansion
-
-```
-$ echo src/*.rs
-src/build.rs src/execute.rs src/history.rs src/jobc.rs ...
-```
-
-### Special Expansions
-
-```sh
-# current session process ID
-$ echo $$
-26653
-
-# last command exit status
-$ echo $?
-0
-
-$ cat /etc/some-config
-
-# last command substitution
-$ sudo !!
-sudo cat /etc/some-config
-```
diff --git a/docs/envs.md b/docs/envs.md
@@ -11,7 +11,7 @@ default: `""` (empty)
 
 ## CICADA_GITBR_PREFIX
 
-In [prompt item](https://github.com/mitnk/cicada/blob/master/docs/prompt.md#available-prompt-items)
+In [prompt item](https://github.com/mitnk/cicada/blob/master/docs/prompt.md#user-content-available-prompt-items)
 `$GITBR`, works as a prefix if defined.
 
 default: `""` (empty)

diff --git a/docs/expansions.md b/docs/expansions.md
@@ -0,0 +1,79 @@
+# Cicada Shell Expansions
+
+## Brace Expansion
+
+```sh
+$ echo sp{el,il,al}l
+spell spill spall
+
+$ cp foo.txt{,.bak}
+# equal to `cp foo.txt foo.txt.bak`
+
+$ echo {1..5}
+1 2 3 4 5
+
+$ echo {1..5..2}
+1 3 5
+```
+
+## Tilde Expansion
+
+```
+$ echo ~/foo
+# equal to echo $HOME/foo
+```
+
+## Parameter Expansion
+
+Currently only works in scripting.
+
+```sh
+$ cat foo.sh
+echo "the args are: $@"
+echo $3 $1 $2
+echo $0
+
+$ cicada foo.sh a b c
+the args are: a b c
+c a b
+foo.sh
+```
+
+## Command Substitution
+
+Command substitution allows the output of a command to replace the command
+itself. Command substitution occurs when a command is enclosed as follows:
+
+```
+$(command)
+```
+
+or
+```
+`command`
+```
+
+## Filename Expansion
+
+```
+$ echo src/*.rs
+src/build.rs src/execute.rs src/history.rs src/jobc.rs ...
+```
+
+## Special Expansions
+
+```sh
+# current session process ID
+$ echo $$
+26653
+
+# last command exit status
+$ echo $?
+0
+
+$ cat /etc/some-config
+
+# last command substitution
+$ sudo !!
+sudo cat /etc/some-config
+```
diff --git a/docs/history.md b/docs/history.md
@@ -32,8 +32,31 @@ are immutable. You cannot edit them. But you could delete them.
 
 ## The history builtin command
 
-See details here: [history built-in command](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#history)
+```
+$ history --help
+
+USAGE:
+    history [FLAGS] [OPTIONS] [PATTERN]
+
+FLAGS:
+    -a, --asc          Search old items first
+    -h, --help         Prints help information
+    -n, --no-id        Do not show ROWID
+    -o, --only-id      Only show ROWID
+    -p, --pwd          For current directory only
+    -s, --session      For current session only
+    -d, --show-date    Show date
+    -V, --version      Prints version information
+
+OPTIONS:
+    -l, --limit <limit>     [default: 20]
+
+ARGS:
+    <PATTERN>    You can use % to match anything [default: ]
+```
+
+See more details here: [history built-in command](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#user-content-history)
 
 ## Others
 
-See more on [Environment Variables](https://github.com/mitnk/cicada/blob/master/docs/envs.md#history_size)
+See more on [Environment Variables](https://github.com/mitnk/cicada/blob/master/docs/envs.md#user-content-history_size)
diff --git a/docs/install.md b/docs/install.md
@@ -23,7 +23,7 @@ $ cicada
 (in-cicada) $ cinfo
 ```
 
-You may want to [set cicada as the default shell](https://github.com/mitnk/cicada/blob/master/docs/install.md#set-cicada-as-your-login-shell).
+You may want to [set cicada as the default shell](https://github.com/mitnk/cicada/blob/master/docs/install.md#user-content-set-cicada-as-your-login-shell).
 
 ### 2) Install via cargo crates
 

diff --git a/docs/prompt.md b/docs/prompt.md
@@ -49,7 +49,7 @@ Note you can also use regular environment variables that not in the list, like `
 
 ## Python Virtual Env in Prompt
 
-See also the [vox](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#vox) builtin.
+See also the [vox](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#user-content-vox) builtin.
 
 When you enter a virtual env, the prompt will prefix by `(pyenv-name)`. e.g.
 `(evn-test)mitnk:mbp: pip$ `.

diff --git a/docs/rc-file.md b/docs/rc-file.md
@@ -1,7 +1,7 @@
 # RC File
 
 When cicada shell is invoked as an interactive
-[login shell](https://github.com/mitnk/cicada/blob/master/docs/install.md#set-cicada-as-your-login-shell),
+[login shell](https://github.com/mitnk/cicada/blob/master/docs/install.md#user-content-set-cicada-as-your-login-shell),
 or with the `--login`/`-l` option, it will reads and executes commands from
 first existing file of below list:
 
@@ -10,7 +10,7 @@ first existing file of below list:
 - `$HOME/.cicadarc`
 
 > Hint: In non-login shell mode, you can apply RC file with
-> [source](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#source):
+> [source](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#user-content-source):
 > `$ source <path-to-rc-file>`.
 
 Here is a sample RC file:

diff --git a/docs/scripting.md b/docs/scripting.md
@@ -9,12 +9,12 @@ to use bash (and call them with `$ bash xxx.sh` in cicada), or dynamic
 scripting languages like Python. Scripting with cicada should only be used
 in simple cases.
 
-- [Introduction](#introduction)
-- [If Statements](#if-statements)
-- [For Statements](#for-statements)
-- [While Statements](#while-statements)
-- [Using Builtins](#using-builtins)
-- [Functions](#functions)
+- [Introduction](#user-content-introduction)
+- [If Statements](#user-content-if-statements)
+- [For Statements](#user-content-for-statements)
+- [While Statements](#user-content-while-statements)
+- [Using Builtins](#user-content-using-builtins)
+- [Functions](#user-content-functions)
 
 ## Introduction
 
@@ -248,7 +248,7 @@ counter = 22
 
 ## The source Builtin
 
-> See also [the source builtin](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#source).
+> See also [the source builtin](https://github.com/mitnk/cicada/blob/master/docs/builtins.md#user-content-source).
 
 Command like `$ cicada foo.sh` would create a new session and run the commands
 of file `foo.sh`. If you want to run them in current shell session, you