Merge branch 'issues/2060-docs-edit-upload-body' into gh-pages

3 files changed, 310 insertions, 39 deletions

diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md
index 24c0c31e0..b230d3127 100644
--- a/docs/developers/i18n.md
+++ b/docs/developers/i18n.md
@@ -6,8 +6,9 @@ title: Internationalisation (for devs)
 # Internationalisation in the code
 
 <p class="lead">
-    This page describes some technical aspects of internationalising the
-    Alaveteli code. It's mostly aimed at devs who are working on the
+    This page describes some technical aspects of 
+    <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalising</a>
+    the Alaveteli code. It's mostly aimed at devs who are working on the
     codebase &mdash; if you just want to translate Alaveteli into your
     own language, see
     <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a>
diff --git a/docs/glossary.md b/docs/glossary.md
index 3ae5e6a3c..246afaf80 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -24,15 +24,18 @@ Definitions
   <li><a href="#capistrano">Capistrano</a></li>
   <li><a href="#censor-rule">censor rule</a></li>
   <li><a href="#development">development site</a></li>
+  <li><a href="#disclosure-log">disclosure log</a></li>
   <li><a href="#emergency">emergency user</a></li>
   <li><a href="#foi">freedom of information</a></li>
   <li><a href="#git">git</a></li>
   <li><a href="#holding_pen">holding pen</a></li>
+  <li><a href="#i18n">internationalisation</a></li>
   <li><a href="#newrelic">New Relic</a></li>
   <li><a href="#mta">MTA</a></li>
   <li><a href="#po">.po files</a></li>
   <li><a href="#production">production site</a></li>
   <li><a href="#publish">publish</a></li>
+  <li><a href="#publication-scheme">publication scheme</a></li>
   <li><a href="#recaptcha">recaptcha</a></li>
   <li><a href="#redact">redacting</a></li>
   <li><a href="#regexp">regular expression</a></li>
@@ -102,7 +105,7 @@ Definitions
         </li>
         <li>
           On a newly-installed Alaveteli system, you can grant yourself
-          admin privilege by using the 
+          admin privilege by using the
           <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency
           user</a>.
         </li>
@@ -268,6 +271,26 @@ Definitions
   </dd>
 
   <dt>
+    <a name="disclosure-log">disclosure log</a>
+  </dt>
+  <dd>
+    Some <a href="#authority" class="glossary__link">authorities</a> routinely
+    publish their responses to <a href="#foi" class="glossary__link">Freedom of
+    Information</a> requests online. This collection of responses is called a
+    <strong>disclosure log</strong>, and if an authority has such a log on its
+    website, you can add the URL so Alaveteli can link to it.
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          You can add a disclosure log URL by
+          <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin.
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
     <a name="emergency">emergency user</a>
   </dt>
   <dd>
@@ -285,7 +308,7 @@ Definitions
         <li>
           The username and password are defined by the configuration settings
           <code><a href="{{site.baseurl}}docs/customising/config/#admin_username">ADMIN_USERNAME</a></code>
-          and 
+          and
           <code><a href="{{site.baseurl}}docs/customising/config/#admin_password">ADMIN_PASSWORD</a></code>.
         </li>
         <li>
@@ -378,6 +401,47 @@ Definitions
   </dd>
 
   <dt>
+    <a name="i18n">internationalisation</a> (also: i18n)
+  </dt>
+  <dd>
+    <strong>Internationalisation</strong> is the way Alaveteli adapts the
+    way it presents text based on the language or languages that your website
+    supports. It's sometimes abbreviated as <em>i18n</em> (because there are
+    18 letters between i and n).
+    <p>
+      Often you don't need to worry about the details of how this is done 
+      because once you've configured your site's
+      <code><a href="{{ site.baseurl }}docs/customising/config/#default_locale">DEFAULT_LOCALE</a></code>
+      Alaveteli takes care of it for you.
+      But when you do need to work on i18n (for example, if you're customising
+      your site by 
+      <a href="{{ site.baseurl }}docs/customising/translation/">translating</a> it, or 
+      <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">uploading names</a>
+      of the public bodies in more than one language) at the very least you may
+      need to know the language codes you're site is using.
+    </p>
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          More about <a href="{{ site.baseurl }}docs/developers/i18n/">internationalising Alaveteli</a>
+        </li>
+        <li>
+          See mySociety's
+          <a href="http://mysociety.github.io/internationalization.html">i18n guidelines</a> for developers
+        </li>
+        <li>
+          <a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">List of language codes</a>
+        </li>
+        <li>
+          For more about i18n in software generally, see
+          the <a href="http://en.wikipedia.org/wiki/Internationalization_and_localization">i18n Wikipedia article</a>.
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
     <a name="mta">MTA</a> (Mail Transfer Agent)
   </dt>
   <dd>
