From 3b5fcf461991777fd7bd9f4b89c26d30fc5eb7b3 Mon Sep 17 00:00:00 2001 From: Helder M Date: Wed, 23 Oct 2019 23:25:02 +0100 Subject: [PATCH] Update options sort order in --help and manpage file This commit updates the sort order of --help options in order to improve usability/importance putting most useful/used commands on top. In addition to that, similar options were grouped together. --- assets/manual/bat.1.in | 140 +++++++-------- src/bin/bat/clap_app.rs | 370 ++++++++++++++++++++-------------------- 2 files changed, 255 insertions(+), 255 deletions(-) diff --git a/assets/manual/bat.1.in b/assets/manual/bat.1.in index b6659d13..00aeda46 100644 --- a/assets/manual/bat.1.in +++ b/assets/manual/bat.1.in @@ -15,44 +15,10 @@ General remarks Command-line options like '-l'/'--language' that take values can be specified as either '--language value', '--language=value', '-l value' or '-lvalue'. .HP -\fB\-l\fR, \fB\-\-language\fR +\fB\-A\fR, \fB\-\-show\-all\fR .IP -Explicitly set the language for syntax highlighting. The language can be -specified as a name (like 'C++' or 'LaTeX') or possible file extension -(like 'cpp', 'hpp' or 'md'). Use '\-\-list\-languages' to show all supported -language names and file extensions. -.HP -\fB\-L\fR, \fB\-\-list\-languages\fR -.IP -Display a list of supported languages for syntax highlighting. -.HP -\fB\-m\fR, \fB\-\-map\-syntax\fR ... -.IP -Map a file extension or file name to an existing syntax. For example, to -highlight *.conf files with the INI syntax, use '\-m conf:ini'. To -highlight files named '.myignore' with the Git Ignore syntax, use '\-m -\&.myignore:gitignore'. -.HP -\fB\-\-theme\fR -.IP -Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all -available themes. To set a default theme, add the '\-\-theme="..."' option -to the configuration file or export the BAT_THEME environment variable -(e.g.: export BAT_THEME="..."). -.HP -\fB\-\-list\-themes\fR -.IP -Display a list of supported themes for syntax highlighting. -.HP -\fB\-\-style\fR -.IP -Configure which elements (line numbers, file headers, grid borders, Git -modifications, ..) to display in addition to the file contents. The -argument is a comma\-separated list of components to display (e.g. -\&'numbers,changes,grid') or a pre\-defined style ('full'). To set a default -style, add the '\-\-style=".."' option to the configuration file or export -the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible -values: *auto*, full, plain, changes, header, grid, numbers, snip. +Show non\-printable characters like space, tab or newline. Use '\-\-tabs' to +control the width of the tab\-placeholders. .HP \fB\-p\fR, \fB\-\-plain\fR .IP @@ -60,32 +26,39 @@ Only show plain style, no decorations. This is an alias for \&'\-\-style=plain'. When '\-p' is used twice ('\-pp'), it also disables automatic paging (alias for '\-\-style=plain \fB\-\-pager\fR=\fI\,never\/\fR'). .HP -\fB\-n\fR, \fB\-\-number\fR +\fB\-l\fR, \fB\-\-language\fR .IP -Only show line numbers, no other decorations. This is an alias for -\&'\-\-style=numbers' -.HP -\fB\-A\fR, \fB\-\-show\-all\fR -.IP -Show non\-printable characters like space, tab or newline. Use '\-\-tabs' to -control the width of the tab\-placeholders. -.HP -\fB\-r\fR, \fB\-\-line\-range\fR ... -.IP -Only print the specified range of lines for each file. For example: -.RS -.IP "\-\-line\-range 30:40" -prints lines 30 to 40 -.IP "\-\-line\-range :40" -prints lines 1 to 40 -.IP "\-\-line\-range 40:" -prints lines 40 to the end of the file -.RE +Explicitly set the language for syntax highlighting. The language can be +specified as a name (like 'C++' or 'LaTeX') or possible file extension +(like 'cpp', 'hpp' or 'md'). Use '\-\-list\-languages' to show all supported +language names and file extensions. .HP \fB\-H\fR, \fB\-\-highlight\-line\fR ... .IP Highlight the N\-th line with a different background color .HP +\fB\-\-tabs\fR +.IP +Set the tab width to T spaces. Use a width of 0 to pass tabs through +directly +.HP +\fB\-\-wrap\fR +.IP +Specify the text\-wrapping mode (*auto*, never, character). The +\&'\-\-terminal\-width' option can be used in addition to control the output +width. +.HP +\fB\-\-terminal\-width\fR +.IP +Explicitly set the width of the terminal instead of determining it +automatically. If prefixed with '+' or '\-', the value will be treated as +an offset to the actual terminal width. See also: '\-\-wrap'. +.HP +\fB\-n\fR, \fB\-\-number\fR +.IP +Only show line numbers, no other decorations. This is an alias for +\&'\-\-style=numbers' +.HP \fB\-\-color\fR .IP Specify when to use colored output. The automatic mode only enables colors @@ -118,28 +91,55 @@ BAT_PAGER environment variables. The default pager is 'less'. To disable the pager completely, use the '\-\-paging' option. Example: '\-\-pager "less \fB\-RF\fR"'. .HP -\fB\-\-wrap\fR +\fB\-m\fR, \fB\-\-map\-syntax\fR ... .IP -Specify the text\-wrapping mode (*auto*, never, character). The -\&'\-\-terminal\-width' option can be used in addition to control the output -width. +Map a file extension or file name to an existing syntax. For example, to +highlight *.conf files with the INI syntax, use '\-m conf:ini'. To +highlight files named '.myignore' with the Git Ignore syntax, use '\-m +\&.myignore:gitignore'. .HP -\fB\-\-tabs\fR +\fB\-\-theme\fR .IP -Set the tab width to T spaces. Use a width of 0 to pass tabs through -directly +Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all +available themes. To set a default theme, add the '\-\-theme="..."' option +to the configuration file or export the BAT_THEME environment variable +(e.g.: export BAT_THEME="..."). +.HP +\fB\-\-list\-themes\fR +.IP +Display a list of supported themes for syntax highlighting. +.HP +\fB\-\-style\fR +.IP +Configure which elements (line numbers, file headers, grid borders, Git +modifications, ..) to display in addition to the file contents. The +argument is a comma\-separated list of components to display (e.g. +\&'numbers,changes,grid') or a pre\-defined style ('full'). To set a default +style, add the '\-\-style=".."' option to the configuration file or export +the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible +values: *auto*, full, plain, changes, header, grid, numbers, snip. +.HP +\fB\-r\fR, \fB\-\-line\-range\fR ... +.IP +Only print the specified range of lines for each file. For example: +.RS +.IP "\-\-line\-range 30:40" +prints lines 30 to 40 +.IP "\-\-line\-range :40" +prints lines 1 to 40 +.IP "\-\-line\-range 40:" +prints lines 40 to the end of the file +.RE +.HP +\fB\-L\fR, \fB\-\-list\-languages\fR +.IP +Display a list of supported languages for syntax highlighting. .HP \fB\-u\fR, \fB\-\-unbuffered\fR .IP This option exists for POSIX\-compliance reasons ('u' is for 'unbuffered'). The output is always unbuffered \- this option is simply ignored. .HP -\fB\-\-terminal\-width\fR -.IP -Explicitly set the width of the terminal instead of determining it -automatically. If prefixed with '+' or '\-', the value will be treated as -an offset to the actual terminal width. See also: '\-\-wrap'. -.HP \fB\-h\fR, \fB\-\-help\fR .IP Print this help message. diff --git a/src/bin/bat/clap_app.rs b/src/bin/bat/clap_app.rs index 62a8e1c2..536488d0 100644 --- a/src/bin/bat/clap_app.rs +++ b/src/bin/bat/clap_app.rs @@ -35,103 +35,16 @@ pub fn build_app(interactive_output: bool) -> ClapApp<'static, 'static> { .empty_values(false), ) .arg( - Arg::with_name("language") - .short("l") - .long("language") - .overrides_with("language") - .help("Set the language for syntax highlighting.") + Arg::with_name("show-all") + .long("show-all") + .alias("show-nonprintable") + .short("A") + .conflicts_with("language") + .help("Show non-printable characters (space, tab, newline, ..).") .long_help( - "Explicitly set the language for syntax highlighting. The language can be \ - specified as a name (like 'C++' or 'LaTeX') or possible file extension \ - (like 'cpp', 'hpp' or 'md'). Use '--list-languages' to show all supported \ - language names and file extensions.", - ) - .takes_value(true), - ) - .arg( - Arg::with_name("list-languages") - .long("list-languages") - .short("L") - .conflicts_with("list-themes") - .help("Display all supported languages.") - .long_help("Display a list of supported languages for syntax highlighting."), - ) - .arg( - Arg::with_name("map-syntax") - .short("m") - .long("map-syntax") - .multiple(true) - .takes_value(true) - .number_of_values(1) - .value_name("from:to") - .help("Map a file extension or name to an existing syntax.") - .long_help( - "Map a file extension or file name to an existing syntax. For example, \ - to highlight *.conf files with the INI syntax, use '-m conf:ini'. \ - To highlight files named '.myignore' with the Git Ignore syntax, use \ - '-m .myignore:gitignore'.", - ) - .takes_value(true), - ) - .arg( - Arg::with_name("theme") - .long("theme") - .overrides_with("theme") - .takes_value(true) - .help("Set the color theme for syntax highlighting.") - .long_help( - "Set the theme for syntax highlighting. Use '--list-themes' to \ - see all available themes. To set a default theme, add the \ - '--theme=\"...\"' option to the configuration file or export the \ - BAT_THEME environment variable (e.g.: export \ - BAT_THEME=\"...\").", - ), - ) - .arg( - Arg::with_name("list-themes") - .long("list-themes") - .help("Display all supported highlighting themes.") - .long_help("Display a list of supported themes for syntax highlighting."), - ) - .arg( - Arg::with_name("style") - .long("style") - .value_name("style-components") - // Need to turn this off for overrides_with to work as we want. See the bottom most - // example at https://docs.rs/clap/2.32.0/clap/struct.Arg.html#method.overrides_with - .use_delimiter(false) - .takes_value(true) - .overrides_with("style") - .overrides_with("plain") - .overrides_with("number") - // Cannot use clap's built in validation because we have to turn off clap's delimiters - .validator(|val| { - let mut invalid_vals = val.split(',').filter(|style| { - !&[ - "auto", "full", "plain", "changes", "header", "grid", "numbers", "snip" - ] - .contains(style) - }); - - if let Some(invalid) = invalid_vals.next() { - Err(format!("Unknown style, '{}'", invalid)) - } else { - Ok(()) - } - }) - .help( - "Comma-separated list of style elements to display \ - (*auto*, full, plain, changes, header, grid, numbers, snip).", - ) - .long_help( - "Configure which elements (line numbers, file headers, grid \ - borders, Git modifications, ..) to display in addition to the \ - file contents. The argument is a comma-separated list of \ - components to display (e.g. 'numbers,changes,grid') or a \ - pre-defined style ('full'). To set a default style, add the \ - '--style=\"..\"' option to the configuration file or export the \ - BAT_STYLE environment variable (e.g.: export BAT_STYLE=\"..\"). \ - Possible values: *auto*, full, plain, changes, header, grid, numbers, snip.", + "Show non-printable characters like space, tab or newline. \ + This option can also be used to print binary files. \ + Use '--tabs' to control the width of the tab-placeholders." ), ) .arg( @@ -149,45 +62,18 @@ pub fn build_app(interactive_output: bool) -> ClapApp<'static, 'static> { ), ) .arg( - Arg::with_name("number") - .long("number") - .overrides_with("number") - .short("n") - .help("Show line numbers (alias for '--style=numbers').") + Arg::with_name("language") + .short("l") + .long("language") + .overrides_with("language") + .help("Set the language for syntax highlighting.") .long_help( - "Only show line numbers, no other decorations. This is an alias for \ - '--style=numbers'", - ), - ) - .arg( - Arg::with_name("show-all") - .long("show-all") - .alias("show-nonprintable") - .short("A") - .conflicts_with("language") - .help("Show non-printable characters (space, tab, newline, ..).") - .long_help( - "Show non-printable characters like space, tab or newline. \ - This option can also be used to print binary files. \ - Use '--tabs' to control the width of the tab-placeholders." - ), - ) - .arg( - Arg::with_name("line-range") - .long("line-range") - .short("r") - .multiple(true) - .takes_value(true) - .number_of_values(1) - .value_name("N:M") - .help("Only print the lines from N to M.") - .long_help( - "Only print the specified range of lines for each file. \ - For example:\n \ - '--line-range 30:40' prints lines 30 to 40\n \ - '--line-range :40' prints lines 1 to 40\n \ - '--line-range 40:' prints lines 40 to the end of the file", - ), + "Explicitly set the language for syntax highlighting. The language can be \ + specified as a name (like 'C++' or 'LaTeX') or possible file extension \ + (like 'cpp', 'hpp' or 'md'). Use '--list-languages' to show all supported \ + language names and file extensions.", + ) + .takes_value(true), ) .arg( Arg::with_name("highlight-line") @@ -202,6 +88,76 @@ pub fn build_app(interactive_output: bool) -> ClapApp<'static, 'static> { "Highlight the N-th line with a different background color", ), ) + .arg( + Arg::with_name("tabs") + .long("tabs") + .overrides_with("tabs") + .takes_value(true) + .value_name("T") + .validator( + |t| { + t.parse::() + .map_err(|_t| "must be a number") + .map(|_t| ()) // Convert to Result<(), &str> + .map_err(|e| e.to_string()) + }, // Convert to Result<(), String> + ) + .help("Set the tab width to T spaces.") + .long_help( + "Set the tab width to T spaces. Use a width of 0 to pass tabs through \ + directly", + ), + ) + .arg( + Arg::with_name("wrap") + .long("wrap") + .overrides_with("wrap") + .takes_value(true) + .value_name("mode") + .possible_values(&["auto", "never", "character"]) + .default_value("auto") + .hide_default_value(true) + .help("Specify the text-wrapping mode (*auto*, never, character).") + .long_help("Specify the text-wrapping mode (*auto*, never, character). \ + The '--terminal-width' option can be used in addition to \ + control the output width."), + ) + .arg( + Arg::with_name("terminal-width") + .long("terminal-width") + .takes_value(true) + .value_name("width") + .hidden_short_help(true) + .allow_hyphen_values(true) + .validator( + |t| { + let is_offset = t.starts_with('+') || t.starts_with('-'); + t.parse::() + .map_err(|_e| "must be an offset or number") + .and_then(|v| if v == 0 && !is_offset { + Err("terminal width cannot be zero".into()) + } else { + Ok(()) + }) + .map_err(|e| e.to_string()) + }) + .help( + "Explicitly set the width of the terminal instead of determining it \ + automatically. If prefixed with '+' or '-', the value will be treated \ + as an offset to the actual terminal width. See also: '--wrap'.", + ), + ) + .arg( + Arg::with_name("number") + .long("number") + .overrides_with("number") + .short("n") + .help("Show line numbers (alias for '--style=numbers').") + .long_help( + "Only show line numbers, no other decorations. This is an alias for \ + '--style=numbers'", + ), + ) .arg( Arg::with_name("color") .long("color") @@ -281,39 +237,108 @@ pub fn build_app(interactive_output: bool) -> ClapApp<'static, 'static> { ), ) .arg( - Arg::with_name("wrap") - .long("wrap") - .overrides_with("wrap") + Arg::with_name("map-syntax") + .short("m") + .long("map-syntax") + .multiple(true) .takes_value(true) - .value_name("mode") - .possible_values(&["auto", "never", "character"]) - .default_value("auto") - .hide_default_value(true) - .help("Specify the text-wrapping mode (*auto*, never, character).") - .long_help("Specify the text-wrapping mode (*auto*, never, character). \ - The '--terminal-width' option can be used in addition to \ - control the output width."), + .number_of_values(1) + .value_name("from:to") + .help("Map a file extension or name to an existing syntax.") + .long_help( + "Map a file extension or file name to an existing syntax. For example, \ + to highlight *.conf files with the INI syntax, use '-m conf:ini'. \ + To highlight files named '.myignore' with the Git Ignore syntax, use \ + '-m .myignore:gitignore'.", + ) + .takes_value(true), ) .arg( - Arg::with_name("tabs") - .long("tabs") - .overrides_with("tabs") + Arg::with_name("theme") + .long("theme") + .overrides_with("theme") .takes_value(true) - .value_name("T") - .validator( - |t| { - t.parse::() - .map_err(|_t| "must be a number") - .map(|_t| ()) // Convert to Result<(), &str> - .map_err(|e| e.to_string()) - }, // Convert to Result<(), String> - ) - .help("Set the tab width to T spaces.") + .help("Set the color theme for syntax highlighting.") .long_help( - "Set the tab width to T spaces. Use a width of 0 to pass tabs through \ - directly", + "Set the theme for syntax highlighting. Use '--list-themes' to \ + see all available themes. To set a default theme, add the \ + '--theme=\"...\"' option to the configuration file or export the \ + BAT_THEME environment variable (e.g.: export \ + BAT_THEME=\"...\").", ), ) + .arg( + Arg::with_name("list-themes") + .long("list-themes") + .help("Display all supported highlighting themes.") + .long_help("Display a list of supported themes for syntax highlighting."), + ) + .arg( + Arg::with_name("style") + .long("style") + .value_name("style-components") + // Need to turn this off for overrides_with to work as we want. See the bottom most + // example at https://docs.rs/clap/2.32.0/clap/struct.Arg.html#method.overrides_with + .use_delimiter(false) + .takes_value(true) + .overrides_with("style") + .overrides_with("plain") + .overrides_with("number") + // Cannot use clap's built in validation because we have to turn off clap's delimiters + .validator(|val| { + let mut invalid_vals = val.split(',').filter(|style| { + !&[ + "auto", "full", "plain", "changes", "header", "grid", "numbers", "snip" + ] + .contains(style) + }); + + if let Some(invalid) = invalid_vals.next() { + Err(format!("Unknown style, '{}'", invalid)) + } else { + Ok(()) + } + }) + .help( + "Comma-separated list of style elements to display \ + (*auto*, full, plain, changes, header, grid, numbers, snip).", + ) + .long_help( + "Configure which elements (line numbers, file headers, grid \ + borders, Git modifications, ..) to display in addition to the \ + file contents. The argument is a comma-separated list of \ + components to display (e.g. 'numbers,changes,grid') or a \ + pre-defined style ('full'). To set a default style, add the \ + '--style=\"..\"' option to the configuration file or export the \ + BAT_STYLE environment variable (e.g.: export BAT_STYLE=\"..\"). \ + Possible values: *auto*, full, plain, changes, header, grid, numbers, snip.", + ), + ) + .arg( + Arg::with_name("line-range") + .long("line-range") + .short("r") + .multiple(true) + .takes_value(true) + .number_of_values(1) + .value_name("N:M") + .help("Only print the lines from N to M.") + .long_help( + "Only print the specified range of lines for each file. \ + For example:\n \ + '--line-range 30:40' prints lines 30 to 40\n \ + '--line-range :40' prints lines 1 to 40\n \ + '--line-range 40:' prints lines 40 to the end of the file", + ), + ) + .arg( + Arg::with_name("list-languages") + .long("list-languages") + .short("L") + .conflicts_with("list-themes") + .help("Display all supported languages.") + .long_help("Display a list of supported languages for syntax highlighting."), + ) .arg( Arg::with_name("unbuffered") .short("u") @@ -325,31 +350,6 @@ pub fn build_app(interactive_output: bool) -> ClapApp<'static, 'static> { is simply ignored.", ), ) - .arg( - Arg::with_name("terminal-width") - .long("terminal-width") - .takes_value(true) - .value_name("width") - .hidden_short_help(true) - .allow_hyphen_values(true) - .validator( - |t| { - let is_offset = t.starts_with('+') || t.starts_with('-'); - t.parse::() - .map_err(|_e| "must be an offset or number") - .and_then(|v| if v == 0 && !is_offset { - Err("terminal width cannot be zero".into()) - } else { - Ok(()) - }) - .map_err(|e| e.to_string()) - }) - .help( - "Explicitly set the width of the terminal instead of determining it \ - automatically. If prefixed with '+' or '-', the value will be treated \ - as an offset to the actual terminal width. See also: '--wrap'.", - ), - ) .arg( Arg::with_name("no-config") .long("no-config")