Various manpage / usage blurb improvements

Corrections, clarifications, consistency.

Not a comprehensive overhaul of the manpages; they do still need work.
These are just flaws I've noted while studying the ostree command syntax.

https://bugzilla.gnome.org/show_bug.cgi?id=740097

23 files changed, 69 insertions, 61 deletions

diff --git a/doc/ostree-admin-config-diff.xml b/doc/ostree-admin-config-diff.xml
index dd1d17a8..f1d18603 100644
--- a/doc/ostree-admin-config-diff.xml
+++ b/doc/ostree-admin-config-diff.xml
@@ -69,7 +69,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--os</option>="OSNAME"</term>
 
                 <listitem><para>
-                    If provided, specifies the operating system root. Default is the current one.
+                    Use a different operating system root than the current one.
                 </para></listitem>
             </varlistentry>
         </variablelist>
diff --git a/doc/ostree-admin-deploy.xml b/doc/ostree-admin-deploy.xml
index 2754122a..f08f443a 100644
--- a/doc/ostree-admin-deploy.xml
+++ b/doc/ostree-admin-deploy.xml
@@ -69,7 +69,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--os</option>="OSNAME"</term>
 
                 <listitem><para>
-                    If provided, specifies the operating system root. Default is the current one.
+                    Use a different operating system root than the current one.
                 </para></listitem>
             </varlistentry>
 
@@ -98,7 +98,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--karg</option>="KEY=VALUE"</term>
+                <term><option>--karg</option>="NAME=VALUE"</term>
 
                 <listitem><para>
                     Set kernel argument, like root=/dev/sda1; this overrides any earlier argument with the same name.
@@ -106,7 +106,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--karg-append</option>="KEY=VALUE"</term>
+                <term><option>--karg-append</option>="NAME=VALUE"</term>
 
                 <listitem><para>
                     Append kernel argument; useful with e.g. console= that can be used multiple times.
diff --git a/doc/ostree-admin-instutil.xml b/doc/ostree-admin-instutil.xml
index 3481384f..4f2ff164 100644
--- a/doc/ostree-admin-instutil.xml
+++ b/doc/ostree-admin-instutil.xml
@@ -67,21 +67,21 @@ Boston, MA 02111-1307, USA.
 
         <variablelist>
             <varlistentry>
-                <term><command>selinux-ensure-labeled</command></term>
+                <term><command>selinux-ensure-labeled <arg choice="opt">SUBPATH PREFIX</arg></command></term>
 
                 <listitem><para>
-                    Ensure all files and directories are labeled according to SELinux policy of the first deployment.  First argument is the subpath and second argument is the prefix.
+                    Ensure all files and directories are labeled according to SELinux policy of the first deployment.
                 </para></listitem>
             </varlistentry>
 
             <varlistentry>
-                <term><command>set-kargs <arg choice="opt">--merge</arg> <arg choice="opt">--import-proc-cmdline</arg> <arg choice="opt">--append=ARG</arg> <arg choice="opt">--replace=ARG</arg> <arg choice="opt">MORE_APPEND_ARGS</arg></command></term>
+                <term><command>set-kargs <arg choice="opt">--merge</arg> <arg choice="opt">--import-proc-cmdline</arg> <arg choice="opt">--append="NAME=VALUE"</arg> <arg choice="opt">--replace="NAME=VALUE"</arg> <arg choice="opt">MORE_APPEND_ARGS</arg></command></term>
 
                 <listitem><para>
                     Replace the kernel arguments of the default deployment. The new arguments are based
                     on an empty list (the default), the current options (--merge), or the arguments
                     of the loaded kernel (--import-proc-cmdline), and new options either are added to the
-                    end (--append=ARG) or replace existing arguments of the same name (--replace=ARG).
+                    end (--append="NAME=VALUE") or replace existing arguments of the same name (--replace="NAME=VALUE").
                 </para></listitem>
             </varlistentry>
         </variablelist>
diff --git a/doc/ostree-admin-switch.xml b/doc/ostree-admin-switch.xml
index 4a09b711..e26da1bc 100644
--- a/doc/ostree-admin-switch.xml
+++ b/doc/ostree-admin-switch.xml
@@ -69,7 +69,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--os</option>="OSNAME"</term>
 
                 <listitem><para>
-                    If provided, specifies the operating system root. Default is the current one.
+                    Use a different operating system root than the current one.
                 </para></listitem>
             </varlistentry>
         </variablelist>
