docs: cli usage

Cargo.toml

@@ -42,6 +42,11 @@ name = "pdu-completions"
 path = "cli/completions.rs"
 required-features = ["cli-completions"]
 
+[[bin]]
+name = "pdu-usage-md"
+path = "cli/usage_md.rs"
+required-features = ["cli"]
+
 [features]
 default = ["cli"]
 json = ["serde/derive", "serde_json"]

README.md

@@ -64,6 +64,10 @@ The benchmark was generated by [a GitHub Workflow](https://github.com/KSXGitHub/
 * Do not differentiate filesystem: Mounted folders are counted as normal folders.
 * The runtime is optimized at the expense of binary size.
 
+## Usage
+
+See [USAGE.md](./USAGE.md) for the full help text.
+
 ## Development
 
 ### Prerequisites

USAGE.md

@@ -0,0 +1,105 @@
+# Usage
+
+```sh
+pdu [OPTIONS] [FILES]...
+```
+
+## Arguments
+
+* `[FILES]...`: List of files and/or directories
+
+## Options
+
+* `--json-input`: Read JSON data from stdin
+* `--json-output`: Print JSON data instead of an ASCII chart
+* `-b <BYTES_FORMAT>`, `--bytes-format <BYTES_FORMAT>`: How to display the numbers of bytes (default: `metric`)
+  * `plain`: Display plain number of bytes without units
+  * `metric`: Use metric scale, i.e. 1K = 1000B, 1M = 1000K, and so on
+  * `binary`: Use binary scale, i.e. 1K = 1024B, 1M = 1024K, and so on
+* `-H`, `--deduplicate-hardlinks`, `--detect-links`, `--dedupe-links`: Detect and subtract the sizes of hardlinks from their parent directory totals
+* `--top-down`: Print the tree top-down instead of bottom-up
+* `--align-right`: Set the root of the bars to the right
+* `-q <QUANTITY>`, `--quantity <QUANTITY>`: Aspect of the files/directories to be measured (default: `block-size`)
+  * `apparent-size`: Measure apparent sizes
+  * `block-size`: Measure block sizes (block-count * 512B)
+  * `block-count`: Count numbers of blocks
+* `-d <MAX_DEPTH>`, `--max-depth <MAX_DEPTH>`, `--depth <MAX_DEPTH>`: Maximum depth to display the data. Could be either "inf" or a positive integer (default: `10`)
+* `-w <TOTAL_WIDTH>`, `--total-width <TOTAL_WIDTH>`, `--width <TOTAL_WIDTH>`: Width of the visualization
+* `--column-width <TREE_WIDTH> <BAR_WIDTH>`: Maximum widths of the tree column and width of the bar column
+* `-m <MIN_RATIO>`, `--min-ratio <MIN_RATIO>`: Minimal size proportion required to appear (default: `0.01`)
+* `--no-sort`: Do not sort the branches in the tree
+* `-s`, `--silent-errors`, `--no-errors`: Prevent filesystem error messages from appearing in stderr
+* `-p`, `--progress`: Report progress being made at the expense of performance
+* `--threads <THREADS>`: Set the maximum number of threads to spawn. Could be either "auto", "max", or a positive integer (default: `auto`)
+* `--omit-json-shared-details`: Do not output `.shared.details` in the JSON output
+* `--omit-json-shared-summary`: Do not output `.shared.summary` in the JSON output
+* `-h`, `--help`: Print help (see a summary with '-h')
+* `-V`, `--version`: Print version
+
+## Examples
+
+### Show disk usage chart of current working directory
+
+```sh
+pdu
+```
+
+### Show disk usage chart of a single file or directory
+
+```sh
+pdu path/to/file/or/directory
+```
+
+### Compare disk usages of multiple files and/or directories
+
+```sh
+pdu file.txt dir/
+```
+
+### Show chart in apparent sizes instead of block sizes
+
+```sh
+pdu --quantity=apparent-size
+```
+
+### Detect and subtract the sizes of hardlinks from their parent nodes
+
+```sh
+pdu --deduplicate-hardlinks
+```
+
+### Show sizes in plain numbers instead of metric units
+
+```sh
+pdu --bytes-format=plain
+```
+
+### Show sizes in base 2¹⁰ units (binary) instead of base 10³ units (metric)
+
+```sh
+pdu --bytes-format=binary
+```
+
+### Show disk usage chart of all entries regardless of size
+
+```sh
+pdu --min-ratio=0
+```
+
+### Only show disk usage chart of entries whose size is at least 5% of total
+
+```sh
+pdu --min-ratio=0.05
+```
+
+### Show disk usage data as JSON instead of chart
+
+```sh
+pdu --min-ratio=0 --max-depth=inf --json-output | jq
+```
+
+### Visualize existing JSON representation of disk usage data
+
+```sh
+pdu --json-input < disk-usage.json
+```

cli/usage_md.rs

@@ -0,0 +1,226 @@
+fn main() {
+    let help = include_str!("../exports/long.help");
+    println!("{}", render(help).trim_end());
+}
+
+fn render(input: &str) -> String {
+    let mut out = String::new();
+    let lines: Vec<&str> = input.lines().collect();
+
+    let section_positions: Vec<usize> = lines
+        .iter()
+        .enumerate()
+        .filter(|(_, l)| is_section_header(l))
+        .map(|(i, _)| i)
+        .collect();
+
+    let first_section = section_positions.first().copied().unwrap_or(lines.len());
+    render_preamble(&lines[..first_section], &mut out);
+
+    for (idx, &start) in section_positions.iter().enumerate() {
+        let end = section_positions
+            .get(idx + 1)
+            .copied()
+            .unwrap_or(lines.len());
+        let name = lines[start].strip_suffix(':').unwrap_or(lines[start]);
+        render_section(name, &lines[start + 1..end], &mut out);
+    }
+
+    out
+}
+
+/// A top-level section header is a single unindented word followed by `:`
+/// (e.g. `Arguments:`, `Options:`, `Examples:`).
+/// Lines like `Usage: pdu …` or `Copyright: …` do not qualify because they
+/// either contain spaces before `:` content or have trailing content.
+fn is_section_header(line: &str) -> bool {
+    !line.starts_with(' ')
+        && line
+            .strip_suffix(':')
+            .is_some_and(|s| !s.is_empty() && s.chars().all(|c| c.is_alphabetic()))
+}
+
+fn render_preamble(lines: &[&str], out: &mut String) {
+    for line in lines {
+        if let Some(rest) = line.strip_prefix("Usage: ") {
+            out.push_str("# Usage\n\n```sh\n");
+            out.push_str(rest);
+            out.push_str("\n```\n\n");
+        }
+    }
+}
+
+fn render_section(name: &str, lines: &[&str], out: &mut String) {
+    out.push_str(&format!("## {name}\n\n"));
+    match name {
+        "Arguments" | "Options" => render_flag_section(lines, out),
+        "Examples" => render_examples_section(lines, out),
+        _ => {}
+    }
+}
+
+fn render_flag_section(lines: &[&str], out: &mut String) {
+    // Flag / argument names are indented 2–6 spaces; descriptions are indented 10+.
+    let item_starts: Vec<usize> = lines
+        .iter()
+        .enumerate()
+        .filter(|(_, l)| {
+            let trimmed = l.trim_start();
+            if trimmed.is_empty() {
+                return false;
+            }
+            let indent = l.len() - trimmed.len();
+            (2..=6).contains(&indent)
+        })
+        .map(|(i, _)| i)
+        .collect();
+
+    for (idx, &start) in item_starts.iter().enumerate() {
+        let end = item_starts.get(idx + 1).copied().unwrap_or(lines.len());
+        render_flag_item(&lines[start..end], out);
+    }
+    out.push('\n');
+}
+
+/// Format a flag line and its aliases as a comma-separated list of backtick-quoted names.
+///
+/// For example, `-b, --bytes-format <BYTES_FORMAT>` with no aliases becomes
+/// `` `-b <BYTES_FORMAT>`, `--bytes-format <BYTES_FORMAT>` ``.
+///
+/// For `-H, --deduplicate-hardlinks` with aliases `--detect-links, --dedupe-links` the
+/// result is `` `-H`, `--deduplicate-hardlinks`, `--detect-links`, `--dedupe-links` ``.
+fn format_flag_names(flag_line: &str, aliases: Option<&str>) -> String {
+    let parts: Vec<&str> = flag_line.split(", ").collect();
+
+    // Extract the value placeholder suffix from the last part (e.g. " <BYTES_FORMAT>").
+    let value_suffix = parts
+        .last()
+        .and_then(|p| p.find(' ').map(|i| &p[i..]))
+        .unwrap_or("");
+
+    let mut names: Vec<String> = parts
+        .iter()
+        .enumerate()
+        .map(|(i, part)| {
+            if i < parts.len() - 1 && !value_suffix.is_empty() {
+                format!("{part}{value_suffix}")
+            } else {
+                part.to_string()
+            }
+        })
+        .collect();
+
+    if let Some(a) = aliases {
+        for alias in a.split(", ") {
+            if value_suffix.is_empty() {
+                names.push(alias.to_string());
+            } else {
+                names.push(format!("{alias}{value_suffix}"));
+            }
+        }
+    }
+
+    names
+        .iter()
+        .map(|n| format!("`{n}`"))
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+fn render_flag_item(lines: &[&str], out: &mut String) {
+    if lines.is_empty() {
+        return;
+    }
+    let flag = lines[0].trim();
+
+    let mut desc_parts: Vec<&str> = Vec::new();
+    let mut possible_values: Vec<(&str, &str)> = Vec::new();
+    let mut default_value: Option<&str> = None;
+    let mut aliases_value: Option<&str> = None;
+    let mut in_possible_values = false;
+
+    for line in &lines[1..] {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            in_possible_values = false;
+            continue;
+        }
+        if trimmed == "Possible values:" {
+            in_possible_values = true;
+            continue;
+        }
+        if let Some(inner) = trimmed
+            .strip_prefix("[default: ")
+            .and_then(|s| s.strip_suffix(']'))
+        {
+            default_value = Some(inner);
+            continue;
+        }
+        if let Some(inner) = trimmed
+            .strip_prefix("[aliases: ")
+            .and_then(|s| s.strip_suffix(']'))
+        {
+            aliases_value = Some(inner);
+            continue;
+        }
+        if in_possible_values {
+            if let Some(entry) = trimmed.strip_prefix("- ") {
+                let (name, desc) = if let Some(colon) = entry.find(':') {
+                    (entry[..colon].trim(), entry[colon + 1..].trim())
+                } else {
+                    (entry.trim(), "")
+                };
+                possible_values.push((name, desc));
+            }
+            continue;
+        }
+        desc_parts.push(trimmed);
+    }
+
+    let names = format_flag_names(flag, aliases_value);
+    let description = desc_parts.join(" ");
+    out.push_str(&format!("* {names}: {description}"));
+    if let Some(d) = default_value {
+        out.push_str(&format!(" (default: `{d}`)"));
+    }
+    out.push('\n');
+
+    for (name, desc) in &possible_values {
+        if desc.is_empty() {
+            out.push_str(&format!("  * `{name}`\n"));
+        } else {
+            out.push_str(&format!("  * `{name}`: {desc}\n"));
+        }
+    }
+}
+
+fn render_examples_section(lines: &[&str], out: &mut String) {
+    let mut i = 0;
+    while i < lines.len() {
+        let trimmed = lines[i].trim();
+        if trimmed.is_empty() {
+            i += 1;
+            continue;
+        }
+        // A line starting with `$ ` is a bare command (no preceding description).
+        if let Some(cmd) = trimmed.strip_prefix("$ ") {
+            out.push_str(&format!("### `{cmd}`\n\n```sh\n{cmd}\n```\n\n"));
+            i += 1;
+        } else {
+            // Description line — the very next non-empty line should be `$ <cmd>`.
+            let desc = trimmed;
+            i += 1;
+            while i < lines.len() && lines[i].trim().is_empty() {
+                i += 1;
+            }
+            if i < lines.len() {
+                if let Some(cmd) = lines[i].trim().strip_prefix("$ ") {
+                    out.push_str(&format!("### {desc}\n\n```sh\n{cmd}\n```\n\n"));
+                    i += 1;
+                    continue;
+                }
+            }
+            out.push_str(&format!("### {desc}\n\n"));
+        }
+    }
+}