Merge branch 'gh-pages' of ssh://git.mysociety.org/data/git/public/alaveteli into gh-pages

5 files changed, 315 insertions, 2 deletions

diff --git a/_layouts/page.html b/_layouts/page.html
index c5b0e3dd0..ca4f0fa0e 100644
--- a/_layouts/page.html
+++ b/_layouts/page.html
@@ -66,6 +66,7 @@ layout: default
           <li><a href="{{ site.baseurl }}docs/running/">Running</a>
             <ul>
               <li><a href="{{ site.baseurl }}docs/running/admin_manual/">Admin manual</a></li>
+              <li><a href="{{ site.baseurl }}docs/running/holding_pen/">The holding pen</a></li>
               <li><a href="{{ site.baseurl }}docs/running/categories_and_tags/">Categories &amp; tags</a></li>
               <li><a href="{{ site.baseurl }}docs/running/redaction">Redaction</a></li>
               <li><a href="{{ site.baseurl }}docs/running/security/">Security &amp; Maintenance</a></li>
diff --git a/docs/glossary.md b/docs/glossary.md
index 504fb8a05..eb778e6ad 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -471,8 +471,9 @@ Definitions
       <p>More information:</p>
       <ul>
         <li>
-          See the <a href="{{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen">admin manual</a> for
-          information on dealing with emails in the holding pen
+          See more <a href="{{ site.baseurl }}docs/running/holding_pen">about
+          the holding pen</a>, including why messages end up there, and
+          instructions on what to do with them.
         </li>
         <li>
           The most common reason for a response to be in the holding pen is that
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index dbe8be3d1..3b05a5400 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -367,6 +367,12 @@ message under the title *Things to do*:
 Click on that message &mdash; you'll see a list of all the messages that need
 your attention. Click on any one of them to see the details.
 
+<div class="attention-box helpful-hint">
+  If the message does not belong to any request, you can delete it instead.
+  Simply click on the <strong>Destroy Message</strong> button instead of
+  redelivering it.
+</div>
+
 When you inspect a message, you may see a guess made by Alaveteli as to which
 request the message belongs to. Check this request. If the guess is right
 &mdash; the incoming email really is a response to that request &mdash; 
@@ -404,6 +410,7 @@ another request** button.
 The message will now be associated with the correct request. It is no longer
 in the holding pen, and is shown instead on the public request page.
 
+
 ### Rejecting spam that arrives in the holding pen
 
 Alaveteli maintains a 
diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md
new file mode 100644
index 000000000..24d8079b0
--- /dev/null
+++ b/docs/running/holding_pen.md
@@ -0,0 +1,96 @@
+---
+layout: page
+title: The holding pen
+---
+
+#  The holding pen
+
+<p class="lead">
+  
+  The <em>holding pen</em> is where Alaveteli puts any incoming
+  <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a>
+  that can't be matched to a
+  <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a>
+  automatically.
+</p>
+
+
+Alaveteli works by emailing requests to the correct target
+<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a>.
+That email message is sent from a unique email address &mdash; that is, an
+email address that is associated with that single request (technically,
+Alaveteli hashes the request ID to generate a unique address and uses this as
+the `Reply-to:` address).
+
+So whenever an authority replies (by email) to a request that Alaveteli has
+sent, that response will be addressed to that request's unique email address.
+The email is received by your installation's
+<a href="{{ site.baseurl}}docs/glossary/#mta" class="glossary__link">MTA</a>,
+and is passed on to Alaveteli. In this way, incoming messages are easily
+matched with the request they are responses to &mdash; this is important
+because your site displays the responses underneath their original request, on
+the request's page.
+
+Normally, this works fine. But sometimes things go wrong, and a message comes
+in that can't be matched with a request. When this happens, Alaveteli puts the
+message in the
+<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding
+pen </a>.
+
+Messages wait in the holding pen until an 
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>
+redelivers them to the correct request, or else deletes them.
+
+## Why messages end up in the holding pen
+
+There are several reasons why a message might end up in the holding pen:
+
+* **the authority "broke" the reply-to email**<br>
+  This can happen if the authority replies "by hand" to the incoming email &mdash;
+  for example if the person at the authority accidentally loses the first
+  letter of the email address when they copy-and-paste it. Or if they copy
+  it manually and simply get it wrong.
+
+* **there's something unusual about the way it was sent**<br>
+  For example, if it was delivered here because the address is in the `Bcc:`
+  field, and is not the `To:` address.
+
+* **a partial email address may have been guessed**<br>
+  Someone guesses an email address which Alaveteli doesn't recognise. Perhaps
+  they have misunderstood how the addresses are formed, or maybe it's a
+  deliberate attempt to send spam.
+
+* **the response has been rejected and rejections are set to go to the holding pen**<br>
+  Incoming mail that is correctly addressed but not accepted for the request
+  goes into the holding pen if the request's `handle_rejected_responses`
+  behaviour is set to `holding_pen` (rather than bouncing the email back to
+  the sender, or simply deleting it). Responses may be rejected for various
+  reasons &mdash; for example, if a response is sent from an unrecognised 
+  email address for a request whose *Allow new responses from* setting is
+  `authority_only`.
+  
+## What to do: redeliver or delete
+
+You need to be an
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>
+to modify the holding pen.
+
+There are two things you can do to a message in the holding pen:
+
+  * **find the right request, and redeliver the message**<br>
+    Alaveteli tries to guess the right request to help you, so sometimes
+    you can just accept its suggestion. 
+    
+  * **delete the message**<br>
+    If the message is not a response, you can delete it.
+
+For instructions, see
+[removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen).
+
+If the `To:` address does not belong to a valid request and the message is
+clearly spam you can add that email address to Alaveteli's
+<a href="{{site.baseurl}}#spam-address-list" class="glossary__link">spam address list</a>.
+Subsequent messages to that address will be automatically rejected &mdash; for
+instructions see
+[rejecting spam that arrives in the holding pen]({{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen).
+
diff --git a/docs/running/requests.md b/docs/running/requests.md
new file mode 100644
index 000000000..d3733b591
--- /dev/null
+++ b/docs/running/requests.md
@@ -0,0 +1,208 @@
+---
+layout: page
+title: Managing requests
+---
+
+# Managing Requests
+
+
+<p class="lead">
+  Alaveteli makes it easy for a user to make a
+  <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a>.
+  As an 
+  <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>,
+  there are some things about that request you can change once it's been created.
+</p>
+
+A request is automatically created when a user submits and (where necessary)
+confirms it. Alaveteli sends it to the authority responsible and handles any
+<a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a>.
+Usually this process runs without needing any intervention from an
+administrator. But sometimes you'll want to change some aspect of the
+request, or the way Alaveteli is handling it.
+
+## What state is the request in?
+
+Every request moves through a series of 
+<a href="{{ site.baseurl }}docs/glossary/#state" class="glossary__link">states</a>,
+indicating its progress. Usually a new request will be in the `waiting_response`
+state until something happens to change that &mdash; for example, a response is
+received.
+
+However, states can't always be set automatically, because they require a
+decision to be made on what kind of answer the authority provided in the
+response. For states like this, Alaveteli invites the original requester to
+describe its state &mdash; for example, when a response is received they can
+change the state to `successful`, `partially_successful` or `not_held` (if the
+authority replied to say they don't have the information requested).
+
+<div class="attention-box info">
+  If a request has been waiting for over three weeks for the original
+  requester to describe it but has still not been described, Alaveteli
+  lets <em>anyone</em> classify it.
+</div>
+
+Internally, Alaveteli does not just record the "described state" of a request,
+but also notices if anything has happened since it was last described and
+sets its "awaiting description" status appropriately.
+
+
+## Changing things about a request
+
+
+To change any of these settings, go to the 
+<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>,
+click on **Requests**, then click on the title of the request you want to affect. 
+Click the **Edit metadata** button.
+
+<table class="table">
+  <tr>
+    <th>
+      What you can change
+    </th>
+    <th>
+      Details
+    </th>
+  </tr>
+  <tr>
+    <td>
+      Title
+    </td>
+    <td>
+      The title is shown on the request's page, but is also used in the URL
+      (the text is changed to lower case, punctuation is removed and, if
+      necessary, a number is added for disambiguation &mdash; this is called
+      the "slug").
+      <p>
+        Note that changing the title changes the URL, because the slug changes
+        &mdash; this means any links to the <em>old</em> URL will no longer
+        work, and will return a 404 (file not found) error.
+      </p>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      Who&nbsp;can&nbsp;see&nbsp;it?
+    </td>
+    <td>
+      Change the <strong>Prominence</strong> setting to one of:
+      <ul>
+        <li><code>normal</code></li>
+        <li>
+          <code>backpage</code>: request can be seen by anyone (by visiting
+          its URL, for example) but does not appear in lists, or search results
+        </li>
+        <li>
+          <code>requester_only</code>: request only visible to the person who
+          made the request
+        </li>
+        <li>
+          <code>hidden</code>: request is never shown (except to administrators)
+        </li>
+      </ul>
+      <br>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      Who can respond?
+    </td>
+    <td>
+      The <strong>Allow new responses from...</strong> setting can be one of:
+      <ul>
+        <li><code>anybody</code></li>
+        <li>
+          <code>authority_only</code>: responses are allowed if they come
+          from the authority to which the request was sent, or from any domain
+          from which a a response has <em>already</em> been accepted
+        </li>
+        <li>
+          <code>nobody</code>: no responses are allowed on this request
+        </li>
+      </ul>
+      Any response from a sender who has been disallowed by this
+      setting will be rejected (see next entry).
+    </td>
+  </tr>
+  <tr>
+    <td>
+      What happens to rejected responses?
+    </td>
+    <td>
+      The <strong>Handle rejected responses...</strong> setting specificies what happens
+      to responses that are not allowed (see previous entry):
+      <ul>
+        <li>
+          <code>bounce</code>: responses are sent back to their sender
+        </li>
+        <li>
+          <code>holding pen</code>: responses are put in the
+          <a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> for an administrator to deal with
+        </li>
+        <li>
+          <code>blackhole</code>: responses are destroyed by being sent to a
+          <a href="{{ site.baseurl }}docs/glossary/#blackhole" class="glossary__link">black hole</a>
+        </li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      What state is it in?
+    </td>
+    <td>
+      See <a href="{{ site.baseurl }}docs/customising/states/">more about
+      request states</a>, which can be customised for your installation.
+      <p>
+        You can force the state of the request by choosing it explicitly.
+        Change the <strong>Described state</strong> setting.
+      </p>
+      <p>
+        You may also need to set <strong>Awaiting description</strong> if,
+        having changed the state, you want the original requester to update the
+        description. For example, if the state depends on the information
+        within the response, and you want the requester to classify it &mdash;
+        see
+        <em><a href="#what-state-is-the-request-in">What state is the request in?</a></em>
+        above.
+      </p>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      Are comments allowed?
+    </td>
+    <td>
+      The <strong>Are comments allowed?</strong> setting simply you choose to 
+      allow or forbid annotations and comments on this request.
+      <!-- are existing comments deleted? -->
+      <br>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      Tags (search&nbsp;keywords)
+    </td>
+    <td>
+      Enter tags, separated by spaces, that are associated with this request.
+      A tag can be either a simple keyword, or a key-value pair (use a colon as
+      the separator, like this: <code>key:value</code>).
+      <p>
+        Tags are used for searching. Users and administators both benefit if
+        you tag requests with useful keywords, because it helps them find
+        specific requests &mdash; especially if your site gets busy and there
+        are very many in the database.
+      </p>
+      <p>
+        Although it's a little more complex than tags on requests,
+        <a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a>
+        also use tags:
+        see 
+        <a href="{{ site.baseurl }}docs/running/categories_and_tags/">more about tags</a> for a little
+        more information.
+      </p>
+    </td>
+  </tr>
+</table>
+
+