@@ -500,6 +564,29 @@ Definitions
   </dd>
 
   <dt>
+    <a name="publication-scheme">publication scheme</a>
+  </dt>
+  <dd>
+    Some <a href="#authority" class="glossary__link">authorities</a> have a
+    <strong>publication scheme</strong> which makes it clear what information
+    is readily available from them under <a href="#foi"
+    class="glossary__link">Freedom of Information</a> law, and how people can
+    get it. This may be a requirement for their compliance with the law, or it
+    may simply be good practice. If an authority has published such a scheme on
+    its website, you can add the URL so Alaveteli can link to it.
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          You can add a publication scheme URL by
+          <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin.
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+
+  <dt>
     <a name="recaptcha">recaptcha</a>
   </dt>
   <dd>
@@ -773,7 +860,7 @@ Definitions
         </li>
         <li>
           On a newly-installed Alaveteli system, you can grant yourself
-          admin privilege by using the 
+          admin privilege by using the
           <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency
           user</a>.
         </li>
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index a846732f3..8c3e72a8e 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -7,23 +7,12 @@ title: Administrator's guide
 
 <p class="lead">
   What is it like running an Alaveteli site? This guide explains what you can
-  expect, and the types of problem that you might encounter. At mySociety,
-  we've been running our own <a href="/docs/glossary/#foi"
+  expect, and the types of problem that you might encounter. It includes
+  examples of how mySociety manages their own <a href="/docs/glossary/#foi"
   class="glossary__link">Freedom of Information</a> site, <a
-  href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>, since 2008,
-  so we've included lots of examples from our own experience.
-  
+  href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>.
 </p>
 
-<div class="attention-box helpful-hint">
-  <p>
-    <b>Before you start...</b>
-    This admin guide assumes your Alaveteli site is already up and running.
-    If it's not, you need to follow the steps for
-    <a href="{{ site.baseurl }}docs/getting_started/">getting started with Alaveteli</a>.
-  </p>
-</div>
-
 In this guide:
 
 <ul class="toc">
@@ -42,7 +31,7 @@ In this guide:
     <ul>
       <li><a href="#administrator-privileges-and-accessing-the-admin-interface">Administrator privileges and accessing the admin interface</a></li>
       <li><a href="#removing-a-message-from-the-holding-pen">Removing a message from the 'Holding Pen'</a></li>
-      <li><a href="#editing-and-uploading-public-body-email-addresses">Editing and uploading public body email addresses</a></li>
+      <li><a href="#creating-changing-and-uploading-public-authority-data">Creating, changing and uploading public authority data</a></li>
       <li><a href="#banning-a-user">Banning a user</a></li>
       <li><a href="#deleting-a-request">Deleting a request</a></li>
       <li><a href="#hiding-a-request">Hiding a request</a></li>