diff --git a/doc/ostree-admin-upgrade.xml b/doc/ostree-admin-upgrade.xml
index ab2672b4..01050a56 100644
--- a/doc/ostree-admin-upgrade.xml
+++ b/doc/ostree-admin-upgrade.xml
@@ -69,7 +69,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--os</option>="OSNAME"</term>
 
                 <listitem><para>
-                    If provided, specifies the operating system root. Default is the current one.
+                    Use a different operating system root than the current one.
                 </para></listitem>
             </varlistentry>
 
diff --git a/doc/ostree-cat.xml b/doc/ostree-cat.xml
index c8ec1c9c..068c0e15 100644
--- a/doc/ostree-cat.xml
+++ b/doc/ostree-cat.xml
@@ -49,7 +49,7 @@ Boston, MA 02111-1307, USA.
 
     <refsynopsisdiv>
             <cmdsynopsis>
-                <command>ostree cat <arg choice="req">COMMIT</arg> <arg choice="req">PATH</arg> <arg choice="opt">PATH</arg></command>
+                <command>ostree cat <arg choice="req">COMMIT</arg> <arg choice="req" rep="repeat">PATH</arg></command>
             </cmdsynopsis>
     </refsynopsisdiv>
 
diff --git a/doc/ostree-checksum.xml b/doc/ostree-checksum.xml
index a6ed8956..c4b5bee9 100644
--- a/doc/ostree-checksum.xml
+++ b/doc/ostree-checksum.xml
@@ -49,7 +49,7 @@ Boston, MA 02111-1307, USA.
 
     <refsynopsisdiv>
             <cmdsynopsis>
-                <command>ostree checksum <arg choice="req">FILE</arg></command>
+                <command>ostree checksum <arg choice="req">PATH</arg></command>
             </cmdsynopsis>
     </refsynopsisdiv>
 
diff --git a/doc/ostree-commit.xml b/doc/ostree-commit.xml
index 4469ce51..995a84fe 100644
--- a/doc/ostree-commit.xml
+++ b/doc/ostree-commit.xml
@@ -49,7 +49,7 @@ Boston, MA 02111-1307, USA.
 
     <refsynopsisdiv>
             <cmdsynopsis>
-                <command>ostree commit <arg choice="opt" rep="repeat">OPTIONS</arg> --branch=<arg choice="req">BRANCH</arg> </command>
+                <command>ostree commit <arg choice="opt" rep="repeat">OPTIONS</arg> --branch=<arg choice="req">BRANCH</arg> <arg choice="opt">PATH</arg></command>
             </cmdsynopsis>
     </refsynopsisdiv>
 
@@ -65,7 +65,7 @@ Boston, MA 02111-1307, USA.
         <title>Options</title>
         <variablelist>
             <varlistentry>
-                <term><option>--subject</option>, <option>-s</option>="subject"</term>
+                <term><option>--subject</option>, <option>-s</option>="SUBJECT"</term>
 
                 <listitem><para>
                     One line subject.
@@ -73,7 +73,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--body</option>, <option>-m</option>="body"</term>
+                <term><option>--body</option>, <option>-m</option>="BODY"</term>
 
                 <listitem><para>
                     Full description.
@@ -81,7 +81,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--branch</option>, <option>-b</option>="branch"</term>
+                <term><option>--branch</option>, <option>-b</option>="BRANCH"</term>
 
                 <listitem><para>
                     Branch.
@@ -89,7 +89,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--tree</option>="NAME"</term>
+                <term><option>--tree</option>="dir=PATH" or "tar=TARFILE" or "ref=COMMIT"</term>
 
                 <listitem><para>
                     Overlay the given argument as a tree.
@@ -100,7 +100,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--add-metadata-string</option>="KEY=VALUE"</term>
 
                 <listitem><para>
-                    Append given key and value (in string format) to metadata.
+                    Add a key/value pair to metadata.
                 </para></listitem>
             </varlistentry>
 
@@ -108,7 +108,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--add-detached-metadata-string</option>="KEY=VALUE"</term>
 
                 <listitem><para>
-                    Append given key and value (in string format) to detached metadata.
+                    Add a key/value pair to detached metadata.
                 </para></listitem>
             </varlistentry>
 
