Merge pull request #264 from rsteube/update-doc

doc: updated instructions
carapace-sh · Feb 19, 2024 · fd760ae · fd760ae
2 parents 0605972 + 1cc1c5c
commit fd760ae
Show file tree

Hide file tree

Showing 11 changed files with 59 additions and 18 deletions.
diff --git a/docs/src/carapace-spec/command/name.md b/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 ([ ]).
diff --git a/docs/src/carapace-spec/usage.md b/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)
diff --git a/docs/src/carapace-spec/usage/bash.png b/docs/src/carapace-spec/usage/bash.png
diff --git a/docs/src/carapace-spec/usage/elvish.png b/docs/src/carapace-spec/usage/elvish.png
diff --git a/docs/src/carapace-spec/usage/fish.png b/docs/src/carapace-spec/usage/fish.png
diff --git a/docs/src/carapace-spec/usage/nushell.png b/docs/src/carapace-spec/usage/nushell.png
diff --git a/docs/src/carapace-spec/usage/oil.png b/docs/src/carapace-spec/usage/oil.png
diff --git a/docs/src/carapace-spec/usage/powershell.png b/docs/src/carapace-spec/usage/powershell.png
diff --git a/docs/src/carapace-spec/usage/tcsh.png b/docs/src/carapace-spec/usage/tcsh.png
diff --git a/docs/src/carapace-spec/usage/xonsh.png b/docs/src/carapace-spec/usage/xonsh.png
diff --git a/docs/src/carapace-spec/usage/zsh.png b/docs/src/carapace-spec/usage/zsh.png