doc: added choices

cmd/carapace/cmd/choice.go

@@ -63,7 +63,7 @@ func init() {
 				for _, choice := range list {
 					vals = append(vals, choice.Name, choice.Format())
 				}
-				return carapace.ActionValuesDescribed(vals...)
+				return carapace.ActionValuesDescribed(vals...).FilterArgs()
 			}
 
 			return carapace.ActionMultiPartsN("@", 2, func(c carapace.Context) carapace.Action {

docs/src/SUMMARY.md

@@ -8,6 +8,7 @@
     - [UserConfigDir](./setup/userConfigDir.md)
   - [Groups](./groups.md)
   - [Variants](./variants.md)
+  - [Choices](./choices.md)
   - [Completers](./completers.md)
   - [Style](./style.md)
   - [Bridges](./bridges.md)

docs/src/bridges.md

@@ -1,3 +1,5 @@
+> deprecated - will be replaced by [choices](./choices.md)
+
 # Bridges
 
 With `${UserConfigDir}/carapace/bridges.yaml` generic bridges can be configured for commands.

docs/src/choices.md

@@ -0,0 +1,24 @@
+> unreleased
+
+# Choices
+
+The **default priority** of completers can be **overridden** with `carapace --choice {name}[/{variant}][@{group}]`.
+
+![](./choices/choices.cast)
+
+> Choices are stored as simple text files in your [config directory](http://localhost:3000/setup/userConfigDir.html).
+> ```sh
+> carapace
+> └── choices
+>     ├── sed  # sed@bsd
+>     └── tldr # tldr/tldr-python-client
+> ```
+
+## Bridges
+
+[Bridges](https://github.com/carapace-sh/carapace-bridge) are a special form of choices as they can be added as **additional completers** otherwise unknown.
+
+![](./choices/bridges.cast)
+
+> With [CARAPACE_BRIDGES](http://localhost:3000/setup/environment.html#carapace_bridges) completers from `zsh`, `fish`, `bash`, and `inshellisense` can largely determined and act as implicit fallback.
+> But frameworks like [cobra](http://localhost:3000/setup/environment.html#carapace_bridges) need to be set explicitly.

docs/src/release_notes/v1.x.md

@@ -30,7 +30,7 @@ commands:
 
 ## Groups
 
-Organized completers into [**groups**](../groups.md).
+Organized completers into [groups](../groups.md).
 
 - `android` termux completers
 - `bridge` bridged completers
@@ -51,6 +51,14 @@ Organized completers into [**groups**](../groups.md).
 
 ![](./v1.x/variants.cast)
 
+## Choices
+
+The default priority of completers can be overridden with [choices](../choices.md).
+
+![](./v1.x/choices.cast)
+
+> This replaces `bridges.yaml` which now has no effect and can be removed.
+
 
 [aws-cli]:https://github.com/aws/aws-cli
 [carapace-aws]:https://github.com/carapace-sh/carapace-aws