proxy: update documentation

In particular, note that /system/proxy/use-same-proxy and
/system/proxy/http/enabled are not actually used.

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

1 files changed, 33 insertions, 6 deletions

diff --git a/schemas/org.gnome.system.proxy.gschema.xml.in.in b/schemas/org.gnome.system.proxy.gschema.xml.in.in
index 103d75d..ee03dd3 100644
--- a/schemas/org.gnome.system.proxy.gschema.xml.in.in
+++ b/schemas/org.gnome.system.proxy.gschema.xml.in.in
@@ -10,13 +10,33 @@
       <_description>
         Select the proxy configuration mode. Supported values are "none", 
         "manual", "auto".
+
+        If this is "none", then proxies are not used.
+
+        If it is "auto", the autoconfiguration URL described by the
+        "autoconfig-url" key is used.
+
+        If it is "manual", then the proxies described by
+        "/system/proxy/http", "/system/proxy/https",
+        "/system/proxy/ftp" and "/system/proxy/socks" will be used.
+        Each of the 4 proxy types is enabled if its "host" key is
+        non-empty and its "port" key is non-0.
+
+        If an http proxy is configured, but an https proxy is not,
+        then the http proxy is also used for https.
+
+        If a SOCKS proxy is configured, it is used for all protocols,
+        except that the http, https, and ftp proxy settings override
+        it for those protocols only.
       </_description>
     </key>
     <key name="autoconfig-url" type="s">
       <default>''</default>
       <_summary>Automatic proxy configuration URL</_summary>
       <_description>
-        URL that provides proxy configuration values.
+        URL that provides proxy configuration values. When mode is
+        "auto", this URL is used to look up proxy information for all
+        protocols.
       </_description>
     </key>
     <key name="ignore-hosts" type="as">
@@ -32,16 +52,19 @@
     </key>
     <key name="use-same-proxy" type="b">
       <default>true</default>
-      <_summary>Use same proxy for all protocols</_summary>
-      <_description>Whether to use the same proxy for all protocols or not.</_description>
+      <_summary>Unused; ignore</_summary>
+      <_description>
+        This key is not used, and should not be read or modified.
+      </_description>
     </key>
   </schema>
   <schema id="org.gnome.system.proxy.http" path="/system/proxy/http/">
     <key name="enabled" type="b">
       <default>false</default>
-      <_summary>Use HTTP proxy</_summary>
+      <_summary>Unused; ignore</_summary>
       <_description>
-        Enables the proxy settings when accessing HTTP over the Internet.
+        This key is not used; HTTP proxying is enabled when the host
+        key is non-empty and the port is non-0.
       </_description>
     </key>
     <key name="host" type="s">
@@ -68,6 +91,10 @@
         The username/password combo is defined by 
         "/system/proxy/http/authentication-user" and 
         "/system/proxy/http/authentication-password".
+
+        This applies only to the http proxy; when using a separate
+        https proxy, there is currently no way to specify that it
+        should use authentication.
       </_description>
     </key>
     <key name="authentication-user" type="s">
@@ -126,7 +153,7 @@
       <default>''</default>
       <_summary>SOCKS proxy host name</_summary>
       <_description>
-        The machine name to proxy socks through.
+        The machine name to use as a SOCKS proxy.
       </_description>
     </key>
     <key name="port" type="i">