Improve --help output

- Use ArgsUsage to document the non-option arguments
- Refer to ArgsUsage placeholders in Usage
- Use named placeholders in flag documentation

Fixes #137, more or less.

cmd/skopeo/copy.go

@@ -162,13 +162,15 @@ func copyHandler(context *cli.Context) error {
 }
 
 var copyCmd = cli.Command{
-	Name:   "copy",
-	Action: copyHandler,
+	Name:      "copy",
+	Usage:     "Copy an image from one location to another",
+	ArgsUsage: "SOURCE-IMAGE DESTINATION-IMAGE",
+	Action:    copyHandler,
 	// FIXME: Do we need to namespace the GPG aspect?
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  "sign-by",
-			Usage: "sign the image using a GPG key with the specified fingerprint",
+			Usage: "Sign the image using a GPG key with the specified `FINGERPRINT`",
 		},
 	},
 }

cmd/skopeo/delete.go

@@ -23,7 +23,8 @@ func deleteHandler(context *cli.Context) error {
 }
 
 var deleteCmd = cli.Command{
-	Name:   "delete",
-	Usage:  "Delete given image",
-	Action: deleteHandler,
+	Name:      "delete",
+	Usage:     "Delete image IMAGE-NAME",
+	ArgsUsage: "IMAGE-NAME",
+	Action:    deleteHandler,
 }

cmd/skopeo/inspect.go

@@ -25,8 +25,9 @@ type inspectOutput struct {
 }
 
 var inspectCmd = cli.Command{
-	Name:  "inspect",
-	Usage: "inspect images on a registry",
+	Name:      "inspect",
+	Usage:     "Inspect image IMAGE-NAME",
+	ArgsUsage: "IMAGE-NAME",
 	Flags: []cli.Flag{
 		cli.BoolFlag{
 			Name:  "raw",

cmd/skopeo/layers.go

@@ -12,8 +12,9 @@ import (
 
 // TODO(runcom): document args and usage
 var layersCmd = cli.Command{
-	Name:  "layers",
-	Usage: "get images layers",
+	Name:      "layers",
+	Usage:     "Get layers of IMAGE-NAME",
+	ArgsUsage: "IMAGE-NAME",
 	Action: func(c *cli.Context) error {
 		rawSource, err := parseImageSource(c, c.Args()[0])
 		if err != nil {

cmd/skopeo/main.go

@@ -13,10 +13,6 @@ import (
 // and will be populated by the Makefile
 var gitCommit = ""
 
-const (
-	usage = `interact with registries`
-)
-
 // createApp returns a cli.App to be run or tested.
 func createApp() *cli.App {
 	app := cli.NewApp()
@@ -26,7 +22,7 @@ func createApp() *cli.App {
 	} else {
 		app.Version = version.Version
 	}
-	app.Usage = usage
+	app.Usage = "Various operations with container images and container image registries"
 	// TODO(runcom)
 	//app.EnableBashCompletion = true
 	app.Flags = []cli.Flag{
@@ -37,21 +33,21 @@ func createApp() *cli.App {
 		cli.StringFlag{
 			Name:  "username",
 			Value: "",
-			Usage: "registry username",
+			Usage: "use `USERNAME` for accessing the registry",
 		},
 		cli.StringFlag{
 			Name:  "password",
 			Value: "",
-			Usage: "registry password",
+			Usage: "use `PASSWORD` for accessing the registry",
 		},
 		cli.StringFlag{
 			Name:  "cert-path",
 			Value: "",
-			Usage: "Certificates path to connect to the given registry (cert.pem, key.pem)",
+			Usage: "use certificates at `PATH` (cert.pem, key.pem) to connect to the registry",
 		},
 		cli.BoolFlag{
 			Name:  "tls-verify",
-			Usage: "Whether to verify certificates or not",
+			Usage: "verify certificates",
 		},
 	}
 	app.Before = func(c *cli.Context) error {

cmd/skopeo/signing.go

@@ -39,13 +39,14 @@ func standaloneSign(context *cli.Context) error {
 }
 
 var standaloneSignCmd = cli.Command{
-	Name:   "standalone-sign",
-	Usage:  "Create a signature using local files",
-	Action: standaloneSign,
+	Name:      "standalone-sign",
+	Usage:     "Create a signature using local files",
+	ArgsUsage: "MANIFEST DOCKER-REFERENCE KEY-FINGERPRINT",
+	Action:    standaloneSign,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  "output, o",
-			Usage: "output signature file name",
+			Usage: "output the signature to `SIGNATURE`",
 		},
 	},
 }
@@ -82,7 +83,8 @@ func standaloneVerify(context *cli.Context) error {
 }
 
 var standaloneVerifyCmd = cli.Command{
-	Name:   "standalone-verify",
-	Usage:  "Verify a signature using local files",
-	Action: standaloneVerify,
+	Name:      "standalone-verify",
+	Usage:     "Verify a signature using local files",
+	ArgsUsage: "MANIFEST DOCKER-REFERENCE KEY-FINGERPRINT SIGNATURE",
+	Action:    standaloneVerify,
 }