docs: Improvements in docs for custom modules (#1615)

* docs: Clarify that commands will be passed in on stdin

* docs: Clearer instruction how to include individual custom modules

* docs: Include link to #1252 in docs for custom modules

That issue is used to share custom modules.

* docs: Remove reference to prompt_order

Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>

Co-authored-by: Thomas O'Donnell <andytom@users.noreply.github.com>

docs/config/README.md

@@ -2276,9 +2276,16 @@ Multiple custom modules can be defined by using a `.`.
 
 ::: tip
 
-The order in which custom modules are shown can be individually set
+The order in which custom modules are shown can be individually set by including 
-by setting `custom.foo` in `prompt_order`. By default, the `custom` module
+`${custom.foo}` in the top level `format` (as it includes a dot, you need to use `${...}`). 
-will simply show all custom modules in the order they were defined.
+By default, the `custom` module will simply show all custom modules in the order they were defined.
+
+:::
+
+::: tip
+
+[Issue #1252](https://github.com/starship/starship/discussions/1252) contains examples of custom modules.
+If you have an interesting example not covered there, feel free to share it there!
 
 :::
 
@@ -2286,7 +2293,7 @@ will simply show all custom modules in the order they were defined.
 
 | Option        | Default                       | Description                                                                                                                |
 | ------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `command`     |                               | The command whose output should be printed.                                                                                |
+| `command`     |                               | The command whose output should be printed. The command will be passed on stdin to the shell.                              |
 | `when`        |                               | A shell command used as a condition to show the module. The module will be shown if the command returns a `0` status code. |
 | `shell`       |                               | [See below](#custom-command-shell)                                                                                         |
 | `description` | `"<custom module>"`           | The description of the module that is shown when running `starship explain`.                                               |
@@ -2317,6 +2324,8 @@ will simply show all custom modules in the order they were defined.
 
 If unset, it will fallback to STARSHIP_SHELL and then to "sh" on Linux, and "cmd /C" on Windows.
 
+The `command` will be passed in on stdin.
+
 If `shell` is not given or only contains one element and Starship detects PowerShell will be used,
 the following arguments will automatically be added: `-NoProfile -Command -`.
 This behavior can be avoided by explicitly passing arguments to the shell, e.g.

docs/faq/README.md

@@ -10,11 +10,11 @@
   - **Configuration**: [matchai's Dotfiles](https://github.com/matchai/dotfiles/blob/b6c6a701d0af8d145a8370288c00bb9f0648b5c2/.config/fish/config.fish)
   - **Prompt**: [Starship](https://starship.rs/)
 
-## Do `prompt_order` and `<module>.disabled` do the same thing?
+## Do top level `format` and `<module>.disabled` do the same thing?
 
 Yes, they can both be used to disable modules in the prompt. If all you plan to do is disable modules, `<module>.disabled` is the preferred way to do so for these reasons:
 
-- Disabling modules is more explicit than omitting them from the prompt_order
+- Disabling modules is more explicit than omitting them from the top level `format`
 - Newly created modules will be added to the prompt as Starship is updated
 
 ## The docs say Starship is cross-shell, but it doesn't support X shell. Why?

src/print.rs

@@ -249,19 +249,19 @@ fn handle_module<'a>(
             Some(false) => modules.push(modules::custom::module(&module[7..], &context)),
             None => match context.config.get_custom_modules() {
                 Some(modules) => log::debug!(
-                    "prompt_order contains custom module \"{}\", but no configuration was provided. Configuration for the following modules were provided: {:?}",
+                    "top level format contains custom module \"{}\", but no configuration was provided. Configuration for the following modules were provided: {:?}",
                     module,
                     DebugCustomModules(modules),
                     ),
                 None => log::debug!(
-                    "prompt_order contains custom module \"{}\", but no configuration was provided.",
+                    "top level format contains custom module \"{}\", but no configuration was provided.",
                     module,
                     ),
             },
         }
     } else {
         log::debug!(
-            "Expected prompt_order to contain value from {:?}. Instead received {}",
+            "Expected top level format to contain value from {:?}. Instead received {}",
             ALL_MODULES,
             module,
         );