Allow composing help message from two parts (#3124)

* Split help message into brief and full help

Demonstrate on ansi command

Brief help is printed when running `help commands` so it doesn't clutter
the table. Full help is printed when normal help message is requested
(e.g., `help ansi`, `ansi --help`, etc.).

* Split long command descriptions

Some are not split, just edited to be shorter.

* Capitalize the usage of all commands

* Make sure every usage ends with dot

* Fix random typo

crates/nu-command/src/commands/ansi/command.rs

@@ -42,9 +42,11 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        r#"Output ANSI codes to change color
+        "Output ANSI codes to change color."
+    }
 
-For escape sequences:
+    fn extra_usage(&self) -> &str {
+        r#"For escape sequences:
 Escape: '\x1b[' is not required for --escape parameter
 Format: #(;#)m
 Example: 1;31m for bold red or 2;37;41m for dimmed white fg with red bg

crates/nu-command/src/commands/append.rs

@@ -25,7 +25,7 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Append a row to the table"
+        "Append a row to the table."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/autoenv.rs

@@ -51,8 +51,12 @@ impl WholeStreamCommand for Autoenv {
         "autoenv"
     }
     fn usage(&self) -> &str {
+        "Manage directory specific environment variables and scripts."
+    }
+
+    fn extra_usage(&self) -> &str {
         // "Mark a .nu-env file in a directory as trusted. Needs to be re-run after each change to the file or its filepath."
-        r#"Manage directory specific environment variables and scripts. Create a file called .nu-env in any directory and run 'autoenv trust' to let nushell read it when entering the directory.
+        r#"Create a file called .nu-env in any directory and run 'autoenv trust' to let nushell read it when entering the directory.
 The file can contain several optional sections:
     env: environment variables to set when visiting the directory. The variables are unset after leaving the directory and any overwritten values are restored.
     scriptvars: environment variables that should be set to the return value of a script. After they have been set, they behave in the same way as variables set in the env section.
@@ -64,7 +68,7 @@ The file can contain several optional sections:
     }
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&Autoenv, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Autoenv, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 

crates/nu-command/src/commands/benchmark.rs

@@ -45,7 +45,7 @@ impl WholeStreamCommand for Benchmark {
     }
 
     fn usage(&self) -> &str {
-        "Runs a block and returns the time it took to execute it"
+        "Runs a block and returns the time it took to execute it."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/build_string.rs

@@ -24,7 +24,7 @@ impl WholeStreamCommand for BuildString {
     }
 
     fn usage(&self) -> &str {
-        "Builds a string from the arguments"
+        "Builds a string from the arguments."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/char_.rs

@@ -29,7 +29,7 @@ impl WholeStreamCommand for Char {
     }
 
     fn usage(&self) -> &str {
-        "Output special characters (eg. 'newline')"
+        "Output special characters (eg. 'newline')."
     }
 
     fn examples(&self) -> Vec<Example> {

crates/nu-command/src/commands/chart.rs

@@ -28,7 +28,7 @@ impl WholeStreamCommand for Chart {
         }
 
         Ok(OutputStream::one(Ok(ReturnSuccess::Value(
-            UntaggedValue::string(get_help(&Chart, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Chart, &args.scope)).into_value(Tag::unknown()),
         ))))
     }
 }

crates/nu-command/src/commands/clear.rs

@@ -17,7 +17,7 @@ impl WholeStreamCommand for Clear {
     }
 
     fn usage(&self) -> &str {
-        "Clears the terminal"
+        "Clears the terminal."
     }
 
     async fn run(&self, _: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/clip.rs

@@ -19,7 +19,7 @@ impl WholeStreamCommand for Clip {
     }
 
     fn usage(&self) -> &str {
-        "Copy the contents of the pipeline to the copy/paste buffer"
+        "Copy the contents of the pipeline to the copy/paste buffer."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/compact.rs

@@ -24,7 +24,7 @@ impl WholeStreamCommand for Compact {
     }
 
     fn usage(&self) -> &str {
-        "Creates a table with non-empty rows"
+        "Creates a table with non-empty rows."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/date/command.rs

@@ -16,12 +16,12 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Apply date function"
+        "Apply date function."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/debug.rs

@@ -21,7 +21,7 @@ impl WholeStreamCommand for Debug {
     }
 
     fn usage(&self) -> &str {
-        "Print the Rust debug representation of the values"
+        "Print the Rust debug representation of the values."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/do_.rs

@@ -29,7 +29,7 @@ impl WholeStreamCommand for Do {
     }
 
     fn usage(&self) -> &str {
-        "Runs a block, optionally ignoring errors"
+        "Runs a block, optionally ignoring errors."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/drop/command.rs

@@ -26,7 +26,7 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Remove the last number of rows. If you want to remove columns, try 'drop column'."
+        "Remove the last number of rows or columns."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/du.rs

@@ -68,7 +68,7 @@ impl WholeStreamCommand for Du {
     }
 
     fn usage(&self) -> &str {
-        "Find disk usage sizes of specified items"
+        "Find disk usage sizes of specified items."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/empty.rs

@@ -32,7 +32,7 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Check for empty values"
+        "Check for empty values."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/enter.rs

@@ -39,14 +39,16 @@ impl WholeStreamCommand for Enter {
     }
 
     fn usage(&self) -> &str {
-        r#"Create a new shell and begin at this path.
-        
-Multiple encodings are supported for reading text files by using
+        "Create a new shell and begin at this path."
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"Multiple encodings are supported for reading text files by using
 the '--encoding <encoding>' parameter. Here is an example of a few:
 big5, euc-jp, euc-kr, gbk, iso-8859-1, utf-16, cp1252, latin5
 
 For a more complete list of encodings please refer to the encoding_rs
-documentation link at https://docs.rs/encoding_rs/0.8.23/encoding_rs/#statics"#
+documentation link at https://docs.rs/encoding_rs/0.8.28/encoding_rs/#statics"#
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/exec.rs

@@ -29,7 +29,7 @@ impl WholeStreamCommand for Exec {
     }
 
     fn usage(&self) -> &str {
-        "Execute command"
+        "Execute command."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/exit.rs

@@ -21,7 +21,7 @@ impl WholeStreamCommand for Exit {
     }
 
     fn usage(&self) -> &str {
-        "Exit the current shell (or all shells)"
+        "Exit the current shell (or all shells)."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/from.rs

@@ -16,12 +16,12 @@ impl WholeStreamCommand for From {
     }
 
     fn usage(&self) -> &str {
-        "Parse content (string or binary) as a table (input format based on subcommand, like csv, ini, json, toml)"
+        "Parse content (string or binary) as a table (input format based on subcommand, like csv, ini, json, toml)."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&From, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&From, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/hash_/command.rs

@@ -24,7 +24,7 @@ impl WholeStreamCommand for Command {
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/headers.rs

@@ -19,7 +19,7 @@ impl WholeStreamCommand for Headers {
     }
 
     fn usage(&self) -> &str {
-        "Use the first row of the table as column names"
+        "Use the first row of the table as column names."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/help.rs

@@ -161,7 +161,7 @@ async fn help(args: CommandArgs) -> Result<OutputStream, ShellError> {
             let command_name = format!("{} {}", rest[0].item, rest[1].item);
             if let Some(command) = scope.get_command(&command_name) {
                 Ok(OutputStream::one(ReturnSuccess::value(
-                    UntaggedValue::string(get_help(command.stream_command(), &scope))
+                    UntaggedValue::string(get_full_help(command.stream_command(), &scope))
                         .into_value(Tag::unknown()),
                 )))
             } else {
@@ -169,7 +169,7 @@ async fn help(args: CommandArgs) -> Result<OutputStream, ShellError> {
             }
         } else if let Some(command) = scope.get_command(&rest[0].item) {
             Ok(OutputStream::one(ReturnSuccess::value(
-                UntaggedValue::string(get_help(command.stream_command(), &scope))
+                UntaggedValue::string(get_full_help(command.stream_command(), &scope))
                     .into_value(Tag::unknown()),
             )))
         } else {

crates/nu-command/src/commands/into_int.rs

@@ -23,7 +23,7 @@ impl WholeStreamCommand for IntoInt {
     }
 
     fn usage(&self) -> &str {
-        "Convert value to integer"
+        "Convert value to integer."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/keep/command.rs

@@ -26,7 +26,7 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Keep the number of rows only"
+        "Keep the number of rows only."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/math/command.rs

@@ -16,12 +16,12 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Use mathematical functions as aggregate functions on a list of numbers or tables"
+        "Use mathematical functions as aggregate functions on a list of numbers or tables."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(Ok(ReturnSuccess::Value(
-            UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()),
         ))))
     }
 }
@@ -154,7 +154,7 @@ mod tests {
                         "col2".to_owned() => table(&[int(5), int(6), int(7), int(8)])
                         ]),
                     Ok(row![
-                        "col1".to_owned() => decimal(BigDecimal::from_str("1.118033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137").expect("Could not convert to decimal from string")), 
+                        "col1".to_owned() => decimal(BigDecimal::from_str("1.118033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137").expect("Could not convert to decimal from string")),
                         "col2".to_owned() => decimal(BigDecimal::from_str("1.118033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137").expect("Could not convert to decimal from string"))
                     ]),
                     Ok(row!["col1".to_owned() => int(10), "col2".to_owned() => int(26)]),

crates/nu-command/src/commands/nth.rs

@@ -31,7 +31,7 @@ impl WholeStreamCommand for Nth {
     }
 
     fn usage(&self) -> &str {
-        "Return or skip only the selected rows"
+        "Return or skip only the selected rows."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/nu/plugin.rs

@@ -101,7 +101,7 @@ impl WholeStreamCommand for SubCommand {
         }
 
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&SubCommand, &scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&SubCommand, &scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/open.rs

@@ -46,14 +46,16 @@ impl WholeStreamCommand for Open {
     }
 
     fn usage(&self) -> &str {
-        r#"Load a file into a cell, convert to table if possible (avoid by appending '--raw').
-        
-Multiple encodings are supported for reading text files by using
+        "Load a file into a cell, convert to table if possible (avoid by appending '--raw')."
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"Multiple encodings are supported for reading text files by using
 the '--encoding <encoding>' parameter. Here is an example of a few:
 big5, euc-jp, euc-kr, gbk, iso-8859-1, utf-16, cp1252, latin5
 
 For a more complete list of encodings please refer to the encoding_rs
-documentation link at https://docs.rs/encoding_rs/0.8.23/encoding_rs/#statics"#
+documentation link at https://docs.rs/encoding_rs/0.8.28/encoding_rs/#statics"#
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/path/command.rs

@@ -16,12 +16,12 @@ impl WholeStreamCommand for Path {
     }
 
     fn usage(&self) -> &str {
-        "Explore and manipulate paths"
+        "Explore and manipulate paths."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&Path, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Path, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/prepend.rs

@@ -25,7 +25,7 @@ impl WholeStreamCommand for Prepend {
     }
 
     fn usage(&self) -> &str {
-        "Prepend the given row to the front of the table"
+        "Prepend the given row to the front of the table."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/random/command.rs

@@ -16,12 +16,12 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Generate random values"
+        "Generate random values."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(Ok(ReturnSuccess::Value(
-            UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()),
         ))))
     }
 }

crates/nu-command/src/commands/range.rs

@@ -27,7 +27,7 @@ impl WholeStreamCommand for Range {
     }
 
     fn usage(&self) -> &str {
-        "Return only the selected rows"
+        "Return only the selected rows."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/reduce.rs

@@ -42,8 +42,11 @@ impl WholeStreamCommand for Reduce {
     }
 
     fn usage(&self) -> &str {
-        "Aggregate a list table to a single value using an accumulator block. Block must be
-        (A, A) -> A unless --fold is selected, in which case it may be A, B -> A."
+        "Aggregate a list table to a single value using an accumulator block."
+    }
+
+    fn extra_usage(&self) -> &str {
+        "Block must be (A, A) -> A unless --fold is selected, in which case it may be A, B -> A."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/rm.rs

@@ -30,7 +30,7 @@ impl WholeStreamCommand for Remove {
     }
 
     fn usage(&self) -> &str {
-        "Remove file(s)"
+        "Remove file(s)."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/roll/command.rs

@@ -24,7 +24,7 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "Rolls the table rows"
+        "Rolls the table rows."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/seq.rs

@@ -45,7 +45,7 @@ impl WholeStreamCommand for Seq {
     }
 
     fn usage(&self) -> &str {
-        "print sequences of numbers"
+        "Print sequences of numbers."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/sleep.rs

@@ -36,7 +36,7 @@ impl WholeStreamCommand for Sleep {
     }
 
     fn usage(&self) -> &str {
-        "Delay for a specified amount of time"
+        "Delay for a specified amount of time."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/split/command.rs

@@ -17,12 +17,12 @@ impl WholeStreamCommand for Command {
     }
 
     fn usage(&self) -> &str {
-        "split contents across desired subcommand (like row, column) via the separator."
+        "Split contents across desired subcommand (like row, column) via the separator."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(Ok(ReturnSuccess::Value(
-            UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()),
         ))))
     }
 }

crates/nu-command/src/commands/str_/command.rs

@@ -24,7 +24,7 @@ impl WholeStreamCommand for Command {
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/to.rs

@@ -22,7 +22,7 @@ impl WholeStreamCommand for To {
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&To, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&To, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/touch.rs

@@ -29,7 +29,7 @@ impl WholeStreamCommand for Touch {
             .rest(SyntaxShape::FilePath, "additional files to create")
     }
     fn usage(&self) -> &str {
-        "creates one or more files"
+        "Creates one or more files."
     }
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         touch(args).await

crates/nu-command/src/commands/uniq.rs

@@ -16,7 +16,7 @@ impl WholeStreamCommand for Uniq {
     }
 
     fn usage(&self) -> &str {
-        "Return the unique rows"
+        "Return the unique rows."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/url_/command.rs

@@ -16,12 +16,12 @@ impl WholeStreamCommand for Url {
     }
 
     fn usage(&self) -> &str {
-        "Apply url function"
+        "Apply url function."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {
         Ok(OutputStream::one(ReturnSuccess::value(
-            UntaggedValue::string(get_help(&Url, &args.scope)).into_value(Tag::unknown()),
+            UntaggedValue::string(get_full_help(&Url, &args.scope)).into_value(Tag::unknown()),
         )))
     }
 }

crates/nu-command/src/commands/version.rs

@@ -21,7 +21,7 @@ impl WholeStreamCommand for Version {
     }
 
     fn usage(&self) -> &str {
-        "Display Nu version"
+        "Display Nu version."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/commands/with_env.rs

@@ -35,7 +35,7 @@ impl WholeStreamCommand for WithEnv {
     }
 
     fn usage(&self) -> &str {
-        "Runs a block with an environment set. Eg) with-env [NAME 'foo'] { echo $nu.env.NAME }"
+        "Runs a block with an environment variable set."
     }
 
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError> {

crates/nu-command/src/prelude.rs

@@ -59,7 +59,7 @@ pub(crate) use nu_engine::Example;
 pub(crate) use nu_engine::Host;
 pub(crate) use nu_engine::RawCommandArgs;
 pub(crate) use nu_engine::ShellManager;
-pub(crate) use nu_engine::{get_help, CommandArgs, Scope, WholeStreamCommand};
+pub(crate) use nu_engine::{get_full_help, CommandArgs, Scope, WholeStreamCommand};
 pub(crate) use nu_parser::ParserScope;
 pub(crate) use nu_protocol::{out, row};
 pub(crate) use nu_source::{AnchorLocation, PrettyDebug, Span, SpannedItem, Tag, TaggedItem, Text};