Merge branch 'gh-pages-docs-admin-requests' into gh-pages

Conflicts:
	docs/running/admin_manual.md

4 files changed, 143 insertions, 63 deletions

diff --git a/_layouts/page.html b/_layouts/page.html
index ca4f0fa0e..d868a951d 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/requests/">Managing requests</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>
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index 558a0838b..cb1443578 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -36,8 +36,8 @@ In this guide:
       <li><a href="#banning-a-user">Banning a user</a></li>
       <li><a href="#allowing-a-user-to-make-more-requests">Allowing a user to make more requests</a></li>
       <li><a href="#batch-requests">Batch requests</a></li>
-      <li><a href="#deleting-a-request">Deleting a request</a></li>
       <li><a href="#hiding-a-request">Hiding a request</a></li>
+      <li><a href="#deleting-a-request">Deleting a request</a></li>
       <li><a href="#hiding-an-incoming-or-outgoing-message">Hiding an incoming or outgoing message</a></li>
       <li><a href="#editing-an-outgoing-message">Editing an outgoing message</a></li>
       <li><a href="#hiding-certain-text-from-a-request-using-censor-rules">Hiding certain text from a request</a></li>
@@ -314,7 +314,7 @@ line, and piping the contents of that file into the mail handling script. e.g.
 The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a>
 is at the URL `/admin`. Only users who are
 <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrators</a>
