Fix 'docker ps --help' so the options don't span more than one line

and add a testcase to catch this in the future.

While in there I also:
- removed extra periods from the few options that had them (new test)
- made the --filter option consistent across all command

Signed-off-by: Doug Davis <dug@us.ibm.com>

api/client/commands.go

@@ -609,7 +609,7 @@ func (cli *DockerCli) CmdInfo(args ...string) error {
 
 func (cli *DockerCli) CmdStop(args ...string) error {
 	cmd := cli.Subcmd("stop", "CONTAINER [CONTAINER...]", "Stop a running container by sending SIGTERM and then SIGKILL after a\ngrace period", true)
-	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing it.")
+	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing it")
 	cmd.Require(flag.Min, 1)
 
 	utils.ParseFlags(cmd, args, true)
@@ -632,7 +632,7 @@ func (cli *DockerCli) CmdStop(args ...string) error {
 
 func (cli *DockerCli) CmdRestart(args ...string) error {
 	cmd := cli.Subcmd("restart", "CONTAINER [CONTAINER...]", "Restart a running container", true)
-	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing the container.")
+	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing the container")
 	cmd.Require(flag.Min, 1)
 
 	utils.ParseFlags(cmd, args, true)
@@ -847,7 +847,7 @@ func (cli *DockerCli) CmdRename(args ...string) error {
 
 func (cli *DockerCli) CmdInspect(args ...string) error {
 	cmd := cli.Subcmd("inspect", "CONTAINER|IMAGE [CONTAINER|IMAGE...]", "Return low-level information on a container or image", true)
-	tmplStr := cmd.String([]string{"f", "#format", "-format"}, "", "Format the output using the given go template.")
+	tmplStr := cmd.String([]string{"f", "#format", "-format"}, "", "Format the output using the given go template")
 	cmd.Require(flag.Min, 1)
 
 	utils.ParseFlags(cmd, args, true)
@@ -1161,7 +1161,7 @@ func (cli *DockerCli) CmdKill(args ...string) error {
 func (cli *DockerCli) CmdImport(args ...string) error {
 	cmd := cli.Subcmd("import", "URL|- [REPOSITORY[:TAG]]", "Create an empty filesystem image and import the contents of the\ntarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then\noptionally tag it.", true)
 	flChanges := opts.NewListOpts(nil)
-	cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image.")
+	cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image")
 	cmd.Require(flag.Min, 1)
 
 	utils.ParseFlags(cmd, args, true)
@@ -1333,7 +1333,7 @@ func (cli *DockerCli) CmdImages(args ...string) error {
 	flTree := cmd.Bool([]string{"#t", "#tree", "#-tree"}, false, "Output graph in tree format")
 
 	flFilter := opts.NewListOpts(nil)
-	cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values (i.e., 'dangling=true')")
+	cmd.Var(&flFilter, []string{"f", "-filter"}, "Filter output based on conditions provided")
 	cmd.Require(flag.Max, 1)
 
 	utils.ParseFlags(cmd, args, true)
@@ -1561,15 +1561,15 @@ func (cli *DockerCli) CmdPs(args ...string) error {
 		size     = cmd.Bool([]string{"s", "-size"}, false, "Display total file sizes")
 		all      = cmd.Bool([]string{"a", "-all"}, false, "Show all containers (default shows just running)")
 		noTrunc  = cmd.Bool([]string{"#notrunc", "-no-trunc"}, false, "Don't truncate output")
-		nLatest  = cmd.Bool([]string{"l", "-latest"}, false, "Show the latest created container, include non-running.")
-		since    = cmd.String([]string{"#sinceId", "#-since-id", "-since"}, "", "Show created since Id or Name, include non-running.")
-		before   = cmd.String([]string{"#beforeId", "#-before-id", "-before"}, "", "Show only container created before Id or Name.")
-		last     = cmd.Int([]string{"n"}, -1, "Show n last created containers, include non-running.")
+		nLatest  = cmd.Bool([]string{"l", "-latest"}, false, "Show the latest created container, include non-running")
+		since    = cmd.String([]string{"#sinceId", "#-since-id", "-since"}, "", "Show created since Id or Name, include non-running")
+		before   = cmd.String([]string{"#beforeId", "#-before-id", "-before"}, "", "Show only container created before Id or Name")
+		last     = cmd.Int([]string{"n"}, -1, "Show n last created containers, include non-running")
 		flFilter = opts.NewListOpts(nil)
 	)
 	cmd.Require(flag.Exact, 0)
 
-	cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values. Valid filters:\nexited=<int> - containers with exit code of <int>\nstatus=(restarting|running|paused|exited)")
+	cmd.Var(&flFilter, []string{"f", "-filter"}, "Filter output based on conditions provided")
 
 	utils.ParseFlags(cmd, args, true)
 	if *last == -1 && *nLatest {
@@ -1711,7 +1711,7 @@ func (cli *DockerCli) CmdCommit(args ...string) error {
 	flComment := cmd.String([]string{"m", "-message"}, "", "Commit message")
 	flAuthor := cmd.String([]string{"a", "#author", "-author"}, "", "Author (e.g., \"John Hannibal Smith <hannibal@a-team.com>\")")
 	flChanges := opts.NewListOpts(nil)
-	cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image.")
+	cmd.Var(&flChanges, []string{"c", "-change"}, "Apply Dockerfile instruction to the created image")
 	// FIXME: --run is deprecated, it will be replaced with inline Dockerfile commands.
 	flConfig := cmd.String([]string{"#run", "#-run"}, "", "This option is deprecated and will be removed in a future version in favor of inline Dockerfile-compatible commands")
 	cmd.Require(flag.Max, 2)
@@ -1771,7 +1771,7 @@ func (cli *DockerCli) CmdEvents(args ...string) error {
 	since := cmd.String([]string{"#since", "-since"}, "", "Show all events created since timestamp")
 	until := cmd.String([]string{"-until"}, "", "Stream events until this timestamp")
 	flFilter := opts.NewListOpts(nil)
-	cmd.Var(&flFilter, []string{"f", "-filter"}, "Provide filter values (i.e., 'event=stop')")
+	cmd.Var(&flFilter, []string{"f", "-filter"}, "Filter output based on conditions provided")
 	cmd.Require(flag.Exact, 0)
 
 	utils.ParseFlags(cmd, args, true)

docs/sources/reference/commandline/cli.md

@@ -26,7 +26,7 @@ To list the help on any command just execute the command, followed by the `--hel
 
     Run a command in a new container
 
-      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
+      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR
       -c, --cpu-shares=0         CPU shares (relative weight)
     ...
 
@@ -756,7 +756,7 @@ Creates a new container.
 
     Create a new container
 
-      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
+      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR
       --add-host=[]              Add a custom host-to-IP mapping (host:ip)
       -c, --cpu-shares=0         CPU shares (relative weight)
       --cap-add=[]               Add Linux capabilities
@@ -875,7 +875,7 @@ For example:
 
     Get real time events from the server
 
-      -f, --filter=[]    Provide filter values (i.e., 'event=stop')
+      -f, --filter=[]    Filter output based on conditions provided
       --since=""         Show all events created since timestamp
       --until=""         Stream events until this timestamp
 
@@ -1060,7 +1060,7 @@ To see how the `docker:latest` image was built:
     List images
 
       -a, --all=false      Show all images (default hides intermediate images)
-      -f, --filter=[]      Provide filter values (i.e., 'dangling=true')
+      -f, --filter=[]      Filter output based on conditions provided
       --no-trunc=false     Don't truncate output
       -q, --quiet=false    Only show numeric IDs
 
@@ -1241,7 +1241,7 @@ ensure we know how your setup is configured.
 
     Return low-level information on a container or image
 
-      -f, --format=""    Format the output using the given go template.
+      -f, --format=""    Format the output using the given go template
 
 By default, this will render all results in a JSON array. If a format is
 specified, the given template will be executed for each result.
@@ -1439,16 +1439,14 @@ The `docker rename` command allows the container to be renamed to a different na
     List containers
 
       -a, --all=false       Show all containers (default shows just running)
-      --before=""           Show only container created before Id or Name.
-      -f, --filter=[]       Provide filter values. Valid filters:
-                              exited=<int> - containers with exit code of <int>
-                              status=(restarting|running|paused|exited)
-      -l, --latest=false    Show the latest created container, include non-running.
-      -n=-1                 Show n last created containers, include non-running .
+      --before=""           Show only container created before Id or Name
+      -f, --filter=[]       Filter output based on conditions provided
+      -l, --latest=false    Show the latest created container, include non-running
+      -n=-1                 Show n last created containers, include non-running 
       --no-trunc=false      Don't truncate output
       -q, --quiet=false     Only display numeric IDs
       -s, --size=false      Display total file sizes
-      --since=""            Show created since Id or Name, include non-running.
+      --since=""            Show created since Id or Name, include non-running
 
 Running `docker ps --no-trunc` showing 2 linked containers.
 
@@ -1531,7 +1529,7 @@ registry or to a self-hosted one.
 
     Restart a running container
 
-      -t, --time=10      Seconds to wait for stop before killing the container.
+      -t, --time=10      Seconds to wait for stop before killing the container
 
 ## rm
 
@@ -1611,7 +1609,7 @@ removed before the image is removed.
 
     Run a command in a new container
 
-      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
+      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR
       --add-host=[]              Add a custom host-to-IP mapping (host:ip)
       -c, --cpu-shares=0         CPU shares (relative weight)
       --cap-add=[]               Add Linux capabilities
@@ -2066,7 +2064,7 @@ containers. Stopped containers will not return any data.
     Stop a running container by sending SIGTERM and then SIGKILL after a
 	grace period
 
-      -t, --time=10      Seconds to wait for stop before killing it.
+      -t, --time=10      Seconds to wait for stop before killing it
 
 The main process inside the container will receive `SIGTERM`, and after a
 grace period, `SIGKILL`.

integration-cli/docker_cli_help_test.go

@@ -11,7 +11,7 @@ import (
 	"github.com/docker/docker/pkg/homedir"
 )
 
-func TestHelpWidth(t *testing.T) {
+func TestHelpTextVerify(t *testing.T) {
 	// Make sure main help text fits within 80 chars and that
 	// on non-windows system we use ~ when possible (to shorten things).
 	// Test for HOME set to its default value and set to "/" on linux
@@ -58,6 +58,7 @@ func TestHelpWidth(t *testing.T) {
 			if len(line) > 80 {
 				t.Fatalf("Line is too long(%d chars):\n%s", len(line), line)
 			}
+
 			if scanForHome && strings.Contains(line, `=`+home) {
 				t.Fatalf("Line should use '%q' instead of %q:\n%s", homedir.GetShortcutString(), home, line)
 			}
@@ -108,6 +109,7 @@ func TestHelpWidth(t *testing.T) {
 					t.Fatalf("Help for %q is too long(%d chars):\n%s", cmd,
 						len(line), line)
 				}
+
 				if scanForHome && strings.Contains(line, `"`+home) {
 					t.Fatalf("Help for %q should use ~ instead of %q on:\n%s",
 						cmd, home, line)
@@ -116,6 +118,18 @@ func TestHelpWidth(t *testing.T) {
 				if i >= 0 && i != len(line)-1 && line[i+1] != '/' {
 					t.Fatalf("Help for %q should not have used ~:\n%s", cmd, line)
 				}
+
+				// If a line starts with 4 spaces then assume someone
+				// added a multi-line description for an option and we need
+				// to flag it
+				if strings.HasPrefix(line, "    ") {
+					t.Fatalf("Help for %q should not have a multi-line option: %s", cmd, line)
+				}
+
+				// Options should NOT end with a period
+				if strings.HasPrefix(line, "  -") && strings.HasSuffix(line, ".") {
+					t.Fatalf("Help for %q should not end with a period: %s", cmd, line)
+				}
 			}
 		}
 
@@ -126,5 +140,5 @@ func TestHelpWidth(t *testing.T) {
 		}
 	}
 
-	logDone("help - widths")
+	logDone("help - verify text")
 }

runconfig/parse.go

@@ -66,7 +66,7 @@ func Parse(cmd *flag.FlagSet, args []string) (*Config, *HostConfig, *flag.FlagSe
 		flReadonlyRootfs  = cmd.Bool([]string{"-read-only"}, false, "Mount the container's root filesystem as read only")
 	)
 
-	cmd.Var(&flAttach, []string{"a", "-attach"}, "Attach to STDIN, STDOUT or STDERR.")
+	cmd.Var(&flAttach, []string{"a", "-attach"}, "Attach to STDIN, STDOUT or STDERR")
 	cmd.Var(&flVolumes, []string{"v", "-volume"}, "Bind mount a volume")
 	cmd.Var(&flLinks, []string{"#link", "-link"}, "Add link to another container")
 	cmd.Var(&flDevices, []string{"-device"}, "Add a host device to the container")