From 83a2bff4bb04b0189d17419baf8ca520992d5033 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sun, 23 Nov 2025 15:57:44 -0500 Subject: Added Metadata section for files instead of _HELP and _USAGE --- docs/command-line-parsing.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs') diff --git a/docs/command-line-parsing.md b/docs/command-line-parsing.md index 714e6e9c..92e9a1c9 100644 --- a/docs/command-line-parsing.md +++ b/docs/command-line-parsing.md @@ -223,3 +223,36 @@ OPTIONS --frob | --no-frob Whether or not to frob your gropnoggles ``` + +## Metadata + +You can specify metadata for a program, which is used for CLI messages like +`--help`, as well as manpage documentation. Metadata can be specified as either +a text literal (no interpolation) or as a file path literal. + +``` +USAGE: "--foo " +HELP: " + This is some custom help text. + You can use these flags: + + --foo The foo parameter + --help Show this message +" +MANPAGE_DESCRIPTION: (./description.roff) +``` + +Supported metadata: + +- `USAGE`: the short form usage shown in CLI parsing errors and help pages. This + should be a single line without the name of the program, so `USAGE: "--foo"` + would translate to the error message `Usage: myprogram --foo`. If this is not + present, it will be generated automatically. + +- `HELP`: The help message displayed when the `--help` flag is used or when there + is an argument parsing error. This should be a description of the program with + a multi-line documentation of commonly used flags. + +- `MANPAGE_SYNOPSYS`: the synopsis section of the manpage (inserted literally). + +- `MANPAGE_DESCRIPTION`: the description section of the manpage (inserted literally). -- cgit v1.2.3