Merge pull request #5634 from vieux/improve_mflag_usage

Add support for \n in usages

docker/docker.go

@@ -43,11 +43,11 @@ func main() {
 		flDaemon             = flag.Bool([]string{"d", "-daemon"}, false, "Enable daemon mode")
 		flDebug              = flag.Bool([]string{"D", "-debug"}, false, "Enable debug mode")
 		flAutoRestart        = flag.Bool([]string{"r", "-restart"}, true, "Restart previously running containers")
-		bridgeName           = flag.String([]string{"b", "-bridge"}, "", "Attach containers to a pre-existing network bridge; use 'none' to disable container networking")
+		bridgeName           = flag.String([]string{"b", "-bridge"}, "", "Attach containers to a pre-existing network bridge\nuse 'none' to disable container networking")
 		bridgeIp             = flag.String([]string{"#bip", "-bip"}, "", "Use this CIDR notation address for the network bridge's IP, not compatible with -b")
 		pidfile              = flag.String([]string{"p", "-pidfile"}, "/var/run/docker.pid", "Path to use for daemon PID file")
 		flRoot               = flag.String([]string{"g", "-graph"}, "/var/lib/docker", "Path to use as the root of the docker runtime")
-		flSocketGroup        = flag.String([]string{"G", "-group"}, "docker", "Group to assign the unix socket specified by -H when running in daemon mode; use '' (the empty string) to disable setting of a group")
+		flSocketGroup        = flag.String([]string{"G", "-group"}, "docker", "Group to assign the unix socket specified by -H when running in daemon mode\nuse '' (the empty string) to disable setting of a group")
 		flEnableCors         = flag.Bool([]string{"#api-enable-cors", "-api-enable-cors"}, false, "Enable CORS headers in the remote API")
 		flDns                = opts.NewListOpts(opts.ValidateIp4Address)
 		flDnsSearch          = opts.NewListOpts(opts.ValidateDomain)
@@ -58,7 +58,7 @@ func main() {
 		flGraphDriver        = flag.String([]string{"s", "-storage-driver"}, "", "Force the docker runtime to use a specific storage driver")
 		flExecDriver         = flag.String([]string{"e", "-exec-driver"}, "native", "Force the docker runtime to use a specific exec driver")
 		flHosts              = opts.NewListOpts(api.ValidateHost)
-		flMtu                = flag.Int([]string{"#mtu", "-mtu"}, 0, "Set the containers network MTU; if no value is provided: default to the default route MTU or 1500 if no default route is available")
+		flMtu                = flag.Int([]string{"#mtu", "-mtu"}, 0, "Set the containers network MTU\nif no value is provided: default to the default route MTU or 1500 if no default route is available")
 		flTls                = flag.Bool([]string{"-tls"}, false, "Use TLS; implied by tls-verify flags")
 		flTlsVerify          = flag.Bool([]string{"-tlsverify"}, false, "Use TLS and verify the remote (daemon: verify client, client: verify daemon)")
 		flCa                 = flag.String([]string{"-tlscacert"}, dockerConfDir+defaultCaFile, "Trust only remotes providing a certificate signed by the CA given here")
@@ -68,7 +68,7 @@ func main() {
 	)
 	flag.Var(&flDns, []string{"#dns", "-dns"}, "Force docker to use specific DNS servers")
 	flag.Var(&flDnsSearch, []string{"-dns-search"}, "Force Docker to use specific DNS search domains")
-	flag.Var(&flHosts, []string{"H", "-host"}, "The socket(s) to bind to in daemon mode, specified using one or more tcp://host:port, unix:///path/to/socket, fd://* or fd://socketfd.")
+	flag.Var(&flHosts, []string{"H", "-host"}, "The socket(s) to bind to in daemon mode\nspecified using one or more tcp://host:port, unix:///path/to/socket, fd://* or fd://socketfd.")
 
 	flag.Parse()
 

docs/sources/reference/commandline/cli.md

@@ -809,33 +809,39 @@ Run a command in a new container
 
     Usage: docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
 
-    -a, --attach=[]: Attach to stdin, stdout or stderr.
+    -a, --attach=[]            Attach to stdin, stdout or stderr.
-    -c, --cpu-shares=0: CPU shares (relative weight)
+    -c, --cpu-shares=0         CPU shares (relative weight)
-    --cidfile="": Write the container ID to the file
+    --cidfile=""               Write the container ID to the file
-    -d, --detach=false: Detached mode: Run container in the background, print new container id
+    -d, --detach=false         Detached mode: Run container in the background, print new container id
-    --dns=[]: Set custom dns servers
+    --dns=[]                   Set custom dns servers
-    --dns-search=[]: Set custom dns search domains
+    --dns-search=[]            Set custom dns search domains
-    -e, --env=[]: Set environment variables
+    -e, --env=[]               Set environment variables
-    --entrypoint="": Overwrite the default entrypoint of the image
+    --entrypoint=""            Overwrite the default entrypoint of the image
-    --env-file=[]: Read in a line delimited file of ENV variables
+    --env-file=[]              Read in a line delimited file of ENV variables
-    --expose=[]: Expose a port from the container without publishing it to your host
+    --expose=[]                Expose a port from the container without publishing it to your host
-    -h, --hostname="": Container host name
+    -h, --hostname=""          Container host name
-    -i, --interactive=false: Keep stdin open even if not attached
+    -i, --interactive=false    Keep stdin open even if not attached
-    --link=[]: Add link to another container (name:alias)
+    --link=[]                  Add link to another container (name:alias)
-    --lxc-conf=[]: (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
+    --lxc-conf=[]              (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
-    -m, --memory="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
+    -m, --memory=""            Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
-    --name="": Assign a name to the container
+    --name=""                  Assign a name to the container
-    --net="bridge": Set the Network mode for the container ('bridge': creates a new network stack for the container on the docker bridge, 'none': no networking for this container, 'container:<name|id>': reuses another container network stack), 'host': use the host network stack inside the container
+    --net="bridge"             Set the Network mode for the container
-    -P, --publish-all=false: Publish all exposed ports to the host interfaces
+                                 'bridge': creates a new network stack for the container on the docker bridge
-    -p, --publish=[]: Publish a container's port to the host (format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort) (use 'docker port' to see the actual mapping)
+                                 'none': no networking for this container
-    --privileged=false: Give extended privileges to this container
+                                 'container:<name|id>': reuses another container network stack
-    --rm=false: Automatically remove the container when it exits (incompatible with -d)
+                                 'host': use the host network stack inside the contaner
-    --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
+    -p, --publish=[]           Publish a container's port to the host
-    -t, --tty=false: Allocate a pseudo-tty
+                                 format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort
-    -u, --user="": Username or UID
+                                 (use 'docker port' to see the actual mapping)
-    -v, --volume=[]: Bind mount a volume (e.g. from the host: -v /host:/container, from docker: -v /container)
+    -P, --publish-all=false    Publish all exposed ports to the host interfaces
-    --volumes-from=[]: Mount volumes from the specified container(s)
+    --privileged=false         Give extended privileges to this container
-    -w, --workdir="": Working directory inside the container
+    --rm=false                 Automatically remove the container when it exits (incompatible with -d)
+    --sig-proxy=true           Proxify all received signal to the process (even in non-tty mode)
+    -t, --tty=false            Allocate a pseudo-tty
+    -u, --user=""              Username or UID
+    -v, --volume=[]            Bind mount a volume (e.g. from the host: -v /host:/container, from docker: -v /container)
+    --volumes-from=[]          Mount volumes from the specified container(s)
+    -w, --workdir=""           Working directory inside the container
 
 The `docker run` command first `creates` a writeable container layer over the
 specified image, and then `starts` it using the specified command. That is,

docs/sources/reference/run.md

@@ -138,6 +138,11 @@ PID files):
 
     --dns=[]      : Set custom dns servers for the container
     --net="bridge": Set the Network mode for the container ('bridge': creates a new network stack for the container on the docker bridge, 'none': no networking for this container, 'container:<name|id>': reuses another container network stack), 'host': use the host network stack inside the container
+    --net="bridge"             Set the Network mode for the container
+                                 'bridge': creates a new network stack for the container on the docker bridge
+                                 'none': no networking for this container
+                                 'container:<name|id>': reuses another container network stack
+                                 'host': use the host network stack inside the contaner
 
 By default, all containers have networking enabled and they can make any
 outgoing connections. The operator can completely disable networking

pkg/mflag/example/example.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"fmt"
+
 	flag "github.com/dotcloud/docker/pkg/mflag"
 )
 
@@ -19,15 +20,17 @@ func init() {
 	flag.IntVar(&i, []string{"-integer", "-number"}, -1, "a simple integer")
 	flag.StringVar(&str, []string{"s", "#hidden", "-string"}, "", "a simple string") //-s -hidden and --string will work, but -hidden won't be in the usage
 	flag.BoolVar(&h, []string{"h", "#help", "-help"}, false, "display the help")
+	flag.StringVar(&str, []string{"mode"}, "mode1", "set the mode\nmode1: use the mode1\nmode2: use the mode2\nmode3: use the mode3")
 	flag.Parse()
 }
 func main() {
 	if h {
 		flag.PrintDefaults()
-	}
+	} else {
 		fmt.Printf("s/#hidden/-string: %s\n", str)
 		fmt.Printf("b: %b\n", b)
 		fmt.Printf("-bool: %b\n", b2)
 		fmt.Printf("s/#hidden/-string(via lookup): %s\n", flag.Lookup("s").Value.String())
 		fmt.Printf("ARGS: %v\n", flag.Args())
+	}
 }

pkg/mflag/flag.go

@@ -83,6 +83,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"text/tabwriter"
 	"time"
 )
 
