Document my now much simpler patch.

3 files changed, 52 insertions, 17 deletions

diff --git a/doc/bugs/http_proxy_for_openid.mdwn b/doc/bugs/http_proxy_for_openid.mdwn
index 566896ec3..4a9c1b3eb 100644
--- a/doc/bugs/http_proxy_for_openid.mdwn
+++ b/doc/bugs/http_proxy_for_openid.mdwn
@@ -79,8 +79,7 @@ Brian May
 >>>>> installed, even with the above commit, `openid` won't be able to 
 >>>>> traverse a proxy. --[[schmonz]]
 
-[[!template id=gitbranch branch=schmonz/proxies author="[[schmonz]]"]]
+[[!template id=gitbranch branch=schmonz/proxy author="[[schmonz]]"]]
 
->>>>> I bollixed up my git, recloned, and reapplied the diffs, so
->>>>> that commit won't exist anymore. My proxy-related changes are
->>>>> now on a branch. --[[schmonz]]
+>>>>>> I've redone this from scratch, much more simply, on a new
+>>>>>> branch. --[[schmonz]].
diff --git a/doc/plugins/contrib/proxies.mdwn b/doc/plugins/contrib/proxies.mdwn
deleted file mode 100644
index 7f8f5faaf..000000000
--- a/doc/plugins/contrib/proxies.mdwn
+++ /dev/null
@@ -1,13 +0,0 @@
-[[!template id=plugin name=proxies author="[[schmonz]]"]]
-[[!template id=gitbranch branch=schmonz/proxies author="[[schmonz]]"]]
-[[!tag type/web]]
-
-This plugin enables ikiwiki to open outbound connections (such as
-found in [[plugins/aggregate]], [[plugins/openid]], and [[plugins/pinger]])
-via a proxy. The proxy can be configurably avoided for connections
-to certain domains.
-
-### To do
-
-* Move duplicated user-agent setup out of other plugins into this one.
-* While I'm at it, fix [[bugs/http_proxy_for_openid]].
diff --git a/doc/todo/outbound_proxy.mdwn b/doc/todo/outbound_proxy.mdwn
new file mode 100644
index 000000000..9159a1af1
--- /dev/null
+++ b/doc/todo/outbound_proxy.mdwn
@@ -0,0 +1,49 @@
+[[!template id=gitbranch branch=schmonz/proxy author="[[schmonz]]"]]
+[[!tag patch]]
+
+## Background
+
+Ikiwiki has several plugins that open outbound connections:
+
+* [[plugins/aggregate]]
+* [[plugins/openid]]
+* [[plugins/pinger]]
+
+In some networks it is desired (or necessary) for these connections
+to traverse a proxy. Proxies are usually configured via environment
+variables, so for ikiwiki it is probably not desirable (or necessary)
+to manage proxy configuration in the setup file.
+
+[[!cpan LWP::UserAgent]] by default doesn't care about the usual
+environment variables, but if its constructor is passed a true
+`env_proxy` value, it does. Then environment settings such as these
+influence the agent, as expected:
+
+    ENV:
+      http_proxy: 'http://foo.internal:8080'
+      no_proxy: 'localhost,.bar.internal'
+
+If the proxy and/or destination requires authentication, it may
+also be necessary to prime `cookiejar`.
+
+## Changes
+
+This patch causes ikiwiki's `LWP::UserAgent` instances to:
+
+* honor proxy configuration in the environment
+* consistently make use of cookies configured in the setup file
+
+## Limitations
+
+The patch lets me configure [[plugins/aggregate]] to traverse my
+corporate proxy and to skip the proxy for internal hosts. I haven't
+tested it with the other two plugins, both of which prefer [[!cpan
+LWPx::ParanoidAgent]] if present, which deliberately lacks proxy
+support. There exists [[!cpan LWP::UserAgent::Paranoid]] claiming
+to be more modern, but I haven't looked at it further, so I don't
+know whether its paranoia measures up or whether it supports proxies.
+
+## See also
+
+* [[bugs/http_proxy_for_openid]]
+* [[forum/Setting_http__95__proxy]]