docs: How to override multi-line usage
Extend Command::override_usage() doc string to describe how to format
multiple usage lines to be compatible with clap's default help formatter.
Relates-to:
@@ -1604,6 +1604,16 @@ impl Command {
/// strings. After this setting is set, this will be *the only* usage string
/// displayed to the user!
///
+ /// # Multiple usage lines
+ ///
+ /// Multiple usage lines may be present in the usage argument, but some
+ /// rules need to be followed to ensure the usage lines are formatted
+ /// correctly by the default help formatter:
+ ///
+ /// - Do not indent the first usage line.
+ /// - Indent all subsequent usage lines with four spaces.
+ /// - The last line must not end with a newline.
+ ///
/// # Examples
///
/// ```no_run
@@ -1612,6 +1622,33 @@ impl Command {
/// .override_usage("myapp [-clDas] <some_file>")
/// # ;
/// ```
+ ///
+ /// Or for multiple usage lines:
+ ///
+ /// ```no_run
+ /// # use clap::{Command, Arg};
+ /// Command::new("myprog").override_usage(
+ /// "\
+ /// myapp -X [-a] [-b] <file>
+ /// myapp -Y [-c] <file1> <file2>
+ /// myapp -Z [-d|-e]"
+ /// )
+ /// # ;
+ /// ```
+ ///
+ /// or equivalently, but with different string escaping:
+ ///
+ /// ```no_run
+ /// # use clap::{Command, Arg};
+ /// Command::new("myprog")
+ /// .override_usage(
+ /// "myapp -X [-a] [-b] <file>\n \
+ /// myapp -Y [-c] <file1> <file2>\n \
+ /// myapp -Z [-d|-e]"
+ /// )
+ /// # ;
+ /// ```
+ ///
/// [`ArgMatches::usage`]: ArgMatches::usage()
#[must_use]
pub fn override_usage(mut self, usage: impl Into<Str>) -> Self {
