From dd6be747c6ec0ee68c4af4cef29282ae4fd570cc Mon Sep 17 00:00:00 2001 From: Arpad Ryszka Date: Wed, 7 Jan 2026 18:45:58 +0100 Subject: [PATCH] fix markdown generation --- Makefile | 2 +- cmd/wand/readme.md | 205 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5d52e4e..cbdc9a3 100644 --- a/Makefile +++ b/Makefile @@ -56,7 +56,7 @@ docreflect_test.go: $(sources) .build/wand.1: $(sources) iniparser.gen.go docreflect.gen.go .build go run script/man/man.go $(date) $(version) ./cmd/wand > .build/wand.1 -cmd/wand/readme.md: +cmd/wand/readme.md: $(sources) docreflect.gen.go go run script/markdown/md.go 0 ./cmd/wand > cmd/wand/readme.md $(prefix)/bin: diff --git a/cmd/wand/readme.md b/cmd/wand/readme.md index e69de29..b85955a 100644 --- a/cmd/wand/readme.md +++ b/cmd/wand/readme.md @@ -0,0 +1,205 @@ +# wand + +## Synopsis: + +``` +wand [options]... [--] [args string]... +wand +``` + +## Description: + +Exec executes a Go function expression parameterized by the subsequent command line arguments. + +It has two modes. When called with arguments, the first argument must be the function expression, and the rest +of the arguments the command line flags and positional arguments. When no arguments are provided, it starts +reading from the input, and considers every line as the expected function expression followed by the options and +positional arguments. In the latter case, the escaping is mostly identical to that of the bash input. It keeps +executing the input expressions until the input is closed (Ctrl+D). + +## Options: + +- --cache-dir, -d string: CacheDir specifies a custom cache dir for wand. Default: ~/.wand. +- --clear-cache, -c bool: ClearCache clears the cached artifacts resulting from a previous execution before the + current execution. +- --import string \[\*\]: Import lists the packages required for the expression to be executed. It accepts + versioned package specifications, or it uses the latest version. When a package spec is prefixed with alias= + or .=, it will import the for the expression with the specified alias or inline. +- --no-cache, -f bool: NoCache causes the execution to avoid relying on the cached artifacts resulting from a + previous execution. +- --replace-module string \[\*\]: ReplaceModule replaces imported go modules with local or other versions of the + given modules. The format of the items is: \=\, like for the go mod edit + -replace command. +- --help: Show help. + +Hints: + +- Options marked with \[\*\] accept any number of instances. +- Bool options can be used with implicit true values. +- The short form of bool options can be combined. The last short form does not need to be a bool option. E.g. + -abc=42. +- Option values can be set both via = or just separated by space. + +## Subcommands: + +Show help for each subcommand by calling \ help or \ --help. + +### wand docreflect + +#### Synopsis: + +``` +wand docreflect [options]... [--] [gopaths string]... +wand docreflect +``` + +#### Description: + +Docreflect generates documentation from the go docs of a package to be included in the compiled binary and +accessed by the automatic help and documentation generator. + +The packageName parameter specifies the package name for the generated Go code. + +The gopath arguments accept any number of package, package level symbol, or struct field paths. It is +recommended to use package paths unless special circumstances. + +#### Options: + +- --help: Show help. + +### wand manpages + +#### Synopsis: + +``` +wand manpages [options]... [--] +wand manpages +``` + +#### Description: + +Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries +extracted by Docreflect. + +#### Options: + +- --date-string string: DateString provides the value for the release date field in a man page. +- --version string: Version provides the value for the release version field in a man page. +- --help: Show help. + +### wand markdown + +#### Synopsis: + +``` +wand markdown [options]... [--] +wand markdown +``` + +#### Description: + +Man generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by +Docreflect. + +#### Options: + +- --level int: Level provides a default title level offset for the titles in a markdown document. +- --help: Show help. + +### wand exec (default) + +#### Synopsis: + +``` +wand exec [options]... [--] [args string]... +wand exec +``` + +#### Description: + +Exec executes a Go function expression parameterized by the subsequent command line arguments. + +It has two modes. When called with arguments, the first argument must be the function expression, and the rest +of the arguments the command line flags and positional arguments. When no arguments are provided, it starts +reading from the input, and considers every line as the expected function expression followed by the options and +positional arguments. In the latter case, the escaping is mostly identical to that of the bash input. It keeps +executing the input expressions until the input is closed (Ctrl+D). + +#### Options: + +- --cache-dir, -d string: CacheDir specifies a custom cache dir for wand. Default: ~/.wand. +- --clear-cache, -c bool: ClearCache clears the cached artifacts resulting from a previous execution before the + current execution. +- --import string \[\*\]: Import lists the packages required for the expression to be executed. It accepts + versioned package specifications, or it uses the latest version. When a package spec is prefixed with alias= + or .=, it will import the for the expression with the specified alias or inline. +- --no-cache, -f bool: NoCache causes the execution to avoid relying on the cached artifacts resulting from a + previous execution. +- --replace-module string \[\*\]: ReplaceModule replaces imported go modules with local or other versions of the + given modules. The format of the items is: \=\, like for the go mod edit + -replace command. +- --help: Show help. + +### wand version + +Show version. + +## Environment variables: + +Every command line option's value can also be provided as an environment variable. Environment variable names +need to use snake casing like myapp\_foo\_bar\_baz or MYAPP\_FOO\_BAR\_BAZ, or other casing that doesn't include the +'-' dash character, and they need to be prefixed with the name of the application, as in the base name of the +command. + +When both the environment variable and the command line option is defined, the command line option overrides the +environment variable. Multiple values for the same environment variable can be defined by concatenating the +values with the ':' separator character. When overriding multiple values with command line options, all the +environment values of the same field are dropped. + +### Example environment variable: + +``` +WAND_DATE_STRING=42 +``` + +## Configuration: + +Every command line option's value can also be provided as an entry in a configuration file. + +Configuration file entries can use keys with different casings, e.g. snake case foo\_bar\_baz, or kebab case +foo-bar-baz. The keys of the entries can use a limited set of characters: \[a-zA-Z0-9\_-\], and the first character +needs to be one of \[a-zA-Z\_\]. Entry values can consist of any characters, except for newline, control +characters, " (quote) and \\ (backslash), or the values can be quoted, in which case they can consist of any +characters, spanning multiple lines, and only the " (quote) and \\ (backslash) characters need to be escaped by +the \\ (backslash) character. + +Configuration files allow multiple entries with the same key, when if the associated command line option also +allows multiple instances (marked with \[\*\]). When an entry is defined multiple configuration files, the +effective value is overridden in the order of the definition of the possible config files (see the listing order +below). To discard values defined in the overridden config files without defining new ones, we can set entries +with only the key, omitting the = key/value separator. Entries in the config files are overridden by the +environment variables, when defined, and by the command line options when defined. + +Config files marked as optional don't need to be present in the file system, but if they exist, then they must +contain valid configuration syntax which is wand's flavor of .ini files +(https://code.squareroundforest.org/arpio/wand/src/branch/main/ini.treerack). + +### Configuration files: + +- /etc/wand/config (optional) +- /Users/arpio/.wand/config (optional) +- /Users/arpio/.config/wand/config (optional) + +### Example configuration entry: + +``` +# Default value for --date-string: +date_string = 42 +``` + +### Example for discarding an inherited entry: + +``` +# Discarding an inherited entry: +date_string +```