Fix md generation for kubectl docs

Display usage string, not long help, as code, remove angle brackets from
output (.md interprets as tags and hides).

pkg/kubectl/cmd/config/config.go

@@ -40,7 +40,7 @@ func NewCmdConfig(out io.Writer) *cobra.Command {
 	pathOptions := &pathOptions{}
 
 	cmd := &cobra.Command{
-		Use:   "config <subcommand>",
+		Use:   "config SUBCOMMAND",
 		Short: "config modifies .kubeconfig files",
 		Long:  `config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"`,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/config/create_authinfo.go

@@ -42,19 +42,8 @@ type createAuthInfoOptions struct {
 	embedCertData     util.BoolFlag
 }
 
-func NewCmdConfigSetAuthInfo(out io.Writer, pathOptions *pathOptions) *cobra.Command {
-	options := &createAuthInfoOptions{pathOptions: pathOptions}
-
-	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("set-credentials name [--%v=authfile] [--%v=certfile] [--%v=keyfile] [--%v=bearer_token] [--%v=basic_user] [--%v=basic_password]", clientcmd.FlagAuthPath, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword),
-		Short: "Sets a user entry in .kubeconfig",
-		Long: fmt.Sprintf(`Sets a user entry in .kubeconfig
-
-  Specifying a name that already exists will merge new fields on top of existing
-  values. For example, the following only sets the "client-key" field on the 
-  "cluster-admin" entry, without touching other values:
-
-    set-credentials cluster-admin --client-key=~/.kube/admin.key
+var create_authinfo_long = fmt.Sprintf(`Sets a user entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values.
 
   Client-certificate flags:
     --%v=certfile --%v=keyfile
@@ -66,7 +55,26 @@ func NewCmdConfigSetAuthInfo(out io.Writer, pathOptions *pathOptions) *cobra.Com
     --%v=basic_user --%v=basic_password
 
   Bearer token and basic auth are mutually exclusive.
-`, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword),
+`, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword)
+
+const create_authinfo_example = `// Set only the "client-key" field on the "cluster-admin"
+// entry, without touching other values:
+$ kubectl set-credentials cluster-admin --client-key=~/.kube/admin.key
+
+// Set basic auth for the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --username=admin --password=uXFGweU9l35qcif
+
+// Embed client certificate data in the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --client-certificate=~/.kube/admin.crt --embed-certs=true`
+
+func NewCmdConfigSetAuthInfo(out io.Writer, pathOptions *pathOptions) *cobra.Command {
+	options := &createAuthInfoOptions{pathOptions: pathOptions}
+
+	cmd := &cobra.Command{
+		Use:     fmt.Sprintf("set-credentials NAME [--%v=/path/to/authfile] [--%v=path/to/certfile] [--%v=path/to/keyfile] [--%v=bearer_token] [--%v=basic_user] [--%v=basic_password]", clientcmd.FlagAuthPath, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword),
+		Short:   "Sets a user entry in .kubeconfig",
+		Long:    create_authinfo_long,
+		Example: create_authinfo_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return

pkg/kubectl/cmd/config/create_cluster.go

@@ -39,18 +39,27 @@ type createClusterOptions struct {
 	embedCAData           util.BoolFlag
 }
 
+const (
+	create_cluster_long = `Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.`
+	create_cluster_example = `// Set only the server field on the e2e cluster entry without touching other values.
+$ kubectl config set-cluster e2e --server=https://1.2.3.4
+
+// Embed certificate authority data for the e2e cluster entry
+$ kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/kubernetes.ca.crt
+
+// Disable cert checking for the dev cluster entry
+$ kubectl config set-cluster e2e --insecure-skip-tls-verify=true`
+)
+
 func NewCmdConfigSetCluster(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &createClusterOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("set-cluster name [--%v=server] [--%v=path/to/certficate/authority] [--%v=apiversion] [--%v=true]", clientcmd.FlagAPIServer, clientcmd.FlagCAFile, clientcmd.FlagAPIVersion, clientcmd.FlagInsecure),
-		Short: "Sets a cluster entry in .kubeconfig",
-		Long: `Sets a cluster entry in .kubeconfig
-	Specifying a name that already exists will merge new fields on top of existing values for those fields.
-	e.g.
-		kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/.kubernetes.ca.cert
-		only sets the certificate-authority field on the e2e cluster entry without touching other values.
-		`,
+		Use:     fmt.Sprintf("set-cluster NAME [--%v=server] [--%v=path/to/certficate/authority] [--%v=apiversion] [--%v=true]", clientcmd.FlagAPIServer, clientcmd.FlagCAFile, clientcmd.FlagAPIVersion, clientcmd.FlagInsecure),
+		Short:   "Sets a cluster entry in .kubeconfig",
+		Long:    create_cluster_long,
+		Example: create_cluster_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return

pkg/kubectl/cmd/config/create_context.go

@@ -36,18 +36,21 @@ type createContextOptions struct {
 	namespace   util.StringFlag
 }
 
+const (
+	create_context_long = `Sets a context entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values for those fields.`
+	create_context_example = `// Set the user field on the gce context entry without touching other values
+$ kubectl config set-context gce --user=cluster-admin`
+)
+
 func NewCmdConfigSetContext(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &createContextOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("set-context name [--%v=cluster-nickname] [--%v=user-nickname] [--%v=namespace]", clientcmd.FlagClusterName, clientcmd.FlagAuthInfoName, clientcmd.FlagNamespace),
-		Short: "Sets a context entry in .kubeconfig",
-		Long: `Sets a context entry in .kubeconfig
-	Specifying a name that already exists will merge new fields on top of existing values for those fields.
-	e.g. 
-		kubectl config set-context gce --user=cluster-admin
-		only sets the user field on the gce context entry without touching other values.`,
-
+		Use:     fmt.Sprintf("set-context NAME [--%v=cluster_nickname] [--%v=user_nickname] [--%v=namespace]", clientcmd.FlagClusterName, clientcmd.FlagAuthInfoName, clientcmd.FlagNamespace),
+		Short:   "Sets a context entry in .kubeconfig",
+		Long:    create_context_long,
+		Example: create_context_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return

pkg/kubectl/cmd/config/set.go

@@ -39,18 +39,17 @@ type setOptions struct {
 	propertyValue string
 }
 
+const set_long = `Sets an individual value in a .kubeconfig file
+PROPERTY_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
+PROPERTY_VALUE is the new value you wish to set.`
+
 func NewCmdConfigSet(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &setOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "set property-name property-value",
+		Use:   "set PROPERTY_NAME PROPERTY_VALUE",
 		Short: "Sets an individual value in a .kubeconfig file",
-		Long: `Sets an individual value in a .kubeconfig file
-
-		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-		property-value is the new value you wish to set.
-
-		`,
+		Long:  set_long,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return

pkg/kubectl/cmd/config/unset.go

@@ -32,16 +32,16 @@ type unsetOptions struct {
 	propertyName string
 }
 
+const unset_long = `Unsets an individual value in a .kubeconfig file
+PROPERTY_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.`
+
 func NewCmdConfigUnset(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &unsetOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "unset property-name",
+		Use:   "unset PROPERTY_NAME",
 		Short: "Unsets an individual value in a .kubeconfig file",
-		Long: `Unsets an individual value in a .kubeconfig file
-
-		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-		`,
+		Long:  unset_long,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return

pkg/kubectl/cmd/config/use_context.go

@@ -35,7 +35,7 @@ func NewCmdConfigUseContext(out io.Writer, pathOptions *pathOptions) *cobra.Comm
 	options := &useContextOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "use-context context-name",
+		Use:   "use-context CONTEXT_NAME",
 		Short: "Sets the current-context in a .kubeconfig file",
 		Long:  `Sets the current-context in a .kubeconfig file`,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/config/view.go

@@ -35,18 +35,28 @@ type viewOptions struct {
 	merge       util.BoolFlag
 }
 
+const (
+	view_long = `displays merged .kubeconfig settings or a specified .kubeconfig file.
+
+You can use --output=template --template=TEMPLATE to extract specific values.`
+	view_example = `// Show merged .kubeconfig settings.
+$ kubectl config view
+
+// Show only local ./.kubeconfig settings
+$ kubectl config view --local
+
+// Get the password for the e2e user
+$ kubectl config view -o template --template='{{ index . "users" "e2e" "password" }}'`
+)
+
 func NewCmdConfigView(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &viewOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "view",
-		Short: "displays merged .kubeconfig settings or a specified .kubeconfig file.",
-		Long:  "displays merged .kubeconfig settings or a specified .kubeconfig file.",
-		Example: `// Show merged .kubeconfig settings.
-$ kubectl config view
-
-// Show only local ./.kubeconfig settings
-$ kubectl config view --local`,
+		Use:     "view",
+		Short:   "displays merged .kubeconfig settings or a specified .kubeconfig file.",
+		Long:    view_long,
+		Example: view_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			options.complete()
 

pkg/kubectl/cmd/create.go

@@ -41,7 +41,7 @@ $ cat pod.json | kubectl create -f -`
 func (f *Factory) NewCmdCreate(out io.Writer) *cobra.Command {
 	var filenames util.StringList
 	cmd := &cobra.Command{
-		Use:     "create -f filename",
+		Use:     "create -f FILENAME",
 		Short:   "Create a resource by filename or stdin",
 		Long:    create_long,
 		Example: create_example,

pkg/kubectl/cmd/delete.go

@@ -58,7 +58,7 @@ $ kubectl delete pods --all`
 func (f *Factory) NewCmdDelete(out io.Writer) *cobra.Command {
 	var filenames util.StringList
 	cmd := &cobra.Command{
-		Use:     "delete (-f filename | <resource> (<id> | -l <label> | --all))",
+		Use:     "delete ([-f FILENAME] | (RESOURCE [(ID | -l label | --all)]",
 		Short:   "Delete a resource by filename, stdin, or resource and ID.",
 		Long:    delete_long,
 		Example: delete_example,

pkg/kubectl/cmd/describe.go

@@ -26,7 +26,7 @@ import (
 
 func (f *Factory) NewCmdDescribe(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "describe <resource> <id>",
+		Use:   "describe RESOURCE ID",
 		Short: "Show details of a specific resource",
 		Long: `Show details of a specific resource.
 

pkg/kubectl/cmd/exec.go

@@ -40,7 +40,7 @@ $ kubectl exec -p 123456-7890 -c ruby-container -i -t -- bash -il`
 
 func (f *Factory) NewCmdExec(cmdIn io.Reader, cmdOut, cmdErr io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "exec -p <pod> -c <container> -- <command> [<args...>]",
+		Use:     "exec -p POD -c CONTAINER -- COMMAND [args...]",
 		Short:   "Execute a command in a container.",
 		Long:    "Execute a command in a container.",
 		Example: exec_example,
@@ -60,11 +60,11 @@ func (f *Factory) NewCmdExec(cmdIn io.Reader, cmdOut, cmdErr io.Writer) *cobra.C
 func RunExec(f *Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer, cmd *cobra.Command, args []string) error {
 	podName := util.GetFlagString(cmd, "pod")
 	if len(podName) == 0 {
-		return util.UsageError(cmd, "<pod> is required for exec")
+		return util.UsageError(cmd, "POD is required for exec")
 	}
 
 	if len(args) < 1 {
-		return util.UsageError(cmd, "<command> is required for exec")
+		return util.UsageError(cmd, "COMMAND is required for exec")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)

pkg/kubectl/cmd/expose.go

@@ -28,7 +28,7 @@ import (
 
 const (
 	expose_long = `Take a replicated application and expose it as Kubernetes Service.
-		
+
 Looks up a ReplicationController by name, and uses the selector for that replication controller
 as the selector for a new Service on the specified port.`
 
@@ -41,7 +41,7 @@ $ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
 
 func (f *Factory) NewCmdExposeService(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]",
+		Use:     "expose NAME --port=port [--protocol=TCP|UDP] [--container-port=number-or-name] [--service-name=name] [--public-ip=ip] [--create-external-load-balancer=bool]",
 		Short:   "Take a replicated application and expose it as Kubernetes Service",
 		Long:    expose_long,
 		Example: expose_example,

pkg/kubectl/cmd/get.go

@@ -58,7 +58,7 @@ $ kubectl get rc,services`
 // retrieves one or more resources from a server.
 func (f *Factory) NewCmdGet(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "get [(-o|--output=)json|yaml|template|...] <resource> [<id>]",
+		Use:     "get [(-o|--output=)json|yaml|template|...] RESOURCE [ID]",
 		Short:   "Display one or many resources",
 		Long:    get_long,
 		Example: get_example,

pkg/kubectl/cmd/label.go

@@ -50,7 +50,7 @@ $ kubectl label pods foo bar-`
 
 func (f *Factory) NewCmdLabel(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "label [--overwrite] <resource> <name> <key-1>=<val-1> ... <key-n>=<val-n> [--resource-version=<version>]",
+		Use:     "label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]",
 		Short:   "Update the labels on a resource",
 		Long:    label_long,
 		Example: label_example,

pkg/kubectl/cmd/log.go

@@ -59,7 +59,7 @@ func selectContainer(pod *api.Pod, in io.Reader, out io.Writer) string {
 
 func (f *Factory) NewCmdLog(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "log [-f] <pod> [<container>]",
+		Use:     "log [-f] POD [CONTAINER]",
 		Short:   "Print the logs for a container in a pod.",
 		Long:    "Print the logs for a container in a pod. If the pod has only one container, the container name is optional.",
 		Example: log_example,
@@ -75,11 +75,11 @@ func (f *Factory) NewCmdLog(out io.Writer) *cobra.Command {
 
 func RunLog(f *Factory, out io.Writer, cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
-		return util.UsageError(cmd, "<pod> is required for log")
+		return util.UsageError(cmd, "POD is required for log")
 	}
 
 	if len(args) > 2 {
-		return util.UsageError(cmd, "log <pod> [<container>]")
+		return util.UsageError(cmd, "log POD [CONTAINER]")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)

pkg/kubectl/cmd/namespace.go

@@ -27,7 +27,7 @@ import (
 // TODO remove once people have been given enough time to notice
 func NewCmdNamespace(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "namespace [<namespace>]",
+		Use:   "namespace [namespace]",
 		Short: "SUPERCEDED: Set and view the current Kubernetes namespace",
 		Long: `SUPERCEDED:  Set and view the current Kubernetes namespace scope for command line requests.
 

pkg/kubectl/cmd/portforward.go

@@ -28,22 +28,23 @@ import (
 )
 
 const (
-	portforward_example = `$ kubectl port-forward -p mypod 5000 6000
-<listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
+	portforward_example = `
+// listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod
+$ kubectl port-forward -p mypod 5000 6000
 
+// listens on port 8888 locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod 8888:5000
-<listens on port 8888 locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod :5000
-<listens on a random port locally, forwarding to 5000 in the pod>
 
-$ kubectl port-forward -p mypod 0:5000
-<listens on a random port locally, forwarding to 5000 in the pod> `
+// listens on a random port locally, forwarding to 5000 in the pod
+$ kubectl port-forward -p mypod 0:5000`
 )
 
 func (f *Factory) NewCmdPortForward() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "port-forward -p <pod> [<local port>:]<remote port> [<port>...]",
+		Use:     "port-forward -p POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]",
 		Short:   "Forward 1 or more local ports to a pod.",
 		Long:    "Forward 1 or more local ports to a pod.",
 		Example: portforward_example,
@@ -60,11 +61,11 @@ func (f *Factory) NewCmdPortForward() *cobra.Command {
 func RunPortForward(f *Factory, cmd *cobra.Command, args []string) error {
 	podName := util.GetFlagString(cmd, "pod")
 	if len(podName) == 0 {
-		return util.UsageError(cmd, "<pod> is required for exec")
+		return util.UsageError(cmd, "POD is required for exec")
 	}
 
 	if len(args) < 1 {
-		return util.UsageError(cmd, "at least 1 <port> is required for port-forward")
+		return util.UsageError(cmd, "at least 1 PORT is required for port-forward")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)

pkg/kubectl/cmd/proxy.go

@@ -27,11 +27,21 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const (
+	proxy_example = `// Run a proxy to kubernetes apiserver on port 8011, serving static content from ./local/www/
+$ kubectl proxy --port=8011 --www=./local/www/
+
+// Run a proxy to kubernetes apiserver, changing the api prefix to k8s-api
+// This makes e.g. the pods api available at localhost:8011/k8s-api/v1beta1/pods/
+$ kubectl proxy --api-prefix=k8s-api`
+)
+
 func (f *Factory) NewCmdProxy(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "proxy",
-		Short: "Run a proxy to the Kubernetes API server",
-		Long:  `Run a proxy to the Kubernetes API server.`,
+		Use:     "proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]",
+		Short:   "Run a proxy to the Kubernetes API server",
+		Long:    `Run a proxy to the Kubernetes API server. `,
+		Example: proxy_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunProxy(f, out, cmd)
 			util.CheckErr(err)

pkg/kubectl/cmd/resize.go

@@ -47,7 +47,7 @@ $ kubectl resize --current-replicas=2 --replicas=3 replicationcontrollers foo`
 
 func (f *Factory) NewCmdResize(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "resize [--resource-version=<version>] [--current-replicas=<count>] --replicas=<count> <resource> <id>",
+		Use:     "resize [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE ID",
 		Short:   "Set a new size for a Replication Controller.",
 		Long:    resize_long,
 		Example: resize_example,
@@ -65,7 +65,7 @@ func (f *Factory) NewCmdResize(out io.Writer) *cobra.Command {
 func RunResize(f *Factory, out io.Writer, cmd *cobra.Command, args []string) error {
 	count := util.GetFlagInt(cmd, "replicas")
 	if len(args) != 2 || count < 0 {
-		return util.UsageError(cmd, "--replicas=<count> <resource> <id>")
+		return util.UsageError(cmd, "--replicas=COUNT RESOURCE ID")
 	}
 
 	cmdNamespace, err := f.DefaultNamespace(cmd)

pkg/kubectl/cmd/rollingupdate.go

@@ -44,7 +44,7 @@ $ cat frontend-v2.json | kubectl rollingupdate frontend-v1 -f -`
 
 func (f *Factory) NewCmdRollingUpdate(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "rollingupdate <old-controller-name> -f <new-controller.json>",
+		Use:     "rollingupdate OLD_CONTROLLER_NAME -f NEW_CONTROLLER_SPEC",
 		Short:   "Perform a rolling update of the given ReplicationController.",
 		Long:    rollingupdate_long,
 		Example: rollingupdate_example,

pkg/kubectl/cmd/run.go

@@ -44,7 +44,7 @@ $ kubectl run-container nginx --image=dockerfile/nginx --overrides='{ "apiVersio
 
 func (f *Factory) NewCmdRunContainer(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "run-container <name> --image=<image> [--port=<port>] [--replicas=replicas] [--dry-run=<bool>] [--overrides=<inline-json>]",
+		Use:     "run-container NAME --image=image [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]",
 		Short:   "Run a particular image on the cluster.",
 		Long:    run_long,
 		Example: run_example,
@@ -66,7 +66,7 @@ func (f *Factory) NewCmdRunContainer(out io.Writer) *cobra.Command {
 
 func RunRunContainer(f *Factory, out io.Writer, cmd *cobra.Command, args []string) error {
 	if len(args) != 1 {
-		return util.UsageError(cmd, "<name> is required for run-container")
+		return util.UsageError(cmd, "NAME is required for run-container")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)

pkg/kubectl/cmd/stop.go

@@ -49,7 +49,7 @@ func (f *Factory) NewCmdStop(out io.Writer) *cobra.Command {
 		Filenames util.StringList
 	}{}
 	cmd := &cobra.Command{
-		Use:     "stop (-f filename | <resource> (<id> | -l <label> | --all))",
+		Use:     "stop (-f FILENAME | RESOURCE (ID | -l label | --all))",
 		Short:   "Gracefully shut down a resource by id or filename.",
 		Long:    stop_long,
 		Example: stop_example,

pkg/kubectl/cmd/update.go

@@ -43,7 +43,7 @@ $ kubectl update pods my-pod --patch='{ "apiVersion": "v1beta1", "desiredState":
 func (f *Factory) NewCmdUpdate(out io.Writer) *cobra.Command {
 	var filenames util.StringList
 	cmd := &cobra.Command{
-		Use:     "update -f filename",
+		Use:     "update -f FILENAME",
 		Short:   "Update a resource by filename or stdin.",
 		Long:    update_long,
 		Example: update_example,