Update help and docs for gsettings cmdline tool

The man page had gotten quite out of sync.

docs/reference/gio/gsettings.xml

@@ -15,35 +15,67 @@
   <cmdsynopsis>
     <command>gsettings</command>
     <arg choice="plain">get</arg>
-    <arg choice="opt" rep="repeat">option</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="req"><replaceable>schema</replaceable></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-    <arg choice="req"><replaceable>key</replaceable></arg>
   </cmdsynopsis>
   <cmdsynopsis>
     <command>gsettings</command>
     <arg choice="plain">monitor</arg>
-    <arg choice="opt" rep="repeat">option</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="req"><replaceable>schema</replaceable></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-    <arg choice="req"><replaceable>key</replaceable></arg>
   </cmdsynopsis>
   <cmdsynopsis>
     <command>gsettings</command>
     <arg choice="plain">writable</arg>
-    <arg choice="opt" rep="repeat">option</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="req"><replaceable>schema</replaceable></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-    <arg choice="req"><replaceable>key</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">range</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
   </cmdsynopsis>
   <cmdsynopsis>
     <command>gsettings</command>
     <arg choice="plain">set</arg>
-    <arg choice="opt" rep="repeat">option</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
-    <arg choice="req"><replaceable>schema</replaceable></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
-    <arg choice="req"><replaceable>key</replaceable></arg>
+    <arg choice="plain"><replaceable>VALUE</replaceable></arg>
-    <arg choice="req"><replaceable>value</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">reset</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-schemas</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-relocatable-schemas</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-keys</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-children</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-recursively</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
   </cmdsynopsis>
   <cmdsynopsis>
     <command>gsettings</command>
     <arg choice="plain">help</arg>
+    <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
 
@@ -53,12 +85,14 @@ interface to <link linkend="GSettings"><type>GSettings</type></link>.
 It lets you get, set or monitor an individual key for changes.
 </para>
 <para>
-The <replaceable>schema</replaceable> and <replaceable>key</replaceable>
+The <replaceable>SCHEMA</replaceable> and <replaceable>KEY</replaceable>
-arguments are required to specify the schema id and the name of the key
+arguments are required for most commands to specify the schema id and the
-to operate on.
+name of the key to operate on. The schema id may optionally have a
+:<replaceable>PATH</replaceable> suffix. Specifying the path is only needed
+if the schema does not have a fixed path.
 </para>
 <para>
-When setting a key, you also need specify a <replaceable>value</replaceable>
+When setting a key, you also need specify a <replaceable>VALUE</replaceable>
 The format for the value is that of a serialized
 <link linkend="GVariant"><type>GVariant</type></link>,
 so e.g. a string
@@ -72,8 +106,8 @@ out values.
 <varlistentry>
 <term><option>get</option></term>
 <listitem><para>
-Get the value of <replaceable>key</replaceable>. The value is printed out
+Gets the value of <replaceable>KEY</replaceable>.
-as a serialised
+The value is printed out as a serialised
 <link linkend="GVariant"><type>GVariant</type></link>.
 </para></listitem>
 </varlistentry>
@@ -81,7 +115,7 @@ as a serialised
 <varlistentry>
 <term><option>monitor</option></term>
 <listitem><para>
-Monitor <replaceable>key</replaceable> for changes and print the changed
+Monitors <replaceable>KEY</replaceable> for changes and prints the changed
 values. Monitoring will continue until the process is terminated.
 </para></listitem>
 </varlistentry>
@@ -89,49 +123,82 @@ values. Monitoring will continue until the process is terminated.
 <varlistentry>
 <term><option>writable</option></term>
 <listitem><para>
-Find out whether <replaceable>key</replaceable> is writable.
+Finds out whether <replaceable>KEY</replaceable> is writable.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>range</option></term>
+<listitem><para>
+Queries the range of valid values for <replaceable>KEY</replaceable>.
 </para></listitem>
 </varlistentry>
 
 <varlistentry>
 <term><option>set</option></term>
 <listitem><para>
-Set the value of <replaceable>key</replaceable> to <replaceable>value</replaceable>.
+Sets the value of <replaceable>KEY</replaceable> to
-The value is specified as a serialised
+<replaceable>VALUE</replaceable>. The value is specified as a serialised
 <link linkend="GVariant"><type>GVariant</type></link>.
 </para></listitem>
 </varlistentry>
 
