Fix md generation for kubectl docs

cmd/gendocs/gen_kubectl_docs.go

@@ -65,10 +65,10 @@ func genMarkdown(command *cobra.Command, parent, docsDir string) {
 	fmt.Fprintf(out, "## %s\n\n", name)
 	fmt.Fprintf(out, "%s\n\n", short)
 	fmt.Fprintf(out, "### Synopsis\n\n")
-	fmt.Fprintf(out, "```\n%s\n```\n\n", long)
+	fmt.Fprintf(out, "\n%s\n\n", long)
 
 	if command.Runnable() {
-		fmt.Fprintf(out, "%s\n\n", command.UseLine())
+		fmt.Fprintf(out, "```\n%s\n```\n\n", command.UseLine())
 	}
 
 	if len(command.Example) > 0 {

docs/kubectl-clusterinfo.md

@@ -4,11 +4,12 @@ Display cluster info
 
 ### Synopsis
 
-```
+
 Display addresses of the master and services with label kubernetes.io/cluster-service=true
-```
 
+```
 kubectl clusterinfo
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-config-set-cluster.md

@@ -4,16 +4,26 @@ Sets a cluster entry in .kubeconfig
 
 ### Synopsis
 
+
+Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
+
+```
+kubectl config set-cluster NAME [--server=server] [--certificate-authority=path/to/certficate/authority] [--api-version=apiversion] [--insecure-skip-tls-verify=true]
 ```
-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.
+
+### Examples
 
 ```
+// 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
 
-kubectl config set-cluster name [--server=server] [--certificate-authority=path/to/certficate/authority] [--api-version=apiversion] [--insecure-skip-tls-verify=true]
+// Disable cert checking for the dev cluster entry
+$ kubectl config set-cluster e2e --insecure-skip-tls-verify=true
+```
 
 ### Options
 

docs/kubectl-config-set-context.md

@@ -4,15 +4,20 @@ Sets a context entry in .kubeconfig
 
 ### Synopsis
 
-```
+
 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.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
+
+```
+kubectl config set-context NAME [--cluster=cluster_nickname] [--user=user_nickname] [--namespace=namespace]
 ```
 
-kubectl config set-context name [--cluster=cluster-nickname] [--user=user-nickname] [--namespace=namespace]
+### Examples
+
+```
+// Set the user field on the gce context entry without touching other values
+$ kubectl config set-context gce --user=cluster-admin
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-config-set-credentials.md

@@ -4,14 +4,9 @@ Sets a user entry in .kubeconfig
 
 ### Synopsis
 
-```
-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
+Sets a user entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values.
 
   Client-certificate flags:
     --client-certificate=certfile --client-key=keyfile
@@ -24,9 +19,24 @@ Sets a user entry in .kubeconfig
 
   Bearer token and basic auth are mutually exclusive.
 
+
+```
+kubectl config set-credentials NAME [--auth-path=/path/to/authfile] [--client-certificate=path/to/certfile] [--client-key=path/to/keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
 ```
 
-kubectl config set-credentials name [--auth-path=authfile] [--client-certificate=certfile] [--client-key=keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
+### Examples
+
+```
+// 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
+```
 
 ### Options
 

docs/kubectl-config-set.md

@@ -4,16 +4,14 @@ Sets an individual value in a .kubeconfig file
 
 ### Synopsis
 
-```
-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.
 
+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.
 
 ```
-
-kubectl config set property-name property-value
+kubectl config set PROPERTY_NAME PROPERTY_VALUE
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-config-unset.md

@@ -4,14 +4,13 @@ Unsets an individual value in a .kubeconfig file
 
 ### Synopsis
 
-```
-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.
+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.
 
 ```
-
-kubectl config unset property-name
+kubectl config unset PROPERTY_NAME
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-config-use-context.md

@@ -4,11 +4,12 @@ Sets the current-context in a .kubeconfig file
 
 ### Synopsis
 
-```
+
 Sets the current-context in a .kubeconfig file
-```
 
-kubectl config use-context context-name
+```
+kubectl config use-context CONTEXT_NAME
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-config-view.md

@@ -4,11 +4,14 @@ displays merged .kubeconfig settings or a specified .kubeconfig file.
 
 ### Synopsis
 
-```
+
 displays merged .kubeconfig settings or a specified .kubeconfig file.
-```
 
+You can use --output=template --template=TEMPLATE to extract specific values.
+
+```
 kubectl config view
+```
 
 ### Examples
 
@@ -18,6 +21,9 @@ $ 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" }}'
 ```
 
 ### Options

docs/kubectl-config.md

@@ -4,11 +4,12 @@ config modifies .kubeconfig files
 
 ### Synopsis
 
-```
+
 config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"
-```
 
-kubectl config <subcommand>
+```
+kubectl config SUBCOMMAND
+```
 
 ### Options
 

docs/kubectl-create.md

@@ -4,13 +4,14 @@ Create a resource by filename or stdin
 
 ### Synopsis
 
-```
+
 Create a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
-```
 
-kubectl create -f filename
+```
+kubectl create -f FILENAME
+```
 
 ### Examples
 

docs/kubectl-delete.md

@@ -4,7 +4,7 @@ Delete a resource by filename, stdin, or resource and ID.
 
 ### Synopsis
 
-```
+
 Delete a resource by filename, stdin, resource and ID, or by resources and label selector.
 
 JSON and YAML formats are accepted.
@@ -15,9 +15,10 @@ arguments are used and the filename is ignored.
 Note that the delete command does NOT do resource version checks, so if someone
 submits an update to a resource right when you submit a delete, their update
 will be lost along with the rest of the resource.
-```
 
-kubectl delete (-f filename | <resource> (<id> | -l <label> | --all))
+```
+kubectl delete ([-f FILENAME] | (RESOURCE [(ID | -l label | --all)]
+```
 
 ### Examples
 

docs/kubectl-describe.md

@@ -4,14 +4,15 @@ Show details of a specific resource
 
 ### Synopsis
 
-```
+
 Show details of a specific resource.
 
 This command joins many API calls together to form a detailed description of a
 given resource.
-```
 
-kubectl describe <resource> <id>
+```
+kubectl describe RESOURCE ID
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-exec.md

@@ -4,11 +4,12 @@ Execute a command in a container.
 
 ### Synopsis
 
-```
+
 Execute a command in a container.
-```
 
-kubectl exec -p <pod> -c <container> -- <command> [<args...>]
+```
+kubectl exec -p POD -c CONTAINER -- COMMAND [args...]
+```
 
 ### Examples
 

docs/kubectl-expose.md

@@ -4,14 +4,15 @@ Take a replicated application and expose it as Kubernetes Service
 
 ### Synopsis
 
-```
+
 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.
-```
 
-kubectl expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]
+```
+kubectl expose NAME --port=port [--protocol=TCP|UDP] [--container-port=number-or-name] [--service-name=name] [--public-ip=ip] [--create-external-load-balancer=bool]
+```
 
 ### Examples
 

docs/kubectl-get.md

@@ -4,7 +4,7 @@ Display one or many resources
 
 ### Synopsis
 
-```
+
 Display one or many resources.
 
 Possible resources include pods (po), replication controllers (rc), services
@@ -12,9 +12,10 @@ Possible resources include pods (po), replication controllers (rc), services
 
 By specifying the output as 'template' and providing a Go template as the value
 of the --template flag, you can filter the attributes of the fetched resource(s).
-```
 
-kubectl get [(-o|--output=)json|yaml|template|...] <resource> [<id>]
+```
+kubectl get [(-o|--output=)json|yaml|template|...] RESOURCE [ID]
+```
 
 ### Examples
 

docs/kubectl-label.md

@@ -4,14 +4,15 @@ Update the labels on a resource
 
 ### Synopsis
 
-```
+
 Update the labels on a resource.
 
 If --overwrite is true, then existing labels can be overwritten, otherwise attempting to overwrite a label will result in an error.
 If --resource-version is specified, then updates will use this resource version, otherwise the existing resource-version will be used.
-```
 
-kubectl label [--overwrite] <resource> <name> <key-1>=<val-1> ... <key-n>=<val-n> [--resource-version=<version>]
+```
+kubectl label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]
+```
 
 ### Examples
 

docs/kubectl-log.md

@@ -4,11 +4,12 @@ Print the logs for a container in a pod.
 
 ### Synopsis
 
-```
+
 Print the logs for a container in a pod. If the pod has only one container, the container name is optional.
-```
 
-kubectl log [-f] <pod> [<container>]
+```
+kubectl log [-f] POD [CONTAINER]
+```
 
 ### Examples
 

docs/kubectl-namespace.md

@@ -4,14 +4,15 @@ SUPERCEDED: Set and view the current Kubernetes namespace
 
 ### Synopsis
 
-```
+
 SUPERCEDED:  Set and view the current Kubernetes namespace scope for command line requests.
 
 namespace has been superceded by the context.namespace field of .kubeconfig files.  See 'kubectl config set-context --help' for more details.
 
-```
 
-kubectl namespace [<namespace>]
+```
+kubectl namespace [namespace]
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-port-forward.md

@@ -4,26 +4,28 @@ Forward 1 or more local ports to a pod.
 
 ### Synopsis
 
-```
+
 Forward 1 or more local ports to a pod.
-```
 
-kubectl port-forward -p <pod> [<local port>:]<remote port> [<port>...]
+```
+kubectl port-forward -p POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]
+```
 
 ### Examples
 
 ```
+
+// 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 ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
 
+// 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>
 
+// 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> 
 ```
 
 ### Options

docs/kubectl-proxy.md

@@ -4,11 +4,23 @@ Run a proxy to the Kubernetes API server
 
 ### Synopsis
 
-```
+
 Run a proxy to the Kubernetes API server. 
+
+```
+kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]
 ```
 
-kubectl proxy
+### Examples
+
+```
+// 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
+```
 
 ### Options
 

docs/kubectl-resize.md

@@ -4,16 +4,17 @@ Set a new size for a Replication Controller.
 
 ### Synopsis
 
-```
+
 Set a new size for a Replication Controller.
 
 Resize also allows users to specify one or more preconditions for the resize action.
 If --current-replicas or --resource-version is specified, it is validated before the
 resize is attempted, and it is guaranteed that the precondition holds true when the
 resize is sent to the server.
-```
 
-kubectl resize [--resource-version=<version>] [--current-replicas=<count>] --replicas=<count> <resource> <id>
+```
+kubectl resize [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE ID
+```
 
 ### Examples
 

docs/kubectl-rollingupdate.md

@@ -4,15 +4,16 @@ Perform a rolling update of the given ReplicationController.
 
 ### Synopsis
 
-```
+
 Perform a rolling update of the given ReplicationController.
 
 Replaces the specified controller with new controller, updating one pod at a time to use the
 new PodTemplate. The new-controller.json must specify the same namespace as the
 existing controller and overwrite at least one (common) label in its replicaSelector.
-```
 
-kubectl rollingupdate <old-controller-name> -f <new-controller.json>
+```
+kubectl rollingupdate OLD_CONTROLLER_NAME -f NEW_CONTROLLER_SPEC
+```
 
 ### Examples
 

docs/kubectl-run-container.md

@@ -4,12 +4,13 @@ Run a particular image on the cluster.
 
 ### Synopsis
 
-```
+
 Create and run a particular image, possibly replicated.
 Creates a replication controller to manage the created container(s).
-```
 
-kubectl run-container <name> --image=<image> [--port=<port>] [--replicas=replicas] [--dry-run=<bool>] [--overrides=<inline-json>]
+```
+kubectl run-container NAME --image=image [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]
+```
 
 ### Examples
 

docs/kubectl-stop.md

@@ -4,14 +4,15 @@ Gracefully shut down a resource by id or filename.
 
 ### Synopsis
 
-```
+
 Gracefully shut down a resource by id or filename.
 
 Attempts to shut down and delete a resource that supports graceful termination.
 If the resource is resizable it will be resized to 0 before deletion.
-```
 
-kubectl stop (-f filename | <resource> (<id> | -l <label> | --all))
+```
+kubectl stop (-f FILENAME | RESOURCE (ID | -l label | --all))
+```
 
 ### Examples
 

docs/kubectl-update.md

@@ -4,13 +4,14 @@ Update a resource by filename or stdin.
 
 ### Synopsis
 
-```
+
 Update a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
-```
 
-kubectl update -f filename
+```
+kubectl update -f FILENAME
+```
 
 ### Examples
 

docs/kubectl-version.md

@@ -4,11 +4,12 @@ Print the client and server version information.
 
 ### Synopsis
 
-```
+
 Print the client and server version information.
-```
 
+```
 kubectl version
+```
 
 ### Options
 

docs/kubectl.md

@@ -4,13 +4,14 @@ kubectl controls the Kubernetes cluster manager
 
 ### Synopsis
 
-```
+
 kubectl controls the Kubernetes cluster manager.
 
 Find more information at https://github.com/GoogleCloudPlatform/kubernetes.
-```
 
+```
 kubectl
+```
 
 ### Options
 

docs/man/man1/kubectl-config-set-cluster.1

@@ -13,11 +13,8 @@ kubectl config set\-cluster \- Sets a cluster entry in .kubeconfig
 
 .SH DESCRIPTION
 .PP
-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.
+Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
 
 
 .SH OPTIONS
@@ -144,6 +141,24 @@ Sets a cluster entry in .kubeconfig
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// 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
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,

docs/man/man1/kubectl-config-set-context.1

@@ -14,10 +14,7 @@ kubectl config set\-context \- Sets a context entry in .kubeconfig
 .SH DESCRIPTION
 .PP
 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.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
@@ -138,6 +135,18 @@ Sets a context entry in .kubeconfig
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Set the user field on the gce context entry without touching other values
+$ kubectl config set\-context gce \-\-user=cluster\-admin
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,

docs/man/man1/kubectl-config-set-credentials.1

@@ -14,20 +14,7 @@ kubectl config set\-credentials \- Sets a user entry in .kubeconfig
 .SH DESCRIPTION
 .PP
 Sets a user entry in .kubeconfig
-
-.PP
-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:
-
-.PP
-.RS
-
-.nf
-set\-credentials cluster\-admin \-\-client\-key=\~/.kube/admin.key
-
-.fi
-.RE
+Specifying a name that already exists will merge new fields on top of existing values.
 
 .PP
 Client\-certificate flags:
@@ -169,6 +156,25 @@ Bearer token and basic auth are mutually exclusive.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// 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
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,

docs/man/man1/kubectl-config-set.1

@@ -14,16 +14,8 @@ kubectl config set \- Sets an individual value in a .kubeconfig file
 .SH DESCRIPTION
 .PP
 Sets an individual value in a .kubeconfig file
-
-.PP
-.RS
-
-.nf
-    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.
-
-.fi
-.RE
+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.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS

docs/man/man1/kubectl-config-unset.1

@@ -14,15 +14,7 @@ kubectl config unset \- Unsets an individual value in a .kubeconfig file
 .SH DESCRIPTION
 .PP
 Unsets an individual value in a .kubeconfig file
-
-.PP
-.RS
-
-.nf
-    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.
-
-.fi
-.RE
+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.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS

docs/man/man1/kubectl-config-view.1

@@ -15,6 +15,9 @@ kubectl config view \- displays merged .kubeconfig settings or a specified .kube
 .PP
 displays merged .kubeconfig settings or a specified .kubeconfig file.
 
+.PP
+You can use \-\-output=template \-\-template=TEMPLATE to extract specific values.
+
 
 .SH OPTIONS
 .PP
@@ -168,6 +171,9 @@ $ 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" \}\}'
+
 .fi
 .RE
 

docs/man/man1/kubectl-port-forward.1

@@ -133,17 +133,18 @@ Forward 1 or more local ports to a pod.
 .RS
 
 .nf
+
+// 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 ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
 
+// 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>
 
+// 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> 
 
 .fi
 .RE

docs/man/man1/kubectl-proxy.1

@@ -140,6 +140,22 @@ Run a proxy to the Kubernetes API server.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// 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
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl(1)\fP,

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),
+		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.
-		`,
+		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),
+		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.`,
-
+		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`,
+		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

@@ -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",
+		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.`,
+		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,