@@ -419,11 +420,12 @@ func Set(name, value string) error {
 // PrintDefaults prints, to standard error unless configured
 // otherwise, the default values of all defined flags in the set.
 func (f *FlagSet) PrintDefaults() {
+	writer := tabwriter.NewWriter(f.out(), 20, 1, 3, ' ', 0)
 	f.VisitAll(func(flag *Flag) {
-		format := "  -%s=%s: %s\n"
+		format := "  -%s=%s"
 		if _, ok := flag.Value.(*stringValue); ok {
 			// put quotes on the value
-			format = "  -%s=%q: %s\n"
+			format = "  -%s=%q"
 		}
 		names := []string{}
 		for _, name := range flag.Names {
@@ -432,9 +434,18 @@ func (f *FlagSet) PrintDefaults() {
 			}
 		}
 		if len(names) > 0 {
-			fmt.Fprintf(f.out(), format, strings.Join(names, ", -"), flag.DefValue, flag.Usage)
+			fmt.Fprintf(writer, format, strings.Join(names, ", -"), flag.DefValue)
+			for i, line := range strings.Split(flag.Usage, "\n") {
+				if i != 0 {
+					line = "  " + line
+				}
+				fmt.Fprintln(writer, "\t", line)
+			}
+			//			start := fmt.Sprintf(format, strings.Join(names, ", -"), flag.DefValue)
+			//			fmt.Fprintln(f.out(), start, strings.Replace(flag.Usage, "\n", "\n"+strings.Repeat(" ", len(start)+1), -1))
 		}
 	})
+	writer.Flush()
 }
 
 // PrintDefaults prints to standard error the default values of all defined command-line flags.

runconfig/parse.go

@@ -62,7 +62,7 @@ func parseRun(cmd *flag.FlagSet, args []string, sysInfo *sysinfo.SysInfo) (*Conf
 		flUser            = cmd.String([]string{"u", "-user"}, "", "Username or UID")
 		flWorkingDir      = cmd.String([]string{"w", "-workdir"}, "", "Working directory inside the container")
 		flCpuShares       = cmd.Int64([]string{"c", "-cpu-shares"}, 0, "CPU shares (relative weight)")
-		flNetMode         = cmd.String([]string{"-net"}, "bridge", "Set the Network mode for the container ('bridge': creates a new network stack for the container on the docker bridge, 'none': no networking for this container, 'container:<name|id>': reuses another container network stack), 'host': use the host network stack inside the container")
+		flNetMode         = cmd.String([]string{"-net"}, "bridge", "Set the Network mode for the container\n'bridge': creates a new network stack for the container on the docker bridge\n'none': no networking for this container\n'container:<name|id>': reuses another container network stack\n'host': use the host network stack inside the contaner")
 		// For documentation purpose
 		_ = cmd.Bool([]string{"#sig-proxy", "-sig-proxy"}, true, "Proxify all received signal to the process (even in non-tty mode)")
 		_ = cmd.String([]string{"#name", "-name"}, "", "Assign a name to the container")
@@ -74,7 +74,7 @@ func parseRun(cmd *flag.FlagSet, args []string, sysInfo *sysinfo.SysInfo) (*Conf
 	cmd.Var(&flEnv, []string{"e", "-env"}, "Set environment variables")
 	cmd.Var(&flEnvFile, []string{"-env-file"}, "Read in a line delimited file of ENV variables")
 
-	cmd.Var(&flPublish, []string{"p", "-publish"}, fmt.Sprintf("Publish a container's port to the host (format: %s) (use 'docker port' to see the actual mapping)", nat.PortSpecTemplateFormat))
+	cmd.Var(&flPublish, []string{"p", "-publish"}, fmt.Sprintf("Publish a container's port to the host\nformat: %s\n(use 'docker port' to see the actual mapping)", nat.PortSpecTemplateFormat))
 	cmd.Var(&flExpose, []string{"#expose", "-expose"}, "Expose a port from the container without publishing it to your host")
 	cmd.Var(&flDns, []string{"#dns", "-dns"}, "Set custom dns servers")
 	cmd.Var(&flDnsSearch, []string{"-dns-search"}, "Set custom dns search domains")