@@ -66,8 +55,7 @@ times.
 
 Administration tasks can be split into [**maintenance**]({{ site.baseurl }}docs/running/admin_manual/#maintenance) and [**user support**]({{ site.baseurl }}docs/running/admin_manual/#user-support).
 The boundaries of these tasks is in fact quite blurred; the main distinction is
-that the former happen exclusively through the web 
-<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, whereas the
+that the former happen exclusively through the web admin interface, whereas the
 latter are mediated by email directly with end users (but often result in
 actions through the web admin interface).
 
@@ -320,24 +308,17 @@ line, and piping the contents of that file into the mail handling script. e.g.
 
 ### Administrator privileges and accessing the admin interface
 
-The 
-<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a>
-is at the URL `/admin`.
+The administrative interface is at the URL `/admin`.
 
-Only users with the
-<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a>
-admin level can access the admin interface. To make a new administrator,
-create a user account in the usual way (signing in using the web front-end),
-and then have an existing administrator to grant them *super* privileges.
+Only users with the `super` admin level can access the admin interface. Users
+create their own accounts in the usual way, and then administrators can give
+them `super` privileges.
 
-Obviously, you can't do this for the very first administrator on a brand
-new Alavetlei installation. So there is an emergency user account which can be
-accessed via `/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and
+There is an emergency user account which can be accessed via
+`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and
 `ADMIN_PASSWORD`, which are set in `general.yml`.  To bootstrap the
 first `super` level accounts, you will need to log in as the emergency
-user. When you have granted *super* privileges to at least one existing user,
-you can disable the emergency user account by setting `DISABLE_EMERGENCY_USER`
-to `true` in `general.yml`.
+user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`.
 
 Users with the superuser role also have extra privileges in the website
 front end, such as being able to categorise any request, being able to view
@@ -359,9 +340,211 @@ Once you have identified the request the message belongs to, you need to go back
 
 The message will now be associated with the correct request and will appear on the public request page.
 
-### Editing and uploading public body email addresses
-
-
+### Creating, changing and uploading public authority data
+
+There are three ways to change public authority data on your site:
+
+   * *Create* &mdash;
+     You can create a new public authority in the admin interface. Go to **Authorities**, and click the **New Public Authority** button.
+
+   * *Edit* &mdash;
+     Once an authority is created, you can update its email address or other
+     details by editing it in the admin interface. Go to **Authorities**, find
+     the authority you want to update, and click on **edit**.
+
+   * *Upload* &mdash;
+     You can also create or edit more than one authority at the same time by
+     uploading a file containing the data in comma-separated values (CSV)
+     format. This works for new authorities as well as those that already exist
+     on your site. Go to **Authorities** and click the **Import from CSV** button. See the rest of this section for more about uploading.
+
+The upload feature is useful &mdash; especially when an Alaveteli site is first
+set up &mdash; because it's common to collect data such as the contact details
+for the public authorities in a spreadsheet. Alaveteli's upload feature makes it
+easy to initially load this data onto the site. It also lets you update the
+data if it changes after it's already been loaded.
+
+To use the data in the spreadsheet to update the bodies on your site, export
+("save as") the spreadsheet as a CSV file. This is the file you can upload.
+
+The first line of your CSV file should start with `#` (this indicates that this
+line does not contain data) and must list the column names for the data that
+follows on the subsequent lines. Column names must:
+
+   * be on the first line
+   * match expected names *exactly*, and include `name` and `request_email`
+    (see table below)
+   * appear in the same order as corresponding items in the lines of data that follow
+
+Most spreadsheet programs will produce a suitable CSV file for you, provided
+that you carefully specify correct titles at the top of each column. Be sure to
+use names exactly as shown &mdash; if Alaveteli encounters an
+unrecognised column name, the import will fail.
+
+<table class="table">
+  <tr>
+    <th>column name</th>
+    <th>i18n suffix?</th>
+    <th>notes</th>
+  </tr>
+  <tr>
+    <td><code>name</code></td>
+    <td><em>yes</em></td>
+    <td>
+      <em>This column <strong>must</strong> be present.</em><br>
+      The full name of the authority.<br>
+      If it matches an existing authority's name, that authority will be
+      updated &mdash; otherwise, this will be added as a new authority.
+    </td>
+  </tr>
+  <tr>
+    <td><code>request_email</code></td>
+    <td><em>yes</em></td>
+    <td>
+      <em>This column <strong>must</strong> be present,
+      but can be left empty.</em><br>
+      The email to which requests are sent
+    </td>
+  </tr>
+  <tr>
+    <td><code>short_name</code></td>
+    <td><em>yes</em></td>
+    <td>Some authorities are known by a shorter name</td>
+  </tr>
+  <tr>
+    <td><code>notes</code></td>
+    <td><em>yes</em></td>
+    <td>Notes, displayed publicly (may contain HTML)</td>
+  </tr>
+  <tr>
+    <td><code>publication_scheme</code></td>
+    <td><em>yes</em></td>
+    <td>
+      The URL of the authority's
+      <a href="{{ site.baseurl }}docs/glossary/#publication-scheme" class="glossary__link">publication scheme</a>,
+      if they have one
+    </td>
+  </tr>
+  <tr>
+    <td><code>disclosure_log</code></td>
+    <td><em>yes</em></td>
+    <td>
+      The URL of the authority's
+      <a href="{{ site.baseurl }}docs/glossary/#disclosure-log" class="glossary__link">disclosure log</a>,
+      if they have one
+    </td>
+  </tr>
+  <tr>
+    <td><code>home_page</code></td>
+    <td>no</td>
+    <td>The URL of the authority's home page</td>
+  </tr>
+  <tr>
+    <td><code>tag_string</code></td>
+    <td>no</td>
+    <td>separated tags with spaces</td>
+  </tr>
+</table>
+
+   * Existing authorities cannot be renamed by uploading: if you need to do
+     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 
+     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.
+   * Columns with "i18n suffix" can accept
+     <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalised</a>
+     names. Add a full stop followed by the language code, for example:
+     `name.es` for Spanish (`es`). This *must* be a locale you've declared in
+     [`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales).
+     If you don't specify an i18n suffix, the default language for your site is
+     assumed.
+   * You can specify a blank entry in the CSV file by having no character
+     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 
+     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"`).
+
+For example, here's data for three authorities in CSV format ready for upload.
+The first line defines the column names, then the next three lines contain the
+data (one line for each authority):
+
+    #name,short_name,short_name.es,request_email,notes
+    XYZ Library Inc.,XYZ Library,XYX Biblioteca,info@xyz.example.com,
+    Ejemplo Town Council,,Ayuntamiento de Ejemplo,etc@example.com,Lorem ipsum.
+    "Comma, Inc.",Comma,,comma@example.com,"e.g. <a href=""x"">link</a>"
+
+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. 
+
+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.
+
+You can add a **Tag to add entries to / alter entries for**. This tag will
+be applied to every body that is imported from your CSV file.
+
+We always recommend you click **Dry run** first -- this will run through the
+file and report the changes it will make in the database, *without actually
+changing the data*. Check the report: it shows what changes would be made if
+you really uploaded this data, followed by a message like this:
+
+    Dry run was successful, real run would do as above.
+
+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 
+will repeat the process, but this time it will make the changes to your
+site's database.
+
+If you see an error like `invalid email`, either you really have mistyped an
+email address, or (more likely) your CSV file does not have a `request_email`
+column.
+
+#### Creating a spreadsheet of existing authorities
+
+You can easily create a spreadsheet containing the authorities that <em>already
+exist</em> on your site. Combined with the upload feature described above, this
+may be a more convenient way to update your data than editing it in the admin
+interface.
+
+To export the existing authorities' data, go to your site's home page (not the
+admin) and click <strong>View Authorities</strong>. Then click <strong>List of
+all authorities (CSV)</strong> to get a CSV file. You can then make changes to
+this file using a spreadsheet program and upload it as described above.
+
+You'll need to remove some columns that are not accepted by the import feature
+and possibly rename some that are &mdash; see the column names above.
+Also, note that by default the exported spreadsheet does not contain a
+`request_email` column. If you want to update email addresses, you should
+manually add a column to your spreadsheet with the heading `request_email` and
+fill in a new email address for each authority you want to update. Authorities
+with blank values in any column will keep their existing value for that
+attribute.
+
+<div class="attention-box info">
+Alaveteli never includes authorities which have the tag <code>site_administration</code> when it exports authorities in CSV format.
+If you're running a development server with the sample data, the single example
+body called "Internal admin authority" has this tag, so if you click
+<strong>List of all authorities (CSV)</strong>, you'll get a CSV file which
+contains no data. You need to add your own authorities (without the
+<code>site_administration</code> tag) before you can export them.
+</div>
 
 ### Banning a user