@@ -184,7 +184,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--gpg-sign</option>="key-id"</term>
+                <term><option>--gpg-sign</option>="KEY-ID"</term>
 
                 <listitem><para>
                     GPG Key ID with which to sign the commit (if have GPGME - GNU Privacy Guard Made Easy).
@@ -192,7 +192,7 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--gpg-homedir</option>="homedir"</term>
+                <term><option>--gpg-homedir</option>="HOMEDIR"</term>
 
                 <listitem><para>
                     GPG home directory to use when looking for keyrings (if have GPGME - GNU Privacy Guard Made Easy).
diff --git a/doc/ostree-config.xml b/doc/ostree-config.xml
index c2b2f09d..b0c0d48b 100644
--- a/doc/ostree-config.xml
+++ b/doc/ostree-config.xml
@@ -49,7 +49,10 @@ Boston, MA 02111-1307, USA.
 
     <refsynopsisdiv>
             <cmdsynopsis>
-                <command>ostree config <arg choice="req">OPERATION</arg> <arg choice="opt">KEY</arg> <arg choice="opt">VALUE</arg></command>
+                <command>ostree config get <arg choice="req">SECTIONNAME.KEYNAME</arg></command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+                <command>ostree config set <arg choice="req">SECTIONNAME.KEYNAME</arg> <arg choice="req">VALUE</arg></command>
             </cmdsynopsis>
     </refsynopsisdiv>
 
@@ -57,14 +60,13 @@ Boston, MA 02111-1307, USA.
         <title>Description</title>
 
         <para>
-            Changes the configuration settings.  Possible operations inlclude either "set" or "get".  If OPERATION is "set", KEY and VALUE are required.  If OPERATION is "get", only KEY is necessary.  KEY must be of the form "sectionname.keyname".
+            Displays or changes a configuration setting.
         </para>
     </refsect1>
 
-<!-- Need a REAL example here - what is an example of a section name and a key name?-->
     <refsect1>
         <title>Example</title>
-        <para><command>$ ostree config get sectionname.keyname</command></para>
-        keyvalue
+        <para><command>$ ostree config get core.mode</command></para>
+        <para>bare</para>
     </refsect1>
 </refentry>
diff --git a/doc/ostree-remote.xml b/doc/ostree-remote.xml
index 6d594c69..e42178f1 100644
--- a/doc/ostree-remote.xml
+++ b/doc/ostree-remote.xml
@@ -49,7 +49,13 @@ Boston, MA 02111-1307, USA.
 
     <refsynopsisdiv>
             <cmdsynopsis>
-                <command>ostree remote <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">OPERATION</arg> <arg choice="req">NAME</arg> <arg choice="opt">args</arg></command>
+                <command>ostree remote <arg choice="opt" rep="repeat">OPTIONS</arg> add <arg choice="req">NAME</arg> <arg choice="req">URL</arg> <arg choice="opt" rep="repeat">BRANCH</arg></command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+                <command>ostree remote delete <arg choice="req">NAME</arg></command>
+            </cmdsynopsis>
+            <cmdsynopsis>
+                <command>ostree remote show-url <arg choice="req">NAME</arg></command>
             </cmdsynopsis>
     </refsynopsisdiv>
 
@@ -57,7 +63,7 @@ Boston, MA 02111-1307, USA.
         <title>Description</title>
 
         <para>
-            Changes remote respository configurations.  Possible operations include either "add" or "show-url".  If OPERATION is "add", a URL must be specified in [args].  The NAME refers to the name of the remote.
+            Changes remote respository configurations.  The NAME refers to the name of the remote.
         </para>
     </refsect1>
 
diff --git a/doc/ostree-show.xml b/doc/ostree-show.xml
index b2ee463d..df573f8c 100644
--- a/doc/ostree-show.xml
+++ b/doc/ostree-show.xml
@@ -74,10 +74,10 @@ Boston, MA 02111-1307, USA.
             </varlistentry>
 
             <varlistentry>
-                <term><option>--print-variant-type</option>="FILENAME"</term>
+                <term><option>--print-variant-type</option>="TYPE"</term>
 
                 <listitem><para>
-                    Argument should be a filename and it will be interpreted as this type.
+                    Memory map <arg choice="req">OBJECT</arg> (in this case a filename) to the GVariant type string.
                 </para></listitem>
             </varlistentry>
 
@@ -85,7 +85,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--print-metadata-key</option>="KEY"</term>
 
                 <listitem><para>
