@@ -45,35 +45,58 @@ impl App {
4545 .setting(AppSettings::DisableHelpSubcommand)
4646 .setting(AppSettings::VersionlessSubcommands)
4747 .max_term_width(90)
48− .about(crate_description!())
48+ .about(
49+ "A cat(1) clone with wings.\n\n\
50+ Use '--help' instead of '-h' to see a more detailed version of the help text.",
51+ )
52+ .long_about("A cat(1) clone with syntax highlighting and Git integration.")
4953 .arg(
5054 Arg::with_name("language")
5155 .short("l")
5256 .long("language")
5357 .help("Set the language for highlighting")
58+ .long_help(
59+ "Set the language for syntax highlighting. The language can be \
60+ specified as a name (like 'C++' or 'LaTeX') or possible file \
61+ extension (like 'cpp', 'hpp' or 'md'). Use '--list-languages' \
62+ to show all supported language names and file extensions",
63+ )
5464 .takes_value(true),
5565 )
5666 .arg(
5767 Arg::with_name("FILE")
58− .help("File(s) to print")
68+ .help("File(s) to print / concatenate. Use '-' for standard input.")
69+ .long_help(
70+ "File(s) to print. Use no argument or '-' to read from standard \
71+ input",
72+ )
5973 .multiple(true)
6074 .empty_values(false),
6175 )
6276 .arg(
6377 Arg::with_name("style")
6478 .long("style")
79+ .value_name("style-components")
6580 .use_delimiter(true)
6681 .takes_value(true)
6782 .possible_values(&[
6883 "auto", "full", "plain", "changes", "header", "grid", "numbers",
6984 ])
7085 .default_value("auto")
71− .help("Additional info to display along with content"),
86+ .help("Comma-separated list of style elements to display")
87+ .long_help(
88+ "Configure which elements (line numbers, file headers, grid \
89+ borders, Git modifications, ..) to display in addition to the \
90+ file contents. The argument is a comma-separated list of \
91+ components to display (e.g. 'numbers,changes,grid') or a \
92+ pre-defined style ('full')",
93+ ),
7294 )
7395 .arg(
7496 Arg::with_name("color")
7597 .long("color")
7698 .takes_value(true)
99+ .value_name("when")
77100 .possible_values(&["auto", "never", "always"])
78101 .default_value("auto")
79102 .help("When to use colors"),
@@ -82,14 +105,17 @@ impl App {
82105 Arg::with_name("paging")
83106 .long("paging")
84107 .takes_value(true)
108+ .value_name("when")
85109 .possible_values(&["auto", "never", "always"])
86110 .default_value("auto")
87− .help("When to use the pager"),
111+ .help("When to use the pager")
112+ .long_help("Specify when to use the pager (less)"),
88113 )
89114 .arg(
90115 Arg::with_name("wrap")
91116 .long("wrap")
92117 .takes_value(true)
118+ .value_name("mode")
93119 .possible_values(&["character", "never"])
94120 .default_value("character")
95121 .help("When to wrap text"),
@@ -97,30 +123,46 @@ impl App {
97123 .arg(
98124 Arg::with_name("list-languages")
99125 .long("list-languages")
100− .help("Displays supported languages"),
126+ .help("Displays supported languages")
127+ .long_help("Display a list of supported languages"),
101128 )
102129 .arg(
103130 Arg::with_name("theme")
104131 .long("theme")
105132 .takes_value(true)
106− .help("Set the theme for highlighting"),
133+ .help("Set the theme for highlighting")
134+ .long_help(
135+ "Set the theme for syntax highlighting. Use '--list-themes' to \
136+ see all available themes",
137+ ),
107138 )
108139 .arg(
109140 Arg::with_name("list-themes")
110141 .long("list-themes")
111− .help("Displays supported themes"),
142+ .help("Displays supported themes")
143+ .help("Display a list of supported themes for syntax highlighting"),
112144 )
113145 .arg(
114146 Arg::with_name("number")
115147 .long("number")
116148 .short("n")
117149 .conflicts_with("style")
118− .help("Alias for '--style=numbers'"),
150+ .help("Show line numbers (alias for '--style=numbers')")
151+ .long_help(
152+ "Show line numbers (no other decorations). This is an alias for \
153+ '--style=numbers'",
154+ ),
119155 )
120156 .arg(
121157 Arg::with_name("unbuffered")
122158 .short("u")
123− .help("(ignored)"),
159+ .help("(ignored)")
160+ // TODO: use '.hidden_short_help(true)' when the next clap version is released
161+ .long_help(
162+ "This option exists for POSIX-compliance reasons ('u' is for \
163+ 'unbuffered'). The output is always unbuffered - this option \
164+ it simply ignored.",
165+ ),
124166 )
125167 .subcommand(
126168 SubCommand::with_name("cache")
@@ -130,7 +172,10 @@ impl App {
130172 .long("init")
131173 .short("i")
132174 .help("Initialize the syntax/theme cache")
133− .long_help("Initialize the syntax/theme cache by loading from the source directory (default: the configuration directory)"),
175+ .long_help(
176+ "Initialize the syntax/theme cache by loading from the \
177+ source directory (default: the configuration directory)",
178+ ),
134179 )
135180 .arg(
136181 Arg::with_name("clear")
@@ -163,8 +208,10 @@ impl App {
163208 .requires("init")
164209 .takes_value(true)
165210 .value_name("dir")
166− .help("Use a different source to store the cached syntax and theme set"),
167− )
211+ .help(
212+ "Use a different source to store the cached syntax and theme set",
213+ ),
214+ ),
168215 )
169216 .help_message("Print this help message.")
170217 .version_message("Show version information.")