Make separate category for global options

docs/reference/rew-ascii.md

@@ -14,3 +14,7 @@ rew ascii [OPTIONS]
 
 Delete non-ASCII characters instead of converting them
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-first.md

@@ -16,3 +16,7 @@ Maximum number of lines to print
 
 **Default value**: `1`
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-join.md

@@ -22,3 +22,7 @@ Separator
 
 Print trailing separator
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-last.md

@@ -16,3 +16,7 @@ Maximum number of lines to print
 
 **Default value**: `1`
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-loop.md

@@ -8,3 +8,7 @@ Repeat all lines in a loop
 rew loop
 ```
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-lower.md

@@ -8,3 +8,7 @@ Convert characters to lowercase
 rew lower
 ```
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-norm.md

@@ -8,3 +8,7 @@ Normalize line separators to LF
 rew norm
 ```
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-seq.md

@@ -22,3 +22,7 @@ Increment between numbers
 
 **Default value**: `1`
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-sink.md

@@ -10,3 +10,7 @@ Works like `/dev/null` redirection but is (obviously) less efficient.
 rew sink
 ```
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-skip.md

@@ -14,3 +14,7 @@ rew skip <COUNT>
 
 Number of lines to skip
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-split.md

@@ -20,3 +20,7 @@ Separator (single byte character)
 
 Ignore trailing separator
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-stream.md

@@ -14,3 +14,7 @@ rew stream [VALUES]...
 
 Values to print
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-trim.md

@@ -20,3 +20,7 @@ Trim the beginning
 
 Trim the end
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-upper.md

@@ -8,3 +8,7 @@ Convert characters to lowercase
 rew upper
 ```
 
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
+

docs/reference/rew-x.md

@@ -5,12 +5,24 @@ Compose commands using a pattern
 ## Usage
 
 ```shell
-rew x [ARGS]...
+rew x [OPTIONS] <PATTERN>
 ```
 
 ## Arguments
 
-### `ARGS`
+### `PATTERN`
 
-Arguments passed to the command
+Composition pattern
+
+## Options
+
+### `-e, --escape`
+
+Escape character for the pattern
+
+**Default value**: `\`
+
+## Global options
+
+See [rew reference](rew.md#global-options) for list of additional global options.
 

docs/reference/rew.md

@@ -26,7 +26,7 @@ rew [OPTIONS] <COMMAND>
 - [trim](./rew-trim.md) - Trim whitespaces from each line
 - [upper](./rew-upper.md) - Convert characters to lowercase
 
-## Options
+## Global options
 
 ### `-0, --null`
 

src/app.rs

@@ -11,11 +11,13 @@ use std::io::Write;
 use std::process;
 
 pub fn build_app(commands: &Vec<Box<dyn CommandMeta>>) -> App {
-    let mut app = GlobalArgs::augment_args(command!()).subcommand_required(true);
+    let mut app = command!().subcommand_required(true);
+
     for command in commands {
         app = app.subcommand(command.build())
     }
-    app
+
+    GlobalArgs::augment_args(app.next_help_heading("Global options"))
 }
 
 pub fn handle_error(result: Result<()>) {

src/exec/args.rs

@@ -20,7 +20,7 @@ pub struct GlobalArgs {
         env = "REW_BUFF",
         default_value_t = Buffering::default(),
         verbatim_doc_comment,
-        hide_default_value = true
+        hide_default_value = true,
     )]
     pub buff: Buffering,
 
@@ -35,7 +35,7 @@ pub struct GlobalArgs {
         name = "BYTES",
         env = "REW_MAX_LINE",
         default_value_t = ByteSize::new(n_mib_bytes(1)),
-        verbatim_doc_comment
+        verbatim_doc_comment,
     )]
     pub max_line: ByteSize,
 }

xtask/src/gen_docs.rs

@@ -1,4 +1,3 @@
-use crate::utils::escape_name;
 use anyhow::anyhow;
 use anyhow::Context;
 use anyhow::Result;
@@ -26,31 +25,33 @@ pub fn generate_docs(app: Command, root_dir: &Path) -> Result<()> {
         create_dir_all(&usage_dir)?;
     }
 
-    let mut command_names: Vec<String> = Vec::new();
-    generate_docs_file(&app, None, &mut command_names, &usage_dir)?;
-    update_summary_reference(command_names, &docs_dir)?;
+    let mut command_paths: Vec<Vec<&str>> = Vec::new();
+    generate_docs_file(&app, &[], false, &mut command_paths, &usage_dir)?;
+    update_summary_reference(&command_paths, &docs_dir)?;
 
     println!("Done");
     Ok(())
 }
 
-fn generate_docs_file(
-    command: &Command,
-    parent: Option<&str>,
-    command_names: &mut Vec<String>,
+fn generate_docs_file<'a>(
+    command: &'a Command,
+    parent_path: &[&'a str],
+    parent_global_options: bool,
+    command_paths: &mut Vec<Vec<&'a str>>,
     target_dir: &Path,
 ) -> Result<()> {
-    let full_name = if let Some(parent) = parent {
-        format!("{} {}", parent, command.get_name())
-    } else {
-        command.get_name().to_string()
-    };
+    let parent_call = parent_path.join(" ");
+    let parent_stem = parent_path.join("-");
 
-    command_names.push(full_name.clone());
+    let command_path = [parent_path, &[command.get_name()]].concat();
+    let command_call = command_path.join(" ");
 
-    let file_name = Path::new(&escape_name(&full_name)).with_extension("md");
+    let file_stem = command_path.join("-");
+    let file_name = Path::new(&file_stem).with_extension("md");
     let file_path = target_dir.join(file_name);
 
+    command_paths.push(command_path.clone());
+
     let custom_content = if file_path.exists() {
         println!("Updating {:?}", file_path);
 
@@ -72,9 +73,9 @@ fn generate_docs_file(
     let about = command
         .get_long_about()
         .or_else(|| command.get_about())
-        .ok_or_else(|| anyhow!("Expected '{}' command to have about", full_name))?;
+        .ok_or_else(|| anyhow!("Expected '{}' command to have about", command_call))?;
 
-    writeln!(&mut writer, "# {}", full_name)?;
+    writeln!(&mut writer, "# {}", command_call)?;
     writeln!(&mut writer)?;
     writeln!(&mut writer, "{}", about)?;
     writeln!(&mut writer)?;
@@ -89,10 +90,10 @@ fn generate_docs_file(
     writeln!(&mut writer)?;
     writeln!(&mut writer, "```shell")?;
 
