doc: updated instructions

docs/src/carapace-spec/command/name.md

@@ -11,3 +11,9 @@ It can also contain the one-line [usage](https://rsteube.github.io/carapace/cara
 ```yaml
 name: add [-F file | -D dir]... [-f format] profile
 ```
+
+> Recommended syntax is as [follows](https://pkg.go.dev/github.com/spf13/cobra#Command):
+> - `[ ]` identifies an optional argument. Arguments that are not enclosed in brackets are required.
+> - `...` indicates that you can specify multiple values for the previous argument.
+> - `|`   indicates mutually exclusive information. You can use the argument to the left of the separator or the argument to the right of the separator. You cannot use both arguments in a single use of the command.
+> - `{ }` delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are optional, they are enclosed in brackets ([ ]).

docs/src/carapace-spec/usage.md

@@ -1,30 +1,65 @@
 # Usage
 
+## Bash
 ```sh
-# bash
-source <(carapace-spec example.yaml)
+# ~/.bashrc
+source <(carapace-spec example/pkill.yaml)
+```
+![](./usage/bash.png)
 
-# elvish
-eval (carapace-spec example.yaml|slurp)
+## Elvish
+```sh
+# ~/.config/elvish/rc.elv
+eval (carapace-spec example/pkill.yaml|slurp)
+```
+![](./usage/elvish.png)
 
-# fish
-carapace-spec example.yaml | source
+## Fish
+```sh
+# ~/.config/fish/config.fish
+carapace-spec example/pkill.yaml | source
+```
+![](./usage/fish.png)
 
-# oil
-source <(carapace-spec example.yaml)
+## Nushell
+> update config.nu according to [Multiple Completer](http://www.nushell.sh/cookbook/external_completers.html#multiple-completer))
+```sh
+#~/.config/nushell/config.nu
+carapace-spec example/pkill.yaml
+```
+![](./usage/nushell.png)
 
-# nushell (update config.nu according to output)
-carapace-spec example.yaml
+## Oil
+```sh
+# ~/.config/oil/oshrc
+source <(carapace-spec example/pkill.yaml)
+```
+![](./usage/oil.png)
 
-# powershell
-carapace-spec example.yaml | Out-String | Invoke-Expression
+## Powershell
+```sh
+# ~/.config/powershell/Microsoft.PowerShell_profile.ps1
+carapace-spec example/pkill.yaml | Out-String | Invoke-Expression
+```
+![](./usage/powershell.png)
 
-# tcsh
-eval `carapace-spec example.yaml`
+# Tcsh
+```sh
+## ~/.tcshrc
+eval `carapace-spec example/pkill.yaml`
+```
+![](./usage/tcsh.png)
 
-# xonsh
-exec($(carapace-spec example.yaml))
+## Xonsh
+```sh
+# ~/.config/xonsh/rc.xsh
+exec($(carapace-spec example/pkill.yaml))
+```
+![](./usage/xonsh.png)
 
-# zsh
-source <(carapace-spec example.yaml)
+## Zsh
+```sh
+# ~/.zshrc
+source <(carapace-spec example/pkill.yaml)
 ```
+![](./usage/zsh.png)