fix markdown generation

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:

cmd/wand/readme.md

@@ -0,0 +1,205 @@
+# wand
+
+## Synopsis:
+
+```
+wand [options]... [--] [args string]...
+wand <subcommand>
+```
+
+## 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: \<module-path\>=\<replacement-module-path\>, 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 \<command\> help or \<command\> --help.
+
+### wand docreflect
+
+#### Synopsis:
+
+```
+wand docreflect [options]... [--] <packageName string> [gopaths string]...
+wand docreflect <subcommand>
+```
+
+#### 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]... [--] <commandDir string>
+wand manpages <subcommand>
+```
+
+#### 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]... [--] <commandDir string>
+wand markdown <subcommand>
+```
+
+#### 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 <subcommand>
+```
+
+#### 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: \<module-path\>=\<replacement-module-path\>, 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
+```