From c0ad659985d7d45c1fe0589ed84461ba38515de9 Mon Sep 17 00:00:00 2001
From: Douglas <32344964+NotTheDr01ds@users.noreply.github.com>
Date: Tue, 17 Dec 2024 15:18:23 -0500
Subject: [PATCH] Doc file fixes (#14608)

# Description

With great thanks to @fdncred and especially @PerchunPak (see #14601)
for finding and fixing a number of issues that I pulled in here due to
the filename changes and upcoming freeze.

This PR primarily fixes a poor wording choice in the new filenames and
`config` command options. The fact that these were called
`sample_config.nu` (etc.) and accessed via `config --sample` created a
great deal of confusion. These were never intended to be used as-is as
config files, but rather as in-shell documentation.

As such, I've renamed them:

* `sample_config.nu` becomes `doc_config.nu`
* `sample_env.nu` becomes `doc_env.nu`
* `config nu --sample` becomes `config nu --doc`
* `config env --sample` because `config env --doc`

Also the following:

* Updates `doc_config.nu` with a few additional comment-fixes on top of
@PerchunPak's changes.
* Adds version numbers to all files - Will need to update the version
script to add some files after this PR.
* Additional doc on plugin and plugin_gc configuration which I had
failed to previously completely update from the older wording
* Updated the comments in the `scaffold_*.nu` files to point people to
`help config`/`help nu` so that, if things change in the future, it will
become more difficult for the comments to be outdated.
*

# User-Facing Changes

Mostly doc.

`config nu` and `config env` changes update new behavior previously
added in 0.100.1

# Tests + Formatting

- :green_circle: `toolkit fmt`
- :green_circle: `toolkit clippy`
- :green_circle: `toolkit test`
- :green_circle: `toolkit test stdlib`

# After Submitting

* Update configuration chapter of doc
* Update the blog entry on migrating config
* Update `bump-version.nu`
---
 .../nu-command/src/env/config/config_env.rs   | 22 +++++-----
 crates/nu-command/src/env/config/config_nu.rs | 22 +++++-----
 crates/nu-utils/src/default_files/README.md   | 18 ++++----
 .../{sample_config.nu => doc_config.nu}       | 41 ++++++++++---------
 .../{sample_env.nu => doc_env.nu}             |  6 ++-
 .../src/default_files/scaffold_config.nu      |  6 +--
 .../src/default_files/scaffold_env.nu         |  6 +--
 crates/nu-utils/src/lib.rs                    |  4 +-
 crates/nu-utils/src/utils.rs                  |  8 ++--
 9 files changed, 65 insertions(+), 68 deletions(-)
 rename crates/nu-utils/src/default_files/{sample_config.nu => doc_config.nu} (97%)
 rename crates/nu-utils/src/default_files/{sample_env.nu => doc_env.nu} (74%)

diff --git a/crates/nu-command/src/env/config/config_env.rs b/crates/nu-command/src/env/config/config_env.rs
index 5fdc39a903..f078b365d2 100644
--- a/crates/nu-command/src/env/config/config_env.rs
+++ b/crates/nu-command/src/env/config/config_env.rs
@@ -18,8 +18,8 @@ impl Command for ConfigEnv {
                 Some('d'),
             )
             .switch(
-                "sample",
-                "Print a commented, sample `env.nu` file instead.",
+                "doc",
+                "Print a commented `env.nu` with documentation instead.",
                 Some('s'),
             )
         // TODO: Signature narrower than what run actually supports theoretically
@@ -37,8 +37,8 @@ impl Command for ConfigEnv {
                 result: None,
             },
             Example {
-                description: "pretty-print a commented, sample `env.nu` that explains common settings",
-                example: "config env --sample | nu-highlight,",
+                description: "pretty-print a commented `env.nu` that explains common settings",
+                example: "config env --doc | nu-highlight,",
                 result: None,
             },
             Example {
@@ -57,13 +57,13 @@ impl Command for ConfigEnv {
         _input: PipelineData,
     ) -> Result<PipelineData, ShellError> {
         let default_flag = call.has_flag(engine_state, stack, "default")?;
-        let sample_flag = call.has_flag(engine_state, stack, "sample")?;
-        if default_flag && sample_flag {
+        let doc_flag = call.has_flag(engine_state, stack, "doc")?;
+        if default_flag && doc_flag {
             return Err(ShellError::IncompatibleParameters {
                 left_message: "can't use `--default` at the same time".into(),
                 left_span: call.get_flag_span(stack, "default").expect("has flag"),
-                right_message: "because of `--sample`".into(),
-                right_span: call.get_flag_span(stack, "sample").expect("has flag"),
+                right_message: "because of `--doc`".into(),
+                right_span: call.get_flag_span(stack, "doc").expect("has flag"),
             });
         }
         // `--default` flag handling
@@ -72,10 +72,10 @@ impl Command for ConfigEnv {
             return Ok(Value::string(nu_utils::get_default_env(), head).into_pipeline_data());
         }
 
-        // `--sample` flag handling
-        if sample_flag {
+        // `--doc` flag handling
+        if doc_flag {
             let head = call.head;
-            return Ok(Value::string(nu_utils::get_sample_env(), head).into_pipeline_data());
+            return Ok(Value::string(nu_utils::get_doc_env(), head).into_pipeline_data());
         }
 
         super::config_::start_editor("env-path", engine_state, stack, call)
diff --git a/crates/nu-command/src/env/config/config_nu.rs b/crates/nu-command/src/env/config/config_nu.rs
index 75d971f36e..66e24e2a94 100644
--- a/crates/nu-command/src/env/config/config_nu.rs
+++ b/crates/nu-command/src/env/config/config_nu.rs
@@ -18,8 +18,8 @@ impl Command for ConfigNu {
                 Some('d'),
             )
             .switch(
-                "sample",
-                "Print a commented, sample `config.nu` file instead.",
+                "doc",
+                "Print a commented `config.nu` with documentation instead.",
                 Some('s'),
             )
         // TODO: Signature narrower than what run actually supports theoretically
@@ -37,8 +37,8 @@ impl Command for ConfigNu {
                 result: None,
             },
             Example {
-                description: "pretty-print a commented, sample `config.nu` that explains common settings",
-                example: "config nu --sample | nu-highlight",
+                description: "pretty-print a commented `config.nu` that explains common settings",
+                example: "config nu --doc | nu-highlight",
                 result: None,
             },
             Example {
@@ -58,13 +58,13 @@ impl Command for ConfigNu {
         _input: PipelineData,
     ) -> Result<PipelineData, ShellError> {
         let default_flag = call.has_flag(engine_state, stack, "default")?;
-        let sample_flag = call.has_flag(engine_state, stack, "sample")?;
-        if default_flag && sample_flag {
+        let doc_flag = call.has_flag(engine_state, stack, "doc")?;
+        if default_flag && doc_flag {
             return Err(ShellError::IncompatibleParameters {
                 left_message: "can't use `--default` at the same time".into(),
                 left_span: call.get_flag_span(stack, "default").expect("has flag"),
-                right_message: "because of `--sample`".into(),
-                right_span: call.get_flag_span(stack, "sample").expect("has flag"),
+                right_message: "because of `--doc`".into(),
+                right_span: call.get_flag_span(stack, "doc").expect("has flag"),
             });
         }
 
@@ -74,10 +74,10 @@ impl Command for ConfigNu {
             return Ok(Value::string(nu_utils::get_default_config(), head).into_pipeline_data());
         }
 
-        // `--sample` flag handling
-        if sample_flag {
+        // `--doc` flag handling
+        if doc_flag {
             let head = call.head;
-            return Ok(Value::string(nu_utils::get_sample_config(), head).into_pipeline_data());
+            return Ok(Value::string(nu_utils::get_doc_config(), head).into_pipeline_data());
         }
 
         super::config_::start_editor("config-path", engine_state, stack, call)
diff --git a/crates/nu-utils/src/default_files/README.md b/crates/nu-utils/src/default_files/README.md
index 68a36b865d..926870d20a 100644
--- a/crates/nu-utils/src/default_files/README.md
+++ b/crates/nu-utils/src/default_files/README.md
@@ -9,7 +9,7 @@
   * During a startup where the user specifies an alternative `env.nu` via `nu --env-config <path>`
   * During a `nu -c <commandstring>` or `nu <script>` startup so that `ENV_CONVERSIONS` is properly handled for Windows.
 * Is *not* loaded when running with an explicit `no --no-config-file (-n)`.
-* Is not commented - Comments are in `sample_env.nu`.
+* Is not commented - Comments are in `doc_env.nu`.
 * Should be optimized for fastest load times.
 * Can be introspected via `config env --default | nu-highlight`
 
@@ -27,7 +27,7 @@ Counterpart to `default_env.nu`.
   * `nu -n/--no-config`
   * `nu -c "ls"`
   * `nu <script.nu>`
-* Is not commented - Comments are in `sample_config.nu`.
+* Is not commented - Comments are in `doc_config.nu`.
 * Should be optimized for fastest load times. Whenever possible, values should be set via nu-protocol::config
   * Exception: `color_config` values are currently set in this file so that user's can introspect the values
   * TODO: Implement defaults for `color_config` in nu-protocol::config and remove from `default_config.nu`
@@ -37,24 +37,24 @@ Counterpart to `default_env.nu`.
   $env.config = {}
   ```
 
-## `sample_env.nu`
+## `doc_env.nu`
 
 * A commented file documenting the most common environment variables that a user might configure in `env.nu`
-* For convenient in-shell access - Can be pretty-printed via `config env --sample | nu-highlight`
+* For convenient in-shell access - Can be pretty-printed via `config env --doc | nu-highlight`
 * Since this file is for documentation only, include actual Nushell code without comments so that it can be pretty-printed
 * No optimization necessary - Not intended for use other than documentation.
-* Consider replacing `config env --sample` with `help env.nu` at some point.
+* Consider replacing `config env --doc` with `help env.nu` at some point.
 * Uses a mix of default values (explained) as well as other examples that users might want in their own `env.nu`
 
-## `sample_config.nu`
+## `doc_config.nu`
 
-Counterpart to `sample_env.nu`.
+Counterpart to `doc_env.nu`.
 
 * A commented file documenting the most common environment variables that a user might configure in `config.nu`
-* For convenient in-shell access - Can be pretty-printed via `config nu --sample | nu-highlight`
+* For convenient in-shell access - Can be pretty-printed via `config nu --doc | nu-highlight`
 * Since this file is for documentation only, include actual Nushell code without comments so that it can be pretty-printed
 * No optimization necessary - Not intended for use other than documentation.
-* Consider replacing `config nu --sample` with `help config.nu` at some point.
+* Consider replacing `config nu --doc` with `help config.nu` at some point.
 * Uses a mix of default values (explained) as well as other examples that users might want in their own `config.nu`
 
 ## `scaffold_env.nu`
diff --git a/crates/nu-utils/src/default_files/sample_config.nu b/crates/nu-utils/src/default_files/doc_config.nu
similarity index 97%
rename from crates/nu-utils/src/default_files/sample_config.nu
rename to crates/nu-utils/src/default_files/doc_config.nu
index 1a91b59f5e..3f4e7e1008 100644
--- a/crates/nu-utils/src/default_files/sample_config.nu
+++ b/crates/nu-utils/src/default_files/doc_config.nu
@@ -1,4 +1,4 @@
-# Nushell Sample Config File
+# Nushell Config File Documentation
 #
 # Warning: This file is intended for documentation purposes only and
 # is not intended to be used as an actual configuration file as-is.
@@ -18,7 +18,7 @@
 # https://nushell.sh/book/configuration
 #
 # You can pretty-print and page this file using:
-# config nu --sample | nu-highlight | less -R
+# config nu --doc | nu-highlight | less -R
 
 # $env.config
 # -----------
@@ -335,7 +335,7 @@ $env.config.table.header_on_separator = false
 # If set to an int, all tables will be abbreviated to only show the first <n> and last <n> rows
 # If set to `null`, all table rows will be displayed
 # Can be overridden by passing a table to `| table --abbreviated/-a`
-$env.config.table.abbreviated_row_count
+$env.config.table.abbreviated_row_count = null
 
 # footer_inheritance (bool): Footer behavior in nested tables
 # true: If a nested table is long enough on its own to display a footer (per `footer_mode` above),
@@ -411,7 +411,7 @@ $env.config.hooks.pre_prompt = []
 $env.config.hooks.pre_execution = []
 # When a specified environment variable changes
 $env.config.hooks.env_change = {
-    # run if the PWD environment is different since the last repl input
+    # Example: Run if the PWD environment is different since the last REPL input
     PWD: [{|before, after| null }]
 }
 # Before Nushell output is displayed in the terminal
@@ -419,6 +419,10 @@ $env.config.hooks.display_output = "if (term size).columns >= 100 { table -e } e
 # When a command is not found
 $env.config.hooks.command_not_found = []
 
+# The env_change hook accepts a record with environment variable names as keys, and a list
+# of hooks to run when that variable changes
+$env.config.hooks.env_change = {}
+
 # -----------
 # Keybindings
 # -----------
@@ -472,7 +476,9 @@ $env.config.menus ++= [
         type: {
             layout: description
             columns: 4
-            col_width: 20 # Optional value. If missing all the screen width is used to calculate column width
+            # col_width is an optional value. If missing, the entire screen width is used to
+            # calculate the column width
+            col_width: 20
             col_padding: 2
             selection_rows: 4
             description_rows: 10
@@ -485,29 +491,26 @@ $env.config.menus ++= [
     }
 ]
 
-
 # ---------------
 # Plugin behavior
 # ---------------
-# Per-plugin configuration. See https://www.nushell.sh/contributor-book/plugins.html#configuration.
-$env.config.plugins
+# Per-plugin configuration. See https://www.nushell.sh/contributor-book/plugins.html#plugin-configuration
+$env.config.plugins = {}
 
-# Configuration for plugin garbage collection
-$env.config.plugin_gc
-$env.config.plugin_gc.default
-# true to enable stopping of inactive plugins
-$env.config.plugin_gc.default.enabled
-# How long to wait after a plugin is inactive before stopping it
-$env.config.plugin_gc.default.stop_after
+# Plugin garbage collection configuration
+# $env.config.plugin_gc.*
+
+# enabled (bool): true/false to enable/disable stopping inactive plugins
+$env.config.plugin_gc.default.enabled = true
+# stop_after (duration): How long to wait after a plugin is inactive before stopping it
+$env.config.plugin_gc.default.stop_after = 10sec
+# plugins (record): Alternate garbage collection configuration per-plugin.
 $env.config.plugin_gc.plugins = {
-  # Alternate configuration for specific plugins, by name, for example:
-  #
   # gstat: {
-  #     enabled: false
+  #   enabled: false
   # }
 }
 
-
 # -------------------------------------
 # Themes/Colors and Syntax Highlighting
 # -------------------------------------
diff --git a/crates/nu-utils/src/default_files/sample_env.nu b/crates/nu-utils/src/default_files/doc_env.nu
similarity index 74%
rename from crates/nu-utils/src/default_files/sample_env.nu
rename to crates/nu-utils/src/default_files/doc_env.nu
index a69363cdf7..4b1bb95a4e 100644
--- a/crates/nu-utils/src/default_files/sample_env.nu
+++ b/crates/nu-utils/src/default_files/doc_env.nu
@@ -1,4 +1,6 @@
-# Sample Nushell Environment Config File
+# Nushell Environment Config File Documentation
+#
+# version = "0.100.1"
 #
 # version = "0.100.1"
 #
@@ -8,4 +10,4 @@
 
 # To pretty-print the in-shell documentation for Nushell's various configuration
 # settings, you can run:
-config nu --sample | nu-highlight | less -R
+config nu --doc | nu-highlight | less -R
diff --git a/crates/nu-utils/src/default_files/scaffold_config.nu b/crates/nu-utils/src/default_files/scaffold_config.nu
index fa6d834c73..1ee112e3aa 100644
--- a/crates/nu-utils/src/default_files/scaffold_config.nu
+++ b/crates/nu-utils/src/default_files/scaffold_config.nu
@@ -12,11 +12,7 @@
 # You can open this file in your default editor using:
 # config nu
 #
-# To pretty-print a sample config.nu with documentation, run:
-# config nu --sample | nu-highlight | less -R
-#
-# To pretty-print the default configuration values, run:
-# config nu --default | nu-highlight | less -R
+# See `help config nu` for more options
 #
 # You can remove these comments if you want or leave
 # them for future reference.
diff --git a/crates/nu-utils/src/default_files/scaffold_env.nu b/crates/nu-utils/src/default_files/scaffold_env.nu
index d7a2e00627..3f1c4600d6 100644
--- a/crates/nu-utils/src/default_files/scaffold_env.nu
+++ b/crates/nu-utils/src/default_files/scaffold_env.nu
@@ -12,11 +12,7 @@
 #
 # See https://www.nushell.sh/book/configuration.html
 #
-# To pretty-print a sample of the configuration settings, run:
-# config nu --sample | nu-highlight | less -R
-#
-# To pretty-print the default env.nu, run:
-# config env --default | nu-highlight | less -R
+# Also see `help config env` for more options.
 #
 # You can remove these comments if you want or leave
 # them for future reference.
diff --git a/crates/nu-utils/src/lib.rs b/crates/nu-utils/src/lib.rs
index a22c2e4537..c43bda9a0e 100644
--- a/crates/nu-utils/src/lib.rs
+++ b/crates/nu-utils/src/lib.rs
@@ -10,8 +10,8 @@ pub mod utils;
 
 pub use locale::get_system_locale;
 pub use utils::{
-    enable_vt_processing, get_default_config, get_default_env, get_ls_colors, get_sample_config,
-    get_sample_env, get_scaffold_config, get_scaffold_env, stderr_write_all_and_flush,
+    enable_vt_processing, get_default_config, get_default_env, get_doc_config, get_doc_env,
+    get_ls_colors, get_scaffold_config, get_scaffold_env, stderr_write_all_and_flush,
     stdout_write_all_and_flush, terminal_size,
 };
 
diff --git a/crates/nu-utils/src/utils.rs b/crates/nu-utils/src/utils.rs
index 74e5277ec4..87d667bdd1 100644
--- a/crates/nu-utils/src/utils.rs
+++ b/crates/nu-utils/src/utils.rs
@@ -94,8 +94,8 @@ pub fn get_scaffold_env() -> &'static str {
     include_str!("default_files/scaffold_env.nu")
 }
 
-pub fn get_sample_env() -> &'static str {
-    include_str!("default_files/sample_env.nu")
+pub fn get_doc_env() -> &'static str {
+    include_str!("default_files/doc_env.nu")
 }
 
 pub fn get_default_config() -> &'static str {
@@ -106,8 +106,8 @@ pub fn get_scaffold_config() -> &'static str {
     include_str!("default_files/scaffold_config.nu")
 }
 
-pub fn get_sample_config() -> &'static str {
-    include_str!("default_files/sample_config.nu")
+pub fn get_doc_config() -> &'static str {
+    include_str!("default_files/doc_config.nu")
 }
 
 pub fn get_ls_colors(lscolors_env_string: Option<String>) -> LsColors {