-can access the admin interface. 
+can access the admin interface.
 
 To make a user an administrator on a brand new site,
 [follow these steps]({{ site.baseurl }}docs/installing/next_steps/#create-a-superuser-admin-account).
@@ -345,7 +345,7 @@ have extra privileges in the main website front end. Administrators can:
 
 Alaveteli puts incoming messages (that is,
 <a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">responses</a>)
-into the 
+into the
 <a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>
 if their `To:` email addresses can't automatically be associated with a
 <a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">request</a>.
@@ -377,7 +377,7 @@ your attention. Click on any one of them to see the details.
 
 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; 
+&mdash; the incoming email really is a response to that request &mdash;
 the request's *title_url* will already be in the input box: click the
 **Redeliver to another request** button.
 
@@ -399,7 +399,7 @@ its *url_title*.
   <p>
     A request's <em>url_title</em> is the part after <code>/request/</code>
     in your Alaveteli site's URL when you are looking at that request.
-    In the URL <code>/request/how_many_vehicles</code>, the 
+    In the URL <code>/request/how_many_vehicles</code>, the
     <em>url_title</em> is <code>how_many_vehicles</code>.
   </p>
 </div>
@@ -415,7 +415,7 @@ in the holding pen, and is shown instead on the public request page.
 
 ### Rejecting spam that arrives in the holding pen
 
-Alaveteli maintains a 
+Alaveteli maintains a
 <a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>.
 Any incoming message to an email address on that list
 *that would otherwise be put in the holding pen* will be rejected and won't
@@ -463,13 +463,13 @@ You can see the spam address list (that is, all known spam-target email
 addresses) at any time by going to the admin interface at `/admin/spam_addresses`.
 
 You can remove any address from the list by clicking the **Remove** button
-next to it. Of course, this won't restore any messages that have been 
+next to it. Of course, this won't restore any messages that have been
 rejected, but Alaveteli will not reject any new messages that are sent to
 this address.
 
 Note that if you are seeing consistent spam email in your holding pen, you
 should also consider implementing (or increasing) the anti-spam measures
-running in your 
+running in your
 <a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>.
 
 ### Creating, changing and uploading public authority data
@@ -582,7 +582,7 @@ unrecognised column name, the import will fail.
      this, use the admin interface to edit the existing record first, and
      change its name in the web interface.
    * If the authority already exists (the `name` matches an existing authority's
-     name exactly), a blank entry leaves the existing value for that column 
+     name exactly), a blank entry leaves the existing value for that column
      unchanged &mdash; that is, that item of data on your site will not be
      changed. This means you only really need to include data you want to
      update.
@@ -597,7 +597,7 @@ unrecognised column name, the import will fail.
      between commas.
    * If an entry contains a comma, enclose it in double quotes like this:
      `"Comma, Inc"`.
-   * If an entry contains any double quotes, you must replace each of 
+   * If an entry contains any double quotes, you must replace each of
      them with two (so `"` becomes `""`) and also enclose the whole entry in
      double quotes like this: `"In ""quotes"""` (which will be imported as `In
      "quotes"`).
@@ -614,15 +614,15 @@ data (one line for each authority):
 Note that, if Ejemplo Town Council already exists on the site, the blank entry
 for `short_name` will leave the existing value for that column unchanged.
 
-To upload a CSV file, log into the admin and click on **Authorities**. Click on 
-**Import from CSV file**, and choose the file you've prepared. 
+To upload a CSV file, log into the admin and click on **Authorities**. Click on
+**Import from CSV file**, and choose the file you've prepared.
 
 Specify **What to do with existing tags?** with one of these options:
 
    * *Replace existing tags with new ones* <br/>
      For each authority being updated, all existing tags will be removed, and
      replaced with the ones in your CSV file.
-   
+
    * *Add new tags to existing ones* <br/>
      Existing tags will be left unchanged, and the tags in your CSV file will
      be added to them.
@@ -640,7 +640,7 @@ you really uploaded this data, followed by a message like this:
 If you see nothing above that line, it means the dry run has resulted in no
 proposed changes.
 
-If everything was OK when you ran the dry run, click **Upload** instead. This 
+If everything was OK when you ran the dry run, click **Upload** instead. This
 will repeat the process, but this time it will make the changes to your
 site's database.
 
@@ -714,35 +714,25 @@ This does not allow anyone to make batch requests yet. You must still enable thi
 
 If you've enabled batch requests for a user, when they start to make a request, in addition to the box where they can select an authority, they will see a link to "make a batch request". When the request is sent, Alaveteli will make a request page for this request for each authority, as if the user had made individual requests.
 
-### Deleting a request
+### Hiding a request
 
-You can delete a request entirely using the admin interface. You will mainly only need to do this if someone has posted private information. Go to the admin page for the request by searching or browsing in the 'Requests' section of the admin interface. In the first section, click the 'Edit metadata' button. At the bottom of the next page, click the red 'Destroy request entirely' button.
+If a request contains vexatious or inappropriate content, is libellous, or is
+not a valid
+<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a>
+request at all, you may want to hide it. A hidden request is still visible to
+you and the other administrators, and (optionally) the requester themselves.
+For instructions, see
+[hiding a request]({{ site.baseurl }}docs/running/requests/#hiding-a-request).
 
-### Hiding a request
+Responses to a hidden request will be accepted in the normal way, but because
+they are added to the request's page, they too will be hidden.
+
+### Deleting a request
+
+You can delete a request from the site. For instructions, see
+[deleting a request]({{ site.baseurl }}docs/running/requests/#deleteing-a-request).
 
-You can hide an entire request from the admin interface. Log in to the
-admin interface at `/admin`. On the top row of links, locate and click on
-'Requests'. Search or browse to find the admin page for the request you
-want to hide. You can also go directly to this page by following an
-'admin' link from the public request page. You can hide a request in one
-of two ways.
-
-  * <strong>Hiding a vexatious or non-FOI request and notifying the
-    requester</strong>
-    Scroll down to the 'actions' section of the request
-    admin page. Select one of the options next to 'Hide the request and
-    notify the user:' and customise the text of the email that will be
-    sent to the user to let them know what you've done. When you're
-    ready, click the 'Hide request' button.
-  * <strong>Hiding a request or making it only visible to the
-    requester without notifying the requester</strong>
-    In the 'Request metadata' section of the request
-    admin page, click 'Edit metadata'. Change the 'Prominence' value to
-    'requester_only' to only allow the requester to view the request, or
-    to 'hidden' to hide the request from everyone except site admins.
-    When you're ready, click 'Save changes' at the bottom of the 'Edit
-    metadata' section. No email will be sent to the requester to notify
-    them of what you've done.
+Responses to a deleted request will be sent to the holding pen.
 
 ### Hiding an incoming or outgoing message
 
diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md
index 24d8079b0..5b7f08bec 100644
--- a/docs/running/holding_pen.md
+++ b/docs/running/holding_pen.md
@@ -60,6 +60,10 @@ There are several reasons why a message might end up in the holding pen:
   they have misunderstood how the addresses are formed, or maybe it's a
   deliberate attempt to send spam.
 
+* **the response is to a request that has been deleted**<br>
+  If you [delete a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request),
+  Alaveteli cannot deliver responses to it.
+
 * **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`
@@ -67,7 +71,8 @@ There are several reasons why a message might end up in the holding pen:
   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`.
+  `authority_only`. See instructions on
+  [how to manage requests]({{site.baseurl}}docs/running/requests/) for details.
   
 ## What to do: redeliver or delete
 
diff --git a/docs/running/requests.md b/docs/running/requests.md
index d3733b591..4feb3d291 100644
--- a/docs/running/requests.md
+++ b/docs/running/requests.md
@@ -11,29 +11,38 @@ title: Managing requests
   <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.
+  there are some things about that request you can change once it&rsquo;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
+confirms it. Alaveteli sends it to the
+<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a>
+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.
+administrator. But sometimes you'll want to change some aspect of the request,
+or the way Alaveteli is handling it.
+
+<ul class="toc">
+  <li><a href="#what-state-is-the-request-in">What state is the request in?</a></li>
+  <li><a href="#changing-things-about-a-request">Changing things about a request</a></li>
+  <li><a href="#hiding-a-request">Hiding a request</a></li>
+  <li><a href="#deleting-a-request">Deleting a request</a></li>
+</ul>
 
 ## 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.
+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
+describe it &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">
@@ -49,7 +58,6 @@ 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. 
@@ -69,10 +77,10 @@ Click the **Edit metadata** button.
       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").
+      The <em>title</em> is shown on the request&rsquo;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 &ldquo;slug&rdquo;).
       <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
@@ -129,15 +137,16 @@ Click the **Edit metadata** button.
       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):
+      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
+          <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
@@ -175,8 +184,10 @@ Click the **Edit metadata** button.
     <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>
+      <p>
+        Note that this won&rsquo;t hide any annotations that have already
+        been left on the reques &mdash; it only prevents users adding new ones.
+      </p>
     </td>
   </tr>
   <tr>
@@ -194,15 +205,88 @@ Click the **Edit metadata** button.
         are very many in the database.
       </p>
       <p>
-        Although it's a little more complex than tags on requests,
+        Although it&rsquo;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.
+        <a href="{{ site.baseurl }}docs/running/categories_and_tags/">more about tags</a>
+        for a little more information.
       </p>
     </td>
   </tr>
 </table>
 
+## Hiding a request
+
+You can hide an entire request. Typically you do this if it's not a valid
+Freedom of Information request (for example, a request for personal
+information), or if it is vexatious.
+
+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. You can
+hide it in one of two ways:
+
+   * [Hide the request and notify the requester](#hide-the-request-and-notify-the-requester)
+   * [Hide the request without notifying the requester](#hide-the-request-without-notifying-the-requester)
+
+Responses to a hidden request will be accepted in the normal way, but because
+they are added to the request's page, they too will be hidden.
+
+### Hide the request and notify the requester
+
+Scroll down to the *Actions* section of the request's admin page.
+Choose one of the options next to **Hide the request and notify the user:**
+
+   * Not a valid FOI request
+   * A vexatious request
+
+Choosing one of these will reveal an email form. Customise the text of the
+email that will be sent to the user, letting them know what you've done. When
+you're ready, click the **Hide request** button.
+
+### Hide the request without notifying the requester
+
+<div class="attention-box helpful-hint">
+  As well as hiding the request from everyone, you can also use this method if
+  you want to make the request only visible to the requester.
+</div>
+  
+In the *Request metadata* section of the request's admin page, click the
+**Edit metadata** button. Change the *Prominence* value to one of these:
+
+  * `requester_only`: only the requester can view the request
+  * `hidden`: nobody can see the request, except administrators.
+
+<div class="attention-box warning">
+  If you want to hide the request, do not chooose  <code>backpage</code>
+  as the prominence. The <code>backpage</code> option stops the request
+  appearing in lists and searches so that it is effectively only visible
+  to anyone who has its URL &mdash; but it <em>does not hide</em> the request.
+</div>
+
+When you're ready, click the **Save changes** button at the bottom of the
+*Edit metadata* section. No email will be sent to the requester to notify
+them of what you've done.
+
+
+## Deleting a request
+
+You can delete a request entirely. Typically, you only need to do this if
+someone has posted private information.  If you delete a request, any responses that it has already received will be
+destroyed as well.
+
+<div class="attention-box warning">
+  Deleting a request destroys it. There is no &ldquo;undo&rdquo; operation.
+  If you're not sure you want to do this, perhaps you should
+  <a href="#hiding-a-request">hide the request</a> instead.
+</div>
+
+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 delete. 
+Click the **Edit metadata** button. Click on the red **Destroy request entirely**
+button at the bottom of the page.
+
+Responses to a deleted request will be sent to the
+<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>.
+