Update the man page, and in the process, organize cmdline.py

2 files changed, 118 insertions, 39 deletions

diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index 448dd470..47a1601b 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -48,7 +48,7 @@ class Opts(object):
     )
     context = optparse.make_option(
         '', '--context', action='store', metavar="LABEL",
-        help="The context label to record for this coverage run",
+        help="The context label to record for this coverage run.",
     )
     debug = optparse.make_option(
         '', '--debug', action='store', metavar="OPTS",
@@ -95,7 +95,7 @@ class Opts(object):
     )
     skip_empty = optparse.make_option(
         '--skip-empty', action='store_true',
-        help="Skip empty files.",
+        help="Skip files with no code.",
     )
     show_contexts = optparse.make_option(
         '--show-contexts', action='store_true',
@@ -129,7 +129,7 @@ class Opts(object):
     )
     json_pretty_print = optparse.make_option(
         '', '--pretty-print', action='store_true',
-        help="Format the JSON for human readers",
+        help="Format the JSON for human readers.",
     )
     parallel_mode = optparse.make_option(
         '-p', '--parallel-mode', action='store_true',
@@ -150,8 +150,8 @@ class Opts(object):
         '', '--rcfile', action='store',
         help=(
             "Specify configuration file. "
-            "By default '.coveragerc', 'pyproject.toml', 'setup.cfg' and "
-            "'tox.ini' are tried. [env: COVERAGE_RCFILE]"
+            "By default '.coveragerc', 'setup.cfg', 'tox.ini', and "
+            "'pyproject.toml' are tried. [env: COVERAGE_RCFILE]"
         ),
     )
     source = optparse.make_option(
@@ -352,16 +352,16 @@ CMDS = {
     'html': CmdOptionParser(
         "html",
         [
+            Opts.contexts,
             Opts.directory,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
             Opts.omit,
-            Opts.title,
+            Opts.show_contexts,
             Opts.skip_covered,
             Opts.skip_empty,
-            Opts.show_contexts,
-            Opts.contexts,
+            Opts.title,
             ] + GLOBAL_ARGS,
         usage="[options] [modules]",
         description=(
@@ -371,14 +371,30 @@ CMDS = {
         ),
     ),
 
+    'json': CmdOptionParser(
+        "json",
+        [
+            Opts.contexts,
+            Opts.fail_under,
+            Opts.ignore_errors,
+            Opts.include,
+            Opts.omit,
+            Opts.output_json,
+            Opts.json_pretty_print,
+            Opts.show_contexts,
+            ] + GLOBAL_ARGS,
+        usage="[options] [modules]",
+        description="Generate a JSON report of coverage results."
+    ),
+
     'report': CmdOptionParser(
         "report",
         [
+            Opts.contexts,
             Opts.fail_under,
             Opts.ignore_errors,
             Opts.include,
             Opts.omit,
-            Opts.contexts,
             Opts.show_missing,
             Opts.skip_covered,
             Opts.skip_empty,
@@ -418,22 +434,6 @@ CMDS = {
         usage="[options] [modules]",
         description="Generate an XML report of coverage results."
     ),
-
-    'json': CmdOptionParser(
-        "json",
-        [
-            Opts.fail_under,
-            Opts.ignore_errors,
-            Opts.include,
-            Opts.omit,
-            Opts.output_json,
-            Opts.json_pretty_print,
-            Opts.show_contexts,
-            Opts.contexts,
-            ] + GLOBAL_ARGS,
-        usage="[options] [modules]",
-        description="Generate a JSON report of coverage results."
-    ),
 }
 
 
diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt
index 1a06bf2e..27ab1924 100644
--- a/doc/python-coverage.1.txt
+++ b/doc/python-coverage.1.txt
@@ -8,7 +8,7 @@ measure code coverage of Python program execution
 
 :Author: Ned Batchelder <ned@nedbatchelder.com>
 :Author: |author|
-:Date: 2019-06-11
+:Date: 2019-11-11
 :Copyright: Apache 2.0 license, attribution and disclaimer required.
 :Manual section: 1
 :Manual group: Coverage.py
@@ -52,6 +52,9 @@ COMMAND OVERVIEW
 |command| **html**
     Create an HTML report.
 
+|command| **json**
+    Create a JSON report of coverage results.
+
 |command| **report**
     Report coverage stats on modules.
 
@@ -69,15 +72,8 @@ GLOBAL OPTIONS
     Describe how to use coverage.py, in general or a command.
 
 **--rcfile** `RCFILE`
-    Specify configuration file `RCFILE`. Defaults to ``.coveragerc``.
-
-**--omit** `PATTERN` [ , ... ]
-    Omit files when their file name matches one of these PATTERNs.
-    Usually needs quoting on the command line.
-
-**--include** `PATTERN` [ , ... ]
-    Include only files whose paths match one of these
-    PATTERNs. Accepts shell-style wildcards, which must be quoted.
+    Specify configuration file `RCFILE`.  By default '.coveragerc',
+    'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
 
 **--debug** `DEBUGOPT`,...
     Debug options `DEBUGOPT`, separated by commas.
@@ -97,6 +93,14 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
 **combine** [ `option` ... ] [ `PATH` ... ]
 
     Combine data from multiple coverage files collected with ``run -p``.
@@ -128,8 +132,8 @@ COMMAND REFERENCE
 
     Options:
 
-    \--contexts `PAT,...`
-        Only include contexts that match one of the patterns.
+    \--contexts `PAT` [ , ... ]
+        Only include contexts that match one of the regex patterns.
 
     \-d `DIR`, --directory `DIR`
         Write the output files to `DIR`.
@@ -140,23 +144,65 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \--show-contexts
         Annotate lines with the contexts that executed them.
 
     \--skip-covered
         Skip files with 100% coverage.
 
+    \--skip-empty
+        Skip files with no code.
+
     \--title `TITLE`
         Use the text string `TITLE` as the title on the HTML.
 
+**json** [ `option` ... ] [ `MODULE` ... ]
+
+    Generate a JSON report of coverage results.
+
+    \--contexts `PAT` [ , ... ]
+        Only include contexts that match one of the regex patterns.
+
+    \--fail-under `MIN`
+        Exit with a status of 2 if the total coverage is less than `MIN`.
+
+    \-i, --ignore-errors
+        Ignore errors while reading source files.
+
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \-o `OUTFILE`
+        Write the JSON report to `OUTFILE`. Defaults to ``coverage.json``.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
+    \--pretty-print
+        Format the JSON for human readers.
+
+    \--show-contexts
+        Include information about the contexts that executed each line.
+
+
 **report** [ `option` ... ] [ `MODULE` ... ]
 
     Report coverage statistics on each `MODULE`.
 
     Options:
 
-    \--contexts `PAT,...`
-        Only include contexts that match one of the patterns.
+    \--contexts `PAT` [ , ... ]
+        Only include contexts that match one of the regex patterns.
 
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.
@@ -164,6 +210,14 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \-m, --show-missing
         Show line numbers of statements in each module that weren't
         executed.
@@ -171,6 +225,9 @@ COMMAND REFERENCE
     \--skip-covered
         Skip files with 100% coverage.
 
+    \--skip-empty
+        Skip files with no code.
+
 **run** [ `options` ... ] `PROGRAMFILE` [ `program_options` ]
 
     Run a Python program `PROGRAMFILE`, measuring code execution.
@@ -188,6 +245,20 @@ COMMAND REFERENCE
         Properly measure code using a concurrency library. Valid values are:
         thread, gevent, greenlet, eventlet, multiprocessing.
 
+    \--context `CONTEXT`
+        The context label to record for this coverage run.
+
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \-m
+        `PROGRAMFILE` is interpreted as a module name.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \-L, --pylib
         Measure coverage even inside the Python installed library, which
         isn't done by default.
@@ -216,6 +287,14 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \-o `OUTFILE`
         Write the XML report to `OUTFILE`. Defaults to ``coverage.xml``.