From 8a239596a9e23c6f23ea3d9c064fc49674ed876b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= <mitr@redhat.com>
Date: Tue, 9 Aug 2016 00:38:10 +0200
Subject: [PATCH] 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    |  8 +++++---
 cmd/skopeo/delete.go  |  7 ++++---
 cmd/skopeo/inspect.go |  5 +++--
 cmd/skopeo/layers.go  |  5 +++--
 cmd/skopeo/main.go    | 14 +++++---------
 cmd/skopeo/signing.go | 16 +++++++++-------
 6 files changed, 29 insertions(+), 26 deletions(-)

diff --git a/cmd/skopeo/copy.go b/cmd/skopeo/copy.go
index 6af7ff86..14e3577a 100644
--- a/cmd/skopeo/copy.go
+++ b/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`",
 		},
 	},
 }
diff --git a/cmd/skopeo/delete.go b/cmd/skopeo/delete.go
index 552b62ba..8e57b832 100644
--- a/cmd/skopeo/delete.go
+++ b/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,
 }
diff --git a/cmd/skopeo/inspect.go b/cmd/skopeo/inspect.go
index 4e8376aa..6414a178 100644
--- a/cmd/skopeo/inspect.go
+++ b/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",
diff --git a/cmd/skopeo/layers.go b/cmd/skopeo/layers.go
index 313d3558..6b38b09d 100644
--- a/cmd/skopeo/layers.go
+++ b/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 {
diff --git a/cmd/skopeo/main.go b/cmd/skopeo/main.go
index afffd63e..f660eec6 100644
--- a/cmd/skopeo/main.go
+++ b/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 {
diff --git a/cmd/skopeo/signing.go b/cmd/skopeo/signing.go
index 0d45912d..aa097d1a 100644
--- a/cmd/skopeo/signing.go
+++ b/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,
 }