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-engine/src/documentation.rs

@@ -11,6 +11,7 @@ const COMMANDS_DOCS_DIR: &str = "docs/commands";
 pub struct DocumentationConfig {
     no_subcommands: bool,
     no_color: bool,
+    brief: bool,
 }
 
 impl Default for DocumentationConfig {
@@ -18,6 +19,7 @@ impl Default for DocumentationConfig {
         DocumentationConfig {
             no_subcommands: false,
             no_color: false,
+            brief: false,
         }
     }
 }
@@ -49,6 +51,7 @@ fn generate_doc(name: &str, scope: &Scope) -> IndexMap<String, Value> {
             &DocumentationConfig {
                 no_subcommands: true,
                 no_color: true,
+                brief: false,
             },
         ))
         .into_untagged_value(),
@@ -70,7 +73,7 @@ pub fn generate_docs(scope: &Scope) -> Value {
             if cmap.contains_key(*parent_name) {
                 let sub_names = cmap
                     .get_mut(*parent_name)
-                    .expect("Expected a entry for parent");
+                    .expect("Expected an entry for parent");
                 sub_names.push(name.to_owned());
             }
         } else {
@@ -135,6 +138,12 @@ pub fn get_documentation(
         long_desc.push_str("\n\n");
     }
 
+    let extra_usage = if config.brief { "" } else { &cmd.extra_usage() };
+    if !extra_usage.is_empty() {
+        long_desc.push_str(extra_usage);
+        long_desc.push_str("\n\n");
+    }
+
     let mut subcommands = vec![];
     if !config.no_subcommands {
         for name in scope.get_command_names() {
@@ -296,6 +305,18 @@ fn get_flags_section(signature: &Signature) -> String {
     long_desc
 }
 
-pub fn get_help(cmd: &dyn WholeStreamCommand, scope: &Scope) -> String {
+pub fn get_brief_help(cmd: &dyn WholeStreamCommand, scope: &Scope) -> String {
+    get_documentation(
+        cmd,
+        scope,
+        &DocumentationConfig {
+            no_subcommands: false,
+            no_color: false,
+            brief: true,
+        },
+    )
+}
+
+pub fn get_full_help(cmd: &dyn WholeStreamCommand, scope: &Scope) -> String {
     get_documentation(cmd, scope, &DocumentationConfig::default())
 }

crates/nu-engine/src/lib.rs

@@ -21,7 +21,7 @@ pub use crate::call_info::UnevaluatedCallInfo;
 pub use crate::command_args::{
     CommandArgs, EvaluatedCommandArgs, EvaluatedWholeStreamCommandArgs, RawCommandArgs,
 };
-pub use crate::documentation::{generate_docs, get_documentation, get_help};
+pub use crate::documentation::{generate_docs, get_brief_help, get_documentation, get_full_help};
 pub use crate::env::environment::Env;
 pub use crate::env::host::FakeHost;
 pub use crate::env::host::Host;

crates/nu-engine/src/whole_stream_command.rs

@@ -1,5 +1,5 @@
 use crate::command_args::CommandArgs;
-use crate::documentation::get_help;
+use crate::documentation::get_full_help;
 use crate::evaluate::block::run_block;
 use crate::evaluation_context::EvaluationContext;
 use crate::example::Example;
@@ -22,6 +22,10 @@ pub trait WholeStreamCommand: Send + Sync {
 
     fn usage(&self) -> &str;
 
+    fn extra_usage(&self) -> &str {
+        ""
+    }
+
     async fn run(&self, args: CommandArgs) -> Result<OutputStream, ShellError>;
 
     fn is_binary(&self) -> bool {
@@ -210,7 +214,7 @@ impl Command {
         if args.call_info.switch_present("help") {
             let cl = self.0.clone();
             Ok(OutputStream::one(Ok(ReturnSuccess::Value(
-                UntaggedValue::string(get_help(&*cl, &args.scope)).into_value(Tag::unknown()),
+                UntaggedValue::string(get_full_help(&*cl, &args.scope)).into_value(Tag::unknown()),
             ))))
         } else {
             self.0.run(args).await