feat(spec): output KDL multiline strings for descriptions

cli/usage.usage.kdl

@@ -7,15 +7,26 @@ usage "Usage: usage-cli [OPTIONS] [COMPLETIONS] <COMMAND>"
 flag --usage-spec help="Outputs a `usage.kdl` spec for this CLI itself"
 arg "[COMPLETIONS]" help="Outputs completions for the specified shell for completing the `usage` CLI itself" required=#false
 cmd bash help="Execute a shell script using bash" {
-    long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
+    long_help #"""
+Execute a shell script with the specified shell
+
+Typically, this will be called by a script's shebang.
+
+If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
+to properly escape and quote values with spaces in them.
+"""#
     flag -h help="Show help"
     flag --help help="Show help"
     arg <SCRIPT>
     arg "[ARGS]…" help="Arguments to pass to script" required=#false var=#true
 }
 cmd complete-word help="Generate shell completion candidates for a partial command line" {
     alias cw
-    long_help "Generate shell completion candidates for a partial command line\n\nThis is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments."
+    long_help #"""
+Generate shell completion candidates for a partial command line
+
+This is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments.
+"""#
     flag "-f --file" help="Usage spec file or script with usage shebang, use \"-\" to read from stdin" {
         arg <FILE>
     }
@@ -41,7 +52,14 @@ cmd exec help="Execute a script, parsing args and exposing them as environment v
     arg "[ARGS]…" help="arguments to pass to script" required=#false var=#true
 }
 cmd fish help="Execute a shell script using fish" {
-    long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
+    long_help #"""
+Execute a shell script with the specified shell
+
+Typically, this will be called by a script's shebang.
+
+If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
+to properly escape and quote values with spaces in them.
+"""#
     flag -h help="Show help"
     flag --help help="Show help"
     arg <SCRIPT>
@@ -59,10 +77,18 @@ cmd generate subcommand_required=#true help="Generate completions, documentation
             arg <CACHE_KEY>
         }
         flag --include-bash-completion-lib help="Include https://github.com/scop/bash-completion" {
-            long_help "Include https://github.com/scop/bash-completion\n\nThis is required for usage completions to work in bash, but the user may already provide it"
+            long_help #"""
+Include https://github.com/scop/bash-completion
+
+This is required for usage completions to work in bash, but the user may already provide it
+"""#
         }
         flag --usage-bin help="Override the bin used for calling back to usage-cli" default=usage {
-            long_help "Override the bin used for calling back to usage-cli\n\nYou may need to set this if you have a different bin named \"usage\""
+            long_help #"""
+Override the bin used for calling back to usage-cli
+
+You may need to set this if you have a different bin named "usage"
+"""#
             arg <USAGE_BIN>
         }
         flag --usage-cmd help="A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"" {
@@ -76,9 +102,17 @@ cmd generate subcommand_required=#true help="Generate completions, documentation
     cmd completion-init help="Generate a shell init script that auto-completes any usage shebang script on $PATH" {
         alias ci
         alias init completions-init hide=#true
-        long_help "Generate a shell init script that auto-completes any usage shebang script on $PATH\n\nSource the output once from your shell rc (e.g. ~/.bashrc) to enable tab-completion for any executable whose first line is a `usage` shebang — no per-script `usage g completion` step required."
+        long_help #"""
+Generate a shell init script that auto-completes any usage shebang script on $PATH
+
+Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab-completion for any executable whose first line is a `usage` shebang — no per-script `usage g completion` step required.
+"""#
         flag --usage-bin help="Override the bin used for calling back to usage-cli" default=usage {
-            long_help "Override the bin used for calling back to usage-cli\n\nYou may need to set this if you have a different bin named \"usage\""
+            long_help #"""
+Override the bin used for calling back to usage-cli
+
+You may need to set this if you have a different bin named "usage"
+"""#
             arg <USAGE_BIN>
         }
         arg <SHELL> help="Shell to generate the init script for" {
@@ -113,7 +147,11 @@ cmd generate subcommand_required=#true help="Generate completions, documentation
             arg <OUT_FILE>
         }
         flag "-s --section" help="Manual section number (default: 1)" default="1" {
-            long_help "Manual section number (default: 1)\n\nCommon sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands"
+            long_help #"""
+Manual section number (default: 1)
+
+Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands
+"""#
             arg <SECTION>
         }
     }
@@ -146,14 +184,28 @@ cmd lint help="Lint a usage spec file for common issues" {
     arg <FILE> help="A usage spec file to lint, use \"-\" to read from stdin"
 }
 cmd powershell help="Execute a shell script using PowerShell" {
-    long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
+    long_help #"""
+Execute a shell script with the specified shell
+
+Typically, this will be called by a script's shebang.
+
+If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
+to properly escape and quote values with spaces in them.
+"""#
     flag -h help="Show help"
     flag --help help="Show help"
     arg <SCRIPT>
     arg "[ARGS]…" help="Arguments to pass to script" required=#false var=#true
 }
 cmd zsh help="Execute a shell script using zsh" {
-    long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
+    long_help #"""
+Execute a shell script with the specified shell
+
+Typically, this will be called by a script's shebang.
+
+If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
+to properly escape and quote values with spaces in them.
+"""#
     flag -h help="Show help"
     flag --help help="Show help"
     arg <SCRIPT>

lib/src/complete/snapshots/usage__complete__bash__tests__complete_bash-3.snap

@@ -20,7 +20,29 @@ bin mycli
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag --flag1 help="flag1 description"
 flag --flag2 help="flag2 description" {
-    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n\n    more code\n\nExamples:\n\n    # run with no arguments to use the interactive selector\n    $ mise use\n\n    # set the current version of node to 20.x in mise.toml of current directory\n    # will write the fuzzy version (e.g.: 20)\n\nsome docs\n\n    $ echo hello world\n    hello world"
+    long_help #"""
+flag2 long description
+
+includes a code block:
+
+    $ echo hello world
+    hello world
+
+    more code
+
+Examples:
+
+    # run with no arguments to use the interactive selector
+    $ mise use
+
+    # set the current version of node to 20.x in mise.toml of current directory
+    # will write the fuzzy version (e.g.: 20)
+
+some docs
+
+    $ echo hello world
+    hello world
+"""#
 }
 flag --flag3 help="flag3 description" negate=--no-flag3
 flag --with-default default="default value"
@@ -36,7 +58,11 @@ arg "[arg2]" help="arg2 description" required=#false default="default value" {
 arg <arg3> help="arg3 description" help_long="arg3 long description"
 arg <argrest>… var=#true
 arg "[with-default]" required=#false default="default value"
-complete plugin run="echo \"plugin-1\nplugin-2\nplugin-3\""
+complete plugin run=#"""
+echo "plugin-1
+plugin-2
+plugin-3"
+"""#
 cmd plugin {
     cmd install {
         long_help "install a plugin"

lib/src/complete/snapshots/usage__complete__fish__tests__complete_fish-3.snap

@@ -17,7 +17,29 @@ bin mycli
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag --flag1 help="flag1 description"
 flag --flag2 help="flag2 description" {
-    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n\n    more code\n\nExamples:\n\n    # run with no arguments to use the interactive selector\n    $ mise use\n\n    # set the current version of node to 20.x in mise.toml of current directory\n    # will write the fuzzy version (e.g.: 20)\n\nsome docs\n\n    $ echo hello world\n    hello world"
+    long_help #"""
+flag2 long description
+
+includes a code block:
+
+    $ echo hello world
+    hello world
+
+    more code
+
+Examples:
+
+    # run with no arguments to use the interactive selector
+    $ mise use
+
+    # set the current version of node to 20.x in mise.toml of current directory
+    # will write the fuzzy version (e.g.: 20)
+
+some docs
+
+    $ echo hello world
+    hello world
+"""#
 }
 flag --flag3 help="flag3 description" negate=--no-flag3
 flag --with-default default="default value"
@@ -33,7 +55,11 @@ arg "[arg2]" help="arg2 description" required=#false default="default value" {
 arg <arg3> help="arg3 description" help_long="arg3 long description"
 arg <argrest>… var=#true
 arg "[with-default]" required=#false default="default value"
-complete plugin run="echo \"plugin-1\nplugin-2\nplugin-3\""
+complete plugin run=#"""
+echo "plugin-1
+plugin-2
+plugin-3"
+"""#
 cmd plugin {
     cmd install {
         long_help "install a plugin"

lib/src/complete/snapshots/usage__complete__nu__tests__complete_nu-3.snap

@@ -9,7 +9,29 @@ bin mycli
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag --flag1 help="flag1 description"
 flag --flag2 help="flag2 description" {
-    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n\n    more code\n\nExamples:\n\n    # run with no arguments to use the interactive selector\n    $ mise use\n\n    # set the current version of node to 20.x in mise.toml of current directory\n    # will write the fuzzy version (e.g.: 20)\n\nsome docs\n\n    $ echo hello world\n    hello world"
+    long_help #"""
+flag2 long description
+
+includes a code block:
+
+    $ echo hello world
+    hello world
+
+    more code
+
+Examples:
+
+    # run with no arguments to use the interactive selector
+    $ mise use
+
+    # set the current version of node to 20.x in mise.toml of current directory
+    # will write the fuzzy version (e.g.: 20)
+
+some docs
+
+    $ echo hello world
+    hello world
+"""#
 }
 flag --flag3 help="flag3 description" negate=--no-flag3
 flag --with-default default="default value"
@@ -25,7 +47,11 @@ arg "[arg2]" help="arg2 description" required=#false default="default value" {
 arg <arg3> help="arg3 description" help_long="arg3 long description"
 arg <argrest>… var=#true
 arg "[with-default]" required=#false default="default value"
-complete plugin run="echo \"plugin-1\nplugin-2\nplugin-3\""
+complete plugin run=#"""
+echo "plugin-1
+plugin-2
+plugin-3"
+"""#
 cmd plugin {
     cmd install {
         long_help "install a plugin"

lib/src/complete/snapshots/usage__complete__powershell__tests__complete_powershell-3.snap

@@ -21,7 +21,29 @@ bin mycli
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag --flag1 help="flag1 description"
 flag --flag2 help="flag2 description" {
-    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n\n    more code\n\nExamples:\n\n    # run with no arguments to use the interactive selector\n    $ mise use\n\n    # set the current version of node to 20.x in mise.toml of current directory\n    # will write the fuzzy version (e.g.: 20)\n\nsome docs\n\n    $ echo hello world\n    hello world"
+    long_help #"""
+flag2 long description
+
+includes a code block:
+
+    $ echo hello world
+    hello world
+
+    more code
+
+Examples:
+
+    # run with no arguments to use the interactive selector
+    $ mise use
+
+    # set the current version of node to 20.x in mise.toml of current directory
+    # will write the fuzzy version (e.g.: 20)
+
+some docs
+
+    $ echo hello world
+    hello world
+"""#
 }
 flag --flag3 help="flag3 description" negate=--no-flag3
 flag --with-default default="default value"
@@ -37,7 +59,11 @@ arg "[arg2]" help="arg2 description" required=#false default="default value" {
 arg <arg3> help="arg3 description" help_long="arg3 long description"
 arg <argrest>… var=#true
 arg "[with-default]" required=#false default="default value"
-complete plugin run="echo \"plugin-1\nplugin-2\nplugin-3\""
+complete plugin run=#"""
+echo "plugin-1
+plugin-2
+plugin-3"
+"""#
 cmd plugin {
     cmd install {
         long_help "install a plugin"

lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap

@@ -24,7 +24,29 @@ bin mycli
 source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 flag --flag1 help="flag1 description"
 flag --flag2 help="flag2 description" {
-    long_help "flag2 long description\n\nincludes a code block:\n\n    $ echo hello world\n    hello world\n\n    more code\n\nExamples:\n\n    # run with no arguments to use the interactive selector\n    $ mise use\n\n    # set the current version of node to 20.x in mise.toml of current directory\n    # will write the fuzzy version (e.g.: 20)\n\nsome docs\n\n    $ echo hello world\n    hello world"
+    long_help #"""
+flag2 long description
+
+includes a code block:
+
+    $ echo hello world
+    hello world
+
+    more code
+
+Examples:
+
+    # run with no arguments to use the interactive selector
+    $ mise use
+
+    # set the current version of node to 20.x in mise.toml of current directory
+    # will write the fuzzy version (e.g.: 20)
+
+some docs
+
+    $ echo hello world
+    hello world
+"""#
 }
 flag --flag3 help="flag3 description" negate=--no-flag3
 flag --with-default default="default value"
@@ -40,7 +62,11 @@ arg "[arg2]" help="arg2 description" required=#false default="default value" {
 arg <arg3> help="arg3 description" help_long="arg3 long description"
 arg <argrest>… var=#true
 arg "[with-default]" required=#false default="default value"
-complete plugin run="echo \"plugin-1\nplugin-2\nplugin-3\""
+complete plugin run=#"""
+echo "plugin-1
+plugin-2
+plugin-3"
+"""#
 cmd plugin {
     cmd install {
         long_help "install a plugin"

lib/src/spec/arg.rs

@@ -7,7 +7,7 @@ use std::str::FromStr;
 use crate::error::UsageErr;
 use crate::spec::builder::SpecArgBuilder;
 use crate::spec::context::ParsingContext;
-use crate::spec::helpers::NodeHelper;
+use crate::spec::helpers::{string_entry, NodeHelper};
 use crate::spec::is_false;
 use crate::{string, SpecChoices};
 
@@ -176,13 +176,13 @@ impl From<&SpecArg> for KdlNode {
         let mut node = KdlNode::new("arg");
         node.push(KdlEntry::new(arg.usage()));
         if let Some(desc) = &arg.help {
-            node.push(KdlEntry::new_prop("help", desc.clone()));
+            node.push(string_entry(Some("help"), desc));
         }
         if let Some(desc) = &arg.help_long {
-            node.push(KdlEntry::new_prop("help_long", desc.clone()));
+            node.push(string_entry(Some("help_long"), desc));
         }
         if let Some(desc) = &arg.help_md {
-            node.push(KdlEntry::new_prop("help_md", desc.clone()));
+            node.push(string_entry(Some("help_md"), desc));
         }
         if !arg.required {
             node.push(KdlEntry::new_prop("required", false));
@@ -211,7 +211,7 @@ impl From<&SpecArg> for KdlNode {
         if !arg.default.is_empty() {
             if arg.default.len() == 1 {
                 // Single value: use property default="bar"
-                node.push(KdlEntry::new_prop("default", arg.default[0].clone()));
+                node.push(string_entry(Some("default"), &arg.default[0]));
             } else {
                 // Multiple values: use child node default { "xyz"; "bar" }
                 let children = node.children_mut().get_or_insert_with(KdlDocument::new);
@@ -228,7 +228,7 @@ impl From<&SpecArg> for KdlNode {
             }
         }
         if let Some(env) = &arg.env {
-            node.push(KdlEntry::new_prop("env", env.clone()));
+            node.push(string_entry(Some("env"), env));
         }
         if let Some(choices) = &arg.choices {
             let children = node.children_mut().get_or_insert_with(KdlDocument::new);