-    if let Some(parent) = parent {
-        writeln!(&mut writer, "{} {}", parent, usage)?;
-    } else {
+    if parent_path.is_empty() {
         writeln!(&mut writer, "{}", usage)?;
+    } else {
+        writeln!(&mut writer, "{} {}", parent_call, usage)?;
     }
 
     writeln!(&mut writer, "```")?;
@@ -104,7 +105,7 @@ fn generate_docs_file(
         writeln!(&mut writer)?;
 
         for subcommand in &subcommands {
-            write_subcommand(&mut writer, subcommand, &full_name)?;
+            write_subcommand(&mut writer, subcommand, &command_path)?;
         }
 
         writeln!(&mut writer)?;
@@ -121,13 +122,13 @@ fn generate_docs_file(
 
         for arg in arguments {
             write_argument(&mut writer, arg)
-                .with_context(|| format!("Failed to process command '{}'", full_name))?;
+                .with_context(|| format!("Failed to process command '{}'", command_call))?;
         }
     }
 
     let options: Vec<&Arg> = command
         .get_arguments()
-        .filter(|arg| !arg.is_positional())
+        .filter(|arg| !arg.is_positional() && !arg.is_global_set())
         .collect();
 
     if !options.is_empty() {
@@ -136,7 +137,31 @@ fn generate_docs_file(
 
         for opt in options {
             write_argument(&mut writer, opt)
-                .with_context(|| format!("Failed to process command '{}'", full_name))?;
+                .with_context(|| format!("Failed to process command '{}'", command_call))?;
+        }
+    }
+
+    let global_options: Vec<&Arg> = command
+        .get_arguments()
+        .filter(|arg| !arg.is_positional() && arg.is_global_set())
+        .collect();
+
+    if !global_options.is_empty() || parent_global_options {
+        writeln!(&mut writer, "## Global options")?;
+        writeln!(&mut writer)?;
+
+        if parent_global_options {
+            writeln!(
+                &mut writer,
+                "See [{} reference]({}.md#global-options) for list of additional global options.",
+                parent_call, parent_stem
+            )?;
+            writeln!(&mut writer)?;
+        }
+
+        for opt in &global_options {
+            write_argument(&mut writer, opt)
+                .with_context(|| format!("Failed to process command '{}'", command_call))?;
         }
     }
 
@@ -145,7 +170,13 @@ fn generate_docs_file(
     }
 
     for subcommand in subcommands {
-        generate_docs_file(subcommand, Some(&full_name), command_names, target_dir)?;
+        generate_docs_file(
+            subcommand,
+            &command_path,
+            !global_options.is_empty(),
+            command_paths,
+            target_dir,
+        )?;
     }
 
     Ok(())
@@ -222,29 +253,26 @@ fn write_argument(mut writer: &mut BufWriter<File>, arg: &Arg) -> Result<()> {
 fn write_subcommand(
     mut writer: &mut BufWriter<File>,
     command: &Command,
-    parent: &str,
+    parent_path: &[&str],
 ) -> Result<()> {
     let name = command.get_name();
-    let full_name = format!("{} {}", parent, name);
+    let path = [parent_path, &[name]].concat();
+    let call = path.join(" ");
+    let stem = path.join("-");
+
     // Prevent markdown formatting it as checkbox `[x]` by making it `[x ]`
     let title = if name == "x" { "x " } else { name };
 
     let about = command
         .get_about()
-        .ok_or_else(|| anyhow!("Expected '{}' command to have about", full_name))?;
+        .ok_or_else(|| anyhow!("Expected '{}' command to have about", call))?;
 
-    writeln!(
-        &mut writer,
-        "- [{}](./{}.md) - {}",
-        title,
-        escape_name(&full_name),
-        about
-    )?;
+    writeln!(&mut writer, "- [{}](./{}.md) - {}", title, stem, about)?;
 
     Ok(())
 }
 
-fn update_summary_reference(command_names: Vec<String>, target_dir: &Path) -> Result<()> {
+fn update_summary_reference(command_paths: &Vec<Vec<&str>>, target_dir: &Path) -> Result<()> {
     let summary_path = target_dir.join("SUMMARY.md");
     println!("Updating reference in {:?}", summary_path);
 
@@ -274,12 +302,12 @@ fn update_summary_reference(command_names: Vec<String>, target_dir: &Path) -> Re
     let mut reference = String::new();
     writeln!(reference)?;
 
-    for name in &command_names {
+    for path in command_paths {
         writeln!(
             reference,
             "- [{}](./reference/{}.md)",
-            name,
-            escape_name(name)
+            path.join(" "),
+            path.join("-")
         )?;
     }