Split short summary from full help text

b3sum/Cargo.lock

@@ -105,6 +105,7 @@ dependencies = [
  "once_cell",
  "strsim",
  "termcolor",
+ "terminal_size",
 ]
 
 [[package]]
@@ -219,6 +220,27 @@ version = "1.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "90e5c1c8368803113bf0c9584fc495a58b86dc8a29edbf8fe877d21d9507e797"
 
+[[package]]
+name = "errno"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f639046355ee4f37944e44f60642c6f3a7efa3cf6b78c78a0d989a8ce6c396a1"
+dependencies = [
+ "errno-dragonfly",
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "errno-dragonfly"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa68f1b12764fab894d2755d2518754e71b4fd80ecfb822714a1206c2aab39bf"
+dependencies = [
+ "cc",
+ "libc",
+]
+
 [[package]]
 name = "fastrand"
 version = "1.8.0"
@@ -274,12 +296,24 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "io-lifetimes"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ea37f355c05dde75b84bba2d767906ad522e97cd9e2eef2be7a4ab7fb442c06"
+
 [[package]]
 name = "libc"
 version = "0.2.133"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c0f80d65747a3e43d1596c7c5492d95d5edddaabd45a7fcdb02b95f644164966"
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4d2456c373231a208ad294c33dc5bff30051eafd954cd4caae83a712b12854d"
+
 [[package]]
 name = "memmap2"
 version = "0.5.7"
@@ -414,6 +448,20 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "rustix"
+version = "0.35.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fbb2fda4666def1433b1b05431ab402e42a1084285477222b72d6c564c417cef"
+dependencies = [
+ "bitflags",
+ "errno",
+ "io-lifetimes",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
 [[package]]
 name = "scopeguard"
 version = "1.1.0"
@@ -476,6 +524,16 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "terminal_size"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8440c860cf79def6164e4a0a983bcc2305d82419177a0e0c71930d049e3ac5a1"
+dependencies = [
+ "rustix",
+ "windows-sys",
+]
+
 [[package]]
 name = "typenum"
 version = "1.15.0"
@@ -533,3 +591,46 @@ name = "winapi-x86_64-pc-windows-gnu"
 version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows-sys"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea04155a16a59f9eab786fe12a4a450e75cdb175f9e0d80da1e17db09f55b8d2"
+dependencies = [
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9bb8c3fd39ade2d67e9874ac4f3db21f0d710bee00fe7cab16949ec184eeaa47"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180e6ccf01daf4c426b846dfc66db1fc518f074baa793aa7d9b9aaeffad6a3b6"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2e7917148b2812d1eeafaeb22a97e4813dfa60a3f8f78ebe204bcc88f12f024"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4dcd171b8776c41b97521e5da127a2d86ad280114807d0b2ab1e462bc764d9e1"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.36.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c811ca4a8c853ef420abd8592ba53ddbbac90410fab6903b3e79972a631f7680"

b3sum/Cargo.toml

@@ -16,7 +16,7 @@ pure = ["blake3/pure"]
 [dependencies]
 anyhow = "1.0.25"
 blake3 = { version = "1", path = "..", features = ["rayon"] }
-clap = { version = "4.0.8", features = ["derive"] }
+clap = { version = "4.0.8", features = ["derive", "wrap_help"] }
 hex = "0.4.0"
 memmap2 = "0.5.3"
 rayon = "1.2.1"

b3sum/README.md

@@ -8,31 +8,31 @@ Coreutils tools like `b2sum` or `md5sum`.
 Usage: b3sum [OPTIONS] [FILE]...
 
 Arguments:
-  [FILE]...  Files to hash, or checkfiles to check. When no file is given,
+  [FILE]...  Files to hash, or checkfiles to check
-             or when - is given, read standard input.
 
 Options:
-  -l, --length <LEN>          The number of output bytes, prior to hex
+  -l, --length <LEN>
-                              encoding [default: 32]
+          The number of output bytes, prior to hex encoding [default: 32]
-      --num-threads <NUM>     The maximum number of threads to use. By
+      --num-threads <NUM>
-                              default, this is the number of logical cores.
+          The maximum number of threads to use
-                              If this flag is omitted, or if its value is 0,
+      --keyed
-                              RAYON_NUM_THREADS is also respected.
+          Uses the keyed mode
-      --keyed                 Uses the keyed mode. The secret key is read from standard
+      --derive-key <CONTEXT>
-                              input, and it must be exactly 32 raw bytes.
+          Uses the key derivation mode, with the given context string
-      --derive-key <CONTEXT>  Uses the key derivation mode, with the given
+      --no-mmap
-                              context string. Cannot be used with --keyed.
+          Disables memory mapping
-      --no-mmap               Disables memory mapping. Currently this also disables
+      --no-names
-                              multithreading.
+          Omits filenames in the output
-      --no-names              Omits filenames in the output
+      --raw
-      --raw                   Writes raw output bytes to stdout, rather than hex.
+          Writes raw output bytes to stdout, rather than hex
-                              --no-names is implied. In this case, only a single
+  -c, --check
-                              input is allowed.
+          Reads BLAKE3 sums from the [FILE]s and checks them
-  -c, --check                 Reads BLAKE3 sums from the [FILE]s and checks them
+      --quiet
-      --quiet                 Skips printing OK for each successfully verified file.
+          Skips printing OK for each successfully verified file
-                              Must be used with --check.
+  -h, --help
-  -h, --help                  Print help information
+          Print help information (use `--help` for more detail)
-  -V, --version               Print version information
+  -V, --version
+          Print version information
 ```
 
 See also [this document about how the `--check` flag

b3sum/src/main.rs

@@ -20,17 +20,15 @@ const RAW_ARG: &str = "raw";
 const CHECK_ARG: &str = "check";
 
 #[derive(Parser)]
-#[command(version)]
+#[command(version, max_term_width(80))]
 struct Inner {
-    /// Files to hash, or checkfiles to check. When no file is given,
+    /// Files to hash, or checkfiles to check.
-    /// or when - is given, read standard input.
+    ///
-    #[arg(verbatim_doc_comment)]
+    /// When no file is given, or when - is given, read standard input.
     file: Vec<PathBuf>,
 
-    /// The number of output bytes, prior to hex
+    /// The number of output bytes, prior to hex encoding.
-    /// encoding
     #[arg(
-        verbatim_doc_comment,
         short,
         long,
         default_value_t = blake3::OUT_LEN as u64,
@@ -38,44 +36,43 @@ struct Inner {
     )]
     length: u64,
 
-    /// The maximum number of threads to use. By
+    /// The maximum number of threads to use.
-    /// default, this is the number of logical cores.
+    ///
-    /// If this flag is omitted, or if its value is 0,
+    /// By default, this is the number of logical cores. If this flag is
-    /// RAYON_NUM_THREADS is also respected.
+    /// omitted, or if its value is 0, RAYON_NUM_THREADS is also respected.
-    #[arg(verbatim_doc_comment, long, value_name("NUM"))]
+    #[arg(long, value_name("NUM"))]
     num_threads: Option<usize>,
 
-    /// Uses the keyed mode. The secret key is read from standard
+    /// Uses the keyed mode.
-    /// input, and it must be exactly 32 raw bytes.
+    ///
-    #[arg(verbatim_doc_comment, long, requires("file"))]
+    /// The secret key is read from standard input, and it must be exactly 32
+    /// raw bytes.
+    #[arg(long, requires("file"))]
     keyed: bool,
 
-    /// Uses the key derivation mode, with the given
+    /// Uses the key derivation mode, with the given context string.
-    /// context string. Cannot be used with --keyed.
+    ///
-    #[arg(
+    /// Cannot be used with --keyed.
-        verbatim_doc_comment,
+    #[arg(long, value_name("CONTEXT"), conflicts_with(KEYED_ARG))]
-        long,
-        value_name("CONTEXT"),
-        conflicts_with(KEYED_ARG)
-    )]
     derive_key: Option<String>,
 
-    /// Disables memory mapping. Currently this also disables
+    /// Disables memory mapping.
-    /// multithreading.
+    ///
-    #[arg(verbatim_doc_comment, long)]
+    /// Currently this also disables multithreading.
+    #[arg(long)]
     no_mmap: bool,
 
-    /// Omits filenames in the output
+    /// Omits filenames in the output.
     #[arg(long)]
     no_names: bool,
 
     /// Writes raw output bytes to stdout, rather than hex.
-    /// --no-names is implied. In this case, only a single
+    ///
-    /// input is allowed.
+    /// --no-names is implied. In this case, only a single input is allowed.
-    #[arg(verbatim_doc_comment, long)]
+    #[arg(long)]
     raw: bool,
 
-    /// Reads BLAKE3 sums from the [FILE]s and checks them
+    /// Reads BLAKE3 sums from the [FILE]s and checks them.
     #[arg(
         short,
         long,
@@ -88,8 +85,9 @@ struct Inner {
     check: bool,
 
     /// Skips printing OK for each successfully verified file.
+    ///
     /// Must be used with --check.
-    #[arg(verbatim_doc_comment, long, requires(CHECK_ARG))]
+    #[arg(long, requires(CHECK_ARG))]
     quiet: bool,
 }