v6.4.0: XDG config layers and terminal-aware help wrapping

This release adds XDG-based config file resolution, teaches --help to wrap to the terminal width with a smarter column layout, fixes zsh completions at mid-line cursor positions, and slims down the library's dependency tree with an independent Markdown feature.

Added

• XDG file layers for config resolution. FileLayer::xdg(XdgBase, path) resolves a relative path under the standard XDG config, data, state, cache, or runtime bases, honoring each base's defaults, absolute-path rules, and precedence with no new dependencies. Config and data bases include system search directories (with the user file winning), while state, cache, and runtime stay user-scoped. The Config derive gains matching #[usage(file(path = "…", xdg = "config"))] metadata that expands into the standard precedence chain in the emitted spec (#1303, @jdx).

  use usage::config::{FileLayer, XdgBase};
  
  // Reads $XDG_CONFIG_HOME then $XDG_CONFIG_DIRS in precedence order,
  // falling back to $HOME/.config and /etc/xdg when unset.
  let layer = FileLayer::xdg(XdgBase::Config, "ex/config.toml");

Fixed

• Terminal help now wraps to the terminal width. Help output uses a hybrid column layout: long option spellings keep their description inline when at least 30 columns remain, otherwise the prose stacks under the shared description column. Paragraphs, section intros, annotations, bullet and numbered lists (with hanging indents), and labelled notes/warnings all wrap, while blank lines and preformatted (4-space/tab-indented) lines are preserved. The Rust reference renderer, the dependency-free usage-argv renderer, and the generated Go renderer stay in parity (#1304, @jdx).
• zsh completions respect the cursor position. Generated zsh scripts now forward zsh's one-based CURRENT to complete-word as a zero-based --cword, so completing a word in the middle of a command line (for example --f before a trailing argument) resolves against the correct word instead of the last one (#1300, @jdx, fixes #1298).

Changed

• Independent markdown and manpage doc features. Markdown and manpage rendering are now separate features so consumers who only generate Markdown can drop the roff dependency. The existing docs and roff feature names remain as aliases. Internally, heck, shell-words, and strum were replaced with focused in-tree implementations and unicode-width was bumped to 0.2, shrinking the dependency footprint while keeping the public API and error variants stable (#1301, @jdx).

  usage-lib = { version = "6", default-features = false, features = ["markdown"] }

Full Changelog: v6.3.0...v6.4.0

💚 Sponsor usage

usage is maintained by @jdx, an open source developer for entire.io, the title sponsor of the jdx.dev open source tools including mise, aube, hk, and more. Work on usage is funded by sponsorships.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider sponsoring at jdx.dev. Every sponsorship helps the project stay independent and moving.