+<varlistentry>
+<term><option>reset</option></term>
+<listitem><para>
+Resets <replaceable>KEY</replaceable> to its default value.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-schemas</option></term>
+<listitem><para>
+Lists the installed, non-relocatable schemas.
+See <option>list-relocatable-schemas</option> if you are interested in
+relocatable schemas.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-relocatable-schemas</option></term>
+<listitem><para>
+Lists the installed, relocatable schemas.
+See <option>list-schemas</option> if you are interested in
+non-relocatable schemas.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-keys</option></term>
+<listitem><para>
+Lists the keys in <replaceable>SCHEMA</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-children</option></term>
+<listitem><para>
+Lists the children of <replaceable>SCHEMA</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-recursively</option></term>
+<listitem><para>
+Lists keys and values, recursively.
+</para></listitem>
+</varlistentry>
+
 <varlistentry>
 <term><option>help</option></term>
 <listitem><para>
-Print help and exit
+Prints help and exits.
 </para></listitem>
 </varlistentry>
 
 </variablelist>
 </refsect2>
 
-
-<refsect2><title>Options</title>
-<variablelist>
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-Print help for the command and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-p <replaceable>path</replaceable></option>, <option>--path=<replaceable>path</replaceable></option></term>
-<listitem><para>
-The path for the schema. This option is only needed if the schema
-does not have a fixed path.
-</para></listitem>
-</varlistentry>
-</variablelist>
-</refsect2>
-
 </refsect1>
 </refentry>
 

gio/gsettings-tool.c

@@ -453,6 +453,12 @@ gsettings_help (gboolean     requested,
   if (command == NULL)
     ;
 
+  else if (strcmp (command, "help") == 0)
+    {
+      description = _("Print help");
+      synopsis = "[COMMAND]";
+    }
+
   else if (strcmp (command, "list-schemas") == 0)
     {
       description = _("List the installed (non-relocatable) schemas");
@@ -467,13 +473,13 @@ gsettings_help (gboolean     requested,
 
   else if (strcmp (command, "list-keys") == 0)
     {
-      description = _("Lists the keys in SCHEMA");
+      description = _("List the keys in SCHEMA");
       synopsis = N_("SCHEMA[:PATH]");
     }
 
   else if (strcmp (command, "list-children") == 0)
     {
-      description = _("Lists the children of SCHEMA");
+      description = _("List the children of SCHEMA");
       synopsis = N_("SCHEMA[:PATH]");
     }
 
@@ -485,37 +491,37 @@ gsettings_help (gboolean     requested,
 
   else if (strcmp (command, "get") == 0)
     {
-      description = _("Gets the value of KEY");
+      description = _("Get the value of KEY");
       synopsis = N_("SCHEMA[:PATH] KEY");
     }
 
   else if (strcmp (command, "range") == 0)
     {
-      description = _("Queries the range of valid values for KEY");
+      description = _("Query the range of valid values for KEY");
       synopsis = N_("SCHEMA[:PATH] KEY");
     }
 
   else if (strcmp (command, "set") == 0)
     {
-      description = _("Sets the value of KEY to VALUE");
+      description = _("Set the value of KEY to VALUE");
       synopsis = N_("SCHEMA[:PATH] KEY VALUE");
     }
 
   else if (strcmp (command, "reset") == 0)
     {
-      description = _("Resets KEY to its default value");
+      description = _("Reset KEY to its default value");
       synopsis = N_("SCHEMA[:PATH] KEY");
     }
 
   else if (strcmp (command, "writable") == 0)
     {
-      description = _("Checks if KEY is writable");
+      description = _("Check if KEY is writable");
       synopsis = N_("SCHEMA[:PATH] KEY");
     }
 
   else if (strcmp (command, "monitor") == 0)
     {
-      description = _("Monitors KEY for changes.\n"
+      description = _("Monitor KEY for changes.\n"
                     "If no KEY is specified, monitor all keys in SCHEMA.\n"
                     "Use ^C to stop monitoring.\n");
       synopsis = N_("SCHEMA[:PATH] [KEY]");
@@ -558,7 +564,11 @@ gsettings_help (gboolean     requested,
         {
           g_string_append (string, _("Arguments:\n"));
 
-          if (strstr (synopsis, "SCHEMA"))
+          if (strstr (synopsis, "[COMMAND]"))
+            g_string_append (string,
+                           _("  COMMAND   The (optional) command to explain\n"));
+
+          else if (strstr (synopsis, "SCHEMA"))
             g_string_append (string,
                            _("  SCHEMA    The name of the schema\n"
                              "  PATH      The path, for relocatable schemas\n"));