-                    Print string value of metadata key KEY for given commit.
+                    Print string value of metadata key.
                 </para></listitem>
             </varlistentry>
 
@@ -93,7 +93,7 @@ Boston, MA 02111-1307, USA.
                 <term><option>--print-detached-metadata-key</option>="KEY"</term>
 
                 <listitem><para>
-                    Print string value of detached metadata key KEY for given commit.
+                    Print string value of detached metadata key.
                 </para></listitem>
             </varlistentry>
 
diff --git a/src/ostree/ot-admin-builtin-deploy.c b/src/ostree/ot-admin-builtin-deploy.c
index d255f8b8..3584dee1 100644
--- a/src/ostree/ot-admin-builtin-deploy.c
+++ b/src/ostree/ot-admin-builtin-deploy.c
@@ -39,12 +39,12 @@ static char *opt_osname;
 static char *opt_origin_path;
 
 static GOptionEntry options[] = {
-  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Specify operating system root to use", NULL },
-  { "origin-file", 0, 0, G_OPTION_ARG_FILENAME, &opt_origin_path, "Specify origin file", NULL },
+  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Use a different operating system root than the current one", "OSNAME" },
+  { "origin-file", 0, 0, G_OPTION_ARG_FILENAME, &opt_origin_path, "Specify origin file", "FILENAME" },
   { "retain", 0, 0, G_OPTION_ARG_NONE, &opt_retain, "Do not delete previous deployment", NULL },
   { "karg-proc-cmdline", 0, 0, G_OPTION_ARG_NONE, &opt_kernel_proc_cmdline, "Import current /proc/cmdline", NULL },
-  { "karg", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_kernel_argv, "Set kernel argument, like root=/dev/sda1; this overrides any earlier argument with the same name", "KEY=VALUE" },
-  { "karg-append", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_kernel_argv_append, "Append kernel argument; useful with e.g. console= that can be used multiple times", "KEY=VALUE" },
+  { "karg", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_kernel_argv, "Set kernel argument, like root=/dev/sda1; this overrides any earlier argument with the same name", "NAME=VALUE" },
+  { "karg-append", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_kernel_argv_append, "Append kernel argument; useful with e.g. console= that can be used multiple times", "NAME=VALUE" },
   { NULL }
 };
 
diff --git a/src/ostree/ot-admin-builtin-diff.c b/src/ostree/ot-admin-builtin-diff.c
index 6623b512..2e9abc0f 100644
--- a/src/ostree/ot-admin-builtin-diff.c
+++ b/src/ostree/ot-admin-builtin-diff.c
@@ -32,7 +32,7 @@
 static char *opt_osname;
 
 static GOptionEntry options[] = {
-  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Specify operating system root to use", NULL },
+  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Use a different operating system root than the current one", "OSNAME" },
   { NULL }
 };
 
diff --git a/src/ostree/ot-admin-builtin-switch.c b/src/ostree/ot-admin-builtin-switch.c
index 5995e33b..3900b81c 100644
--- a/src/ostree/ot-admin-builtin-switch.c
+++ b/src/ostree/ot-admin-builtin-switch.c
@@ -35,7 +35,7 @@ static gboolean opt_reboot;
 static char *opt_osname;
 
 static GOptionEntry options[] = {
-  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Specify operating system root to use", NULL },
+  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Use a different operating system root than the current one", "OSNAME" },
   { NULL }
 };
 
