add: ability to "go run" a local package and process the output. This enables using makeclapman in go:generate commands
Note in the README that makeclapman does not require the program using clapman to import claphelp.
change: make command order in generated manpage consistent across runs (thank you sertonix@...!)
A pretty Usage-printer and manpage generator for programs that use the claptrap flags library.
package mytest
require ser1.net/claptrap/v4
require ser1.net/claphelp/v2
For pretty-print usage, in your project:
package main
import "ser1.net/claptrap/v4"
import "ser1.net/claphelp/v2"
func main() {
reg := claptrap.Command("tripl", "Load a file a number of times")
// Set up the flags normally, .Add, AdCommand, etc.
reg.Add("!file", "a file name")
reg.Add("--count", "-c", 3, "times to read the file")
reg.Add("--action...", []string{"bytes", "words", "lines"}, "count the number of something in the file")
// Override the usage and error printing functions
claptrap.Usage = claphelp.PrettyUsage
claptrap.HandleErrors = claphelp.PrettyErrors
// Parse and use Usage as normal, e.g. reg.Parse(nil)
claptrap.Usage()
}
To generate manpages, use the magic environment variable CLAPTRAP_USAGE_JSON
with your program's Usage
and pipe the output through claphelp's cmd/makeclapman
:
Note: you do not need to import claphelp into your project if all you want to do is generate manpages. Base claptrap understands the CLAPTRAP_USAGE_JSON
environment variable. You need to import claphelp only if you want pretty-print help/error messages.
$ go install ser1.net/claphelp/cmd/makeclapman
$ CLAPTRAP_USAGE_JSON=true myprogram | makeclapman
makeclapman
will generate one man page per subcommand in your program; for example:
root := claptrap.AddCommand("myprogram", "This is my program")
help := root.AddCommand("help", "Show my program's usage")
lotto := root.AddCommand("lotto", "Show winning lottery numbers")
will generate:
with "See also" references in all files.
For man pages, an author section can be added with the --author
flag. If --description
is specified, then the command description will be used for the synopsis, and the command-line description will be used for the DESCRIPTION section. A file can also be provided to include arbitrary sections; this file contains:
# SECTION NAME
Any text, included raw. This allows passing through manpage mark-up.
example-additional.txt has a more full example.
makeclapman can be used in a go:generate directive through the --run
argument. For example:
//go:generate go run ser1.net/claphelp/v2/cmd/makeclapman@latest --run "./cmd/myprogram --help"
makeclapman will execute go run ./cmd/myprogram --help
with the CLAPTRAP_USAGE_JSON=true
environment variable and will consume and transform the output into man pages.