diff --git a/src/ostree/ot-admin-builtin-upgrade.c b/src/ostree/ot-admin-builtin-upgrade.c
index 46acfbc3..ffb93d4a 100644
--- a/src/ostree/ot-admin-builtin-upgrade.c
+++ b/src/ostree/ot-admin-builtin-upgrade.c
@@ -38,7 +38,7 @@ static gboolean opt_allow_downgrade;
 static char *opt_osname;
 
 static GOptionEntry options[] = {
-  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Specify operating system root to use", NULL },
+  { "os", 0, 0, G_OPTION_ARG_STRING, &opt_osname, "Use a different operating system root than the current one", "OSNAME" },
   { "reboot", 'r', 0, G_OPTION_ARG_NONE, &opt_reboot, "Reboot after a successful upgrade", NULL },
   { "allow-downgrade", 0, 0, G_OPTION_ARG_NONE, &opt_allow_downgrade, "Permit deployment of chronologically older trees", NULL },
   { NULL }
diff --git a/src/ostree/ot-admin-instutil-builtin-grub2-generate.c b/src/ostree/ot-admin-instutil-builtin-grub2-generate.c
index 0b00cf97..4aa58d01 100644
--- a/src/ostree/ot-admin-instutil-builtin-grub2-generate.c
+++ b/src/ostree/ot-admin-instutil-builtin-grub2-generate.c
@@ -43,7 +43,7 @@ ot_admin_instutil_builtin_grub2_generate (int argc, char **argv, OstreeSysroot *
   GOptionContext *context = NULL;
   gs_unref_object GFile *deployment_path = NULL;
 
-  context = g_option_context_new ("BOOTVERSION - generate GRUB2 configuration from given BLS entries");
+  context = g_option_context_new ("[BOOTVERSION] - generate GRUB2 configuration from given BLS entries");
 
   g_option_context_add_main_entries (context, options, NULL);
 
diff --git a/src/ostree/ot-admin-instutil-builtin-set-kargs.c b/src/ostree/ot-admin-instutil-builtin-set-kargs.c
index 214e4661..b683f19c 100644
--- a/src/ostree/ot-admin-instutil-builtin-set-kargs.c
+++ b/src/ostree/ot-admin-instutil-builtin-set-kargs.c
@@ -37,8 +37,8 @@ static char **opt_append;
 static GOptionEntry options[] = {
   { "import-proc-cmdline", 0, 0, G_OPTION_ARG_NONE, &opt_proc_cmdline, "Import current /proc/cmdline", NULL },
   { "merge", 0, 0, G_OPTION_ARG_NONE, &opt_merge, "Merge with previous command line", NULL },
-  { "replace", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_replace, "Set kernel argument, like root=/dev/sda1; this overrides any earlier argument with the same name", "KEY=VALUE" },
-  { "append", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_append, "Append kernel argument; useful with e.g. console= that can be used multiple times", "KEY=VALUE" },
+  { "replace", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_replace, "Set kernel argument, like root=/dev/sda1; this overrides any earlier argument with the same name", "NAME=VALUE" },
+  { "append", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_append, "Append kernel argument; useful with e.g. console= that can be used multiple times", "NAME=VALUE" },
   { NULL }
 };
 
diff --git a/src/ostree/ot-builtin-cat.c b/src/ostree/ot-builtin-cat.c
index c4973e2f..92d4c840 100644
--- a/src/ostree/ot-builtin-cat.c
+++ b/src/ostree/ot-builtin-cat.c
@@ -65,7 +65,7 @@ ostree_builtin_cat (int argc, char **argv, OstreeRepo *repo, GCancellable *cance
   gs_unref_object GFile *root = NULL;
   gs_unref_object GFile *f = NULL;
 
-  context = g_option_context_new ("COMMIT PATH [PATH...] - Concatenate contents of files");
+  context = g_option_context_new ("COMMIT PATH... - Concatenate contents of files");
   g_option_context_add_main_entries (context, options, NULL);
 
   if (!g_option_context_parse (context, &argc, &argv, error))
diff --git a/src/ostree/ot-builtin-checkout.c b/src/ostree/ot-builtin-checkout.c
index fae461f0..3f776192 100644
--- a/src/ostree/ot-builtin-checkout.c
+++ b/src/ostree/ot-builtin-checkout.c
@@ -42,7 +42,7 @@ static GOptionEntry options[] = {
   { "union", 0, 0, G_OPTION_ARG_NONE, &opt_union, "Keep existing directories, overwrite existing files", NULL },
   { "allow-noent", 0, 0, G_OPTION_ARG_NONE, &opt_allow_noent, "Do nothing if specified path does not exist", NULL },
   { "from-stdin", 0, 0, G_OPTION_ARG_NONE, &opt_from_stdin, "Process many checkouts from standard input", NULL },
-  { "from-file", 0, 0, G_OPTION_ARG_STRING, &opt_from_file, "Process many checkouts from input file", NULL },
+  { "from-file", 0, 0, G_OPTION_ARG_STRING, &opt_from_file, "Process many checkouts from input file", "FILE" },
   { NULL }
 };
 
@@ -179,7 +179,7 @@ ostree_builtin_checkout (int argc, char **argv, OstreeRepo *repo, GCancellable *
   gs_free char *resolved_commit = NULL;
   gs_unref_object GFile *checkout_target = NULL;
 
-  context = g_option_context_new ("COMMIT DESTINATION - Check out a commit into a filesystem tree");
+  context = g_option_context_new ("COMMIT [DESTINATION] - Check out a commit into a filesystem tree");
   g_option_context_add_main_entries (context, options, NULL);
 
   if (!g_option_context_parse (context, &argc, &argv, error))
diff --git a/src/ostree/ot-builtin-checksum.c b/src/ostree/ot-builtin-checksum.c
index c210c50e..e7d5dd87 100644
--- a/src/ostree/ot-builtin-checksum.c
+++ b/src/ostree/ot-builtin-checksum.c
@@ -63,7 +63,7 @@ ostree_builtin_checksum (int argc, char **argv, OstreeRepo *repo, GCancellable *
   gs_unref_object GFile *f = NULL;
   AsyncChecksumData data = { 0, };
 
-  context = g_option_context_new ("FILENAME - Checksum a file or directory");
+  context = g_option_context_new ("PATH - Checksum a file or directory");
   g_option_context_add_main_entries (context, options, NULL);
 
   if (!g_option_context_parse (context, &argc, &argv, error))
diff --git a/src/ostree/ot-builtin-commit.c b/src/ostree/ot-builtin-commit.c
index bd31427e..eda556e9 100644
--- a/src/ostree/ot-builtin-commit.c
+++ b/src/ostree/ot-builtin-commit.c
@@ -83,23 +83,23 @@ static gboolean opt__fsync(const gchar *option_name,
 }
 
 static GOptionEntry options[] = {
-  { "subject", 's', 0, G_OPTION_ARG_STRING, &opt_subject, "One line subject", "subject" },
-  { "body", 'm', 0, G_OPTION_ARG_STRING, &opt_body, "Full description", "body" },
-  { "branch", 'b', 0, G_OPTION_ARG_STRING, &opt_branch, "Branch", "branch" },
-  { "tree", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_trees, "Overlay the given argument as a tree", "NAME" },
-  { "add-metadata-string", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_metadata_strings, "Append given key and value (in string format) to metadata", "KEY=VALUE" },
-  { "add-detached-metadata-string", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_detached_metadata_strings, "Append given key and value (in string format) to detached metadata", "KEY=VALUE" },
+  { "subject", 's', 0, G_OPTION_ARG_STRING, &opt_subject, "One line subject", "SUBJECT" },
+  { "body", 'm', 0, G_OPTION_ARG_STRING, &opt_body, "Full description", "BODY" },
+  { "branch", 'b', 0, G_OPTION_ARG_STRING, &opt_branch, "Branch", "BRANCH" },
+  { "tree", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_trees, "Overlay the given argument as a tree", "dir=PATH or tar=TARFILE or ref=COMMIT" },
+  { "add-metadata-string", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_metadata_strings, "Add a key/value pair to metadata", "KEY=VALUE" },
+  { "add-detached-metadata-string", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_detached_metadata_strings, "Add a key/value pair to detached metadata", "KEY=VALUE" },
   { "owner-uid", 0, 0, G_OPTION_ARG_INT, &opt_owner_uid, "Set file ownership user id", "UID" },
   { "owner-gid", 0, 0, G_OPTION_ARG_INT, &opt_owner_gid, "Set file ownership group id", "GID" },
   { "no-xattrs", 0, 0, G_OPTION_ARG_NONE, &opt_no_xattrs, "Do not import extended attributes", NULL },
   { "link-checkout-speedup", 0, 0, G_OPTION_ARG_NONE, &opt_link_checkout_speedup, "Optimize for commits of trees composed of hardlinks into the repository", NULL },
   { "tar-autocreate-parents", 0, 0, G_OPTION_ARG_NONE, &opt_tar_autocreate_parents, "When loading tar archives, automatically create parent directories as needed", NULL },
   { "skip-if-unchanged", 0, 0, G_OPTION_ARG_NONE, &opt_skip_if_unchanged, "If the contents are unchanged from previous commit, do nothing", NULL },
-  { "statoverride", 0, 0, G_OPTION_ARG_FILENAME, &opt_statoverride_file, "File containing list of modifications to make to permissions", "path" },
+  { "statoverride", 0, 0, G_OPTION_ARG_FILENAME, &opt_statoverride_file, "File containing list of modifications to make to permissions", "PATH" },
   { "table-output", 0, 0, G_OPTION_ARG_NONE, &opt_table_output, "Output more information in a KEY: VALUE format", NULL },
 #ifdef HAVE_GPGME
-  { "gpg-sign", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_key_ids, "GPG Key ID to sign the commit with", "key-id"},
-  { "gpg-homedir", 0, 0, G_OPTION_ARG_STRING, &opt_gpg_homedir, "GPG Homedir to use when looking for keyrings", "homedir"},
+  { "gpg-sign", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_key_ids, "GPG Key ID to sign the commit with", "KEY-ID"},
+  { "gpg-homedir", 0, 0, G_OPTION_ARG_STRING, &opt_gpg_homedir, "GPG Homedir to use when looking for keyrings", "HOMEDIR"},
 #endif
   { "generate-sizes", 0, 0, G_OPTION_ARG_NONE, &opt_generate_sizes, "Generate size information along with commit metadata", NULL },
   { "disable-fsync", 0, G_OPTION_FLAG_HIDDEN, G_OPTION_ARG_NONE, &opt_disable_fsync, "Do not invoke fsync()", NULL },
@@ -327,7 +327,7 @@ ostree_builtin_commit (int argc, char **argv, OstreeRepo *repo, GCancellable *ca
   OstreeRepoCommitModifier *modifier = NULL;
   OstreeRepoTransactionStats stats;
 
-  context = g_option_context_new ("[ARG] - Commit a new revision");
+  context = g_option_context_new ("[PATH] - Commit a new revision");
   g_option_context_add_main_entries (context, options, NULL);
 
   if (!g_option_context_parse (context, &argc, &argv, error))
diff --git a/src/ostree/ot-builtin-ls.c b/src/ostree/ot-builtin-ls.c
index b4d5ac9c..f0a85be5 100644
--- a/src/ostree/ot-builtin-ls.c
+++ b/src/ostree/ot-builtin-ls.c
@@ -247,7 +247,7 @@ ostree_builtin_ls (int argc, char **argv, OstreeRepo *repo, GCancellable *cancel
   int i;
   gs_unref_object GFile *root = NULL;
 
-  context = g_option_context_new ("COMMIT PATH [PATH...] - List file paths");
+  context = g_option_context_new ("COMMIT [PATH...] - List file paths");
   g_option_context_add_main_entries (context, options, NULL);
 
   if (!g_option_context_parse (context, &argc, &argv, error))
diff --git a/src/ostree/ot-builtin-show.c b/src/ostree/ot-builtin-show.c
index 9f4568e9..4b877828 100644
--- a/src/ostree/ot-builtin-show.c
+++ b/src/ostree/ot-builtin-show.c
@@ -34,10 +34,10 @@ static char* opt_print_detached_metadata_key;
 static gboolean opt_raw;
 
 static GOptionEntry options[] = {
-  { "print-related", 0, 0, G_OPTION_ARG_NONE, &opt_print_related, "If given, show the \"related\" commits", NULL },
-  { "print-variant-type", 0, 0, G_OPTION_ARG_STRING, &opt_print_variant_type, "If given, argument should be a filename and it will be interpreted as this type", NULL },
-  { "print-metadata-key", 0, 0, G_OPTION_ARG_STRING, &opt_print_metadata_key, "Print string value of metadata key KEY for given commit", "KEY" },
-  { "print-detached-metadata-key", 0, 0, G_OPTION_ARG_STRING, &opt_print_detached_metadata_key, "Print string value of detached metadata key KEY for given commit", "KEY" },
+  { "print-related", 0, 0, G_OPTION_ARG_NONE, &opt_print_related, "Show the \"related\" commits", NULL },
+  { "print-variant-type", 0, 0, G_OPTION_ARG_STRING, &opt_print_variant_type, "Memory map OBJECT (in this case a filename) to the GVariant type string", "TYPE" },
+  { "print-metadata-key", 0, 0, G_OPTION_ARG_STRING, &opt_print_metadata_key, "Print string value of metadata key", "KEY" },
+  { "print-detached-metadata-key", 0, 0, G_OPTION_ARG_STRING, &opt_print_detached_metadata_key, "Print string value of detached metadata key", "KEY" },
   { "raw", 0, 0, G_OPTION_ARG_NONE, &opt_raw, "Show raw variant data" },
   { NULL }
 };