path: root/docs/glossary.md

---
layout: page
title: Glossary
---

Glossary
====================

<p class="lead">
  Glossary of terms for Alaveteli, mySociety's freedom of information
  platform.
</p>

Definitions
-----------

<ul class="definitions">
  <li><a href="#alaveteli">Alaveteli</a></li>
  <li><a href="#agnostic">asker agnostic</a></li>
  <li><a href="#authority">authority</a></li>
  <li><a href="#blackhole">black hole</a></li>
  <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="#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="#mta">MTA</a></li>
  <li><a href="#production">production site</a></li>
  <li><a href="#publish">publish</a></li>
  <li><a href="#recaptcha">recaptcha</a></li>
  <li><a href="#redact">redacting</a></li>
  <li><a href="#regexp">regular expression</a></li>
  <li><a href="#request">request</a></li>
  <li><a href="#response">response</a></li>
  <li><a href="#rails">Ruby&nbsp;on&nbsp;Rails</a></li>
  <li><a href="#sass">Sass</a></li>
  <li><a href="#staging">staging site</a></li>
  <li><a href="#state">state</a></li>
  <li><a href="#theme">theme</a></li>
</ul>


<dl class="glossary">

  <dt>
    <a name="alaveteli">Alaveteli</a>
  </dt>
  <dd>
    <strong>Alaveteli</strong> is the name of the open source software platform created
    by <a href="http://www.mysociety.org">mySociety</a> for submitting,
    managing and archiving Freedom of Information requests.
    <p>
      It grew from the successful FOI UK project
      <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow</a>.
      We use the name <em>Alaveteli</em> to distinguish the software
      that runs the platform from any specific website that it is powering.
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          The Alaveteli website is at <a href="http://www.alaveteli.org">www.alaveteli.org</a>
        </li>
        <li>
          The name "Alaveteli" comes from
          <a href="http://en.wikipedia.org/wiki/Alaveteli,_Finland">Alaveteli in Finland</a>
          where
          <a href="http://en.wikipedia.org/wiki/Anders_Chydenius">an early FOI campaigner</a>
          once worked.
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="agnostic">asker agnostic</a>
  </dt>
  <dd>
    <a href="#foi" class="glossary">Freedom of Information</a> (FoI) law typically considers
    the <a href="#response" class="glossary">responses</a> given by the
    <a href="#authority" class="glossary">authorities</a> to be <strong>asker agnostic</strong>. This means
    that the reply should not be any different depending on <em>who</em> asked for the
    information. One consequence of this is that the response
    can be <a href="#publish" class="glossary">published</a>, because in theory <em>everyone</em>
    could ask for it and expect, by law, to receive the same information.
    <p>
      Despite this, it's still very common all around the world for authorities to reply
      to FoI requests privately, instead of publishing their responses themselves. One of the
      functions of Alaveteli is, therefore, to act as a public repository of published answers.
      This also serves to reduce duplicate requests, by publishing the answer instead of
      requiring it to be asked again.
    </p>
  </dd>

  <dt>
    <a name="authority">authority</a>
  </dt>
  <dd>
    An <strong>authority</strong> is the term we use for any of the bodies, organisations,
    departments, or companies to which users can send <a href="#request" class="glossary">requests</a>.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          An administrator can add, edit, or remove authorities in the admin
        </li>
        <li>
          Authorities are usually, but not always, public bodies that are obliged by the local
          <a href="#foi" class="glossary">Freedom of Information</a> (FoI) law to respond. Sometimes an
          Alaveteli site is set up in a jurisdiction that does not yet have FoI law. In the UK,
          we add some authorites to our <a href="https://www.whatdotheyknow.com">WhaDoTheyKnow</a>
          site that are not subject to FoI law, but which have either voluntarily submitted themselves
          to it, or which we believe should be accountable in this way.
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="blackhole">black hole</a>
  </dt>
  <dd>
    A <strong>black hole</strong> is an email address that accepts and destroys
    any email messages that are sent to it. Alaveteli uses this for "do not
    reply" emails, which are usually automatically generated system emails.
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          Use the config setting
          <code><a href="{{site.baseurl}}docs/customising/config/#blackhole_prefix">BLACKHOLE_PREFIX</a></code>
          to specify what this email address looks like.
        </li>
        <li>
          Conversely, see
          <code><a href="{{site.baseurl}}docs/customising/config/#contact_email">CONTACT_EMAIL</a></code>
          to specify the email address to which users' emails (such as support
          enquiries) will be delivered.
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="capistrano">Capistrano</a>
  </dt>
  <dd>
    <strong>Capistrano</strong> is a remote server automation and deployment tool written in Ruby.
    Alaveteli's deployment mechanism, which is optional, uses it.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          how to <a href="{{ site.baseurl }}docs/installing/deploy">deploy Alaveteli</a> (and why it's
          a good idea)
        </li>
        <li>
         The <a href="http://capistranorb.com/">Capistrano website</a> has thorough documentation
         about the tool
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="censor-rule">censor rule</a>
  </dt>
  <dd>
    Alaveteli administrators can define <strong>censor rules</strong> to define
    which parts of replies or responses should be
    <a href="#redact" class="glossary">redacted</a>.
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          see the
          <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a>
          for more about censor rules
        </li>
        <li>
          censor rules may simply redact text that exactly matches a
          particular sentence or phrase, or may use
          <a href="regexp">regular expressions</a>
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="development">development site</a> (also: dev, development server)
  </dt>
  <dd>
    A <strong>dev server</strong> is one that is running your Alaveteli site
    so you can <a href="{{ site.baseurl }}docs/customising/">customise it</a>, experiment
    with different settings, and test that it does what you expect.
    This is different from a
    <a href="#production" class="glossary">production server</a>, which is the one your
    users actually visit running with live data, or a
    <a href="#staging" class="glossary">staging server</a>,
    which is used for testing code before it goes live.
    <p>
      On your dev server, you should set
      <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code>
      to <code>1</code>.
    </p>
  </dd>

  <dt>
    <a name="foi">Freedom of Information</a> (also FOI)
  </dt>
  <dd>
    <strong>Freedom of information</strong> laws allow access by the general public
    to data held by national governments. They establish a "right-to-know"
    legal process by which requests may be made for government-held
    information, to be received freely or at minimal cost, barring standard
    exceptions.
    <br>
    <em>[from wikipedia]</em>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          Wikipedia summary of <a href="http://http://en.wikipedia.org/wiki/Freedom_of_information_laws_by_country">FOI laws by country</a>.
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="git">git</a> (also github,  git repository, and git repo)
  </dt>
  <dd>
    We use a popular source code control system called <strong>git</strong>. This
    helps us track changes to the code, and also makes it easy for other people
    to duplicate and even contribute to our software.
    <p>
      The website <a href="http://github.com/mysociety">github.com</a> is a central, public
      place where we make our software available. Because it's Open Source, you can
      inspect the code there (Alaveteli is mostly written in the programming language
      Ruby), report bugs, suggest features and many other useful things.
    </p>
    <p>
      The entire set of files that form the Alaveteli platform is called the
      <strong>git repository</strong> or <strong>repo</strong>. When you
      install Alaveteli, you are effectively cloning our repository on your
      own machine.
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          See the <a href="{{ site.baseurl }}docs/installing">installation instructions</a> which will
          clone the Alaveteli repo.
        </li>
        <li>
          Everything about git from the <a
          href="//http://git-scm.com">official website</a>.
        </li>
        <li>
          See <a href="http://github.com/mysociety">the mySociety projects on
          github</a>.
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="holding pen">holding pen</a>
  </dt>
  <dd>
    The <strong>holding pen</strong> is the conceptual place where responses that
    could not be delivered are held. They need attention from a administrator.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          see the <a href="{{ site.baseurl }}docs/running/admin_manual">admin manual</a> for
          information on dealing with emails in the holding pen
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="mta">MTA</a> (Mail Transfer Agent)
  </dt>
  <dd>
    A <strong>Mail Tranfer Agent</strong> is the the program which actually sends
    and receives email. Alaveteli sends email on behalf of its users, and processes
    the <a href="#response" class="glossary">responses</a> and replies it receives.
    All this email goes through the MTA, which is a seperate service on your system.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          see these instructions for <a href="{{ site.baseurl }}docs/installing/email">configuring your MTA</a>
          (examples are for exim4 and postfix, two of the most common)
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="production">production site</a> (also: live, production server)
  </dt>
  <dd>
    A <strong>production server</strong> is one that is running your Alaveteli site
    for real users, with live data. This is different from a
    <a href="#development" class="glossary">development server</a>, which you use make your
    customisation and environment changes and try to get them to all work OK, or a
    <a href="#staging" class="glossary">staging server</a>, which is used for testing code
    and configuration after it's been finished but before it goes live.
    <p>
      Your production site should be configured to run as efficiently as possible: for
      example, caching is enabled, and debugging switched off.
      <a href="#rails" class="glossary">Rails</a> has a "production mode" which does
      this for you: set
      <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code>
      to <code>0</code>. Note that if you <em>change</em> this setting after you've
      deployed, the <code>rails_env.rb</code> file that enables Rails's production
      mode won't be created until you run <code>rails-post-deploy</code>.
    <p>
      If you have a staging server, the system environment of your staging and
      production servers should be identical.
    </p>
    <p>
      You should never need to edit code directly on your production server.
      We strongly recommend you use Alaveteli's
      <a href="{{ site.baseurl }}docs/installing/deploy/">deployment mechanism</a>
      (using Capistrano) to make changes to your production site.
    </p>
  </dd>

  <dt>
    <a name="publish">publish</a>
  </dt>
  <dd>
    Alaveteli works by <strong>publishing</strong> the
    <a href="#response" class="glossary">responses</a> it recieves to the
    <a href="#foi" class="glossary">Freedom of Information</a>
    <a href="#request" class="glossary">requests</a> that its users send.
    It does this by processing the emails it receives and presenting them
    as pages &mdash; one per request &mdash; on the website. This makes it
    easy for people to find, read, link to, and share the request and the
    information provided in response.
  </dd>

  <dt>
    <a name="response">response</a>
  </dt>
  <dd>
    A <strong>response</strong> is the email sent by an
     <a href="#authority" class="glossary">authority</a> in reply to
     a user's  <a href="#request" class="glossary">requests</a>.
  </dd>

  <dt>
    <a name="recaptcha">recaptcha</a>
  </dt>
  <dd>
    <strong>Recaptcha</strong> is a mechanism that deters non-human users,
    such as automated bots, from submitting requests automatically.
    It requires the (human) user to identify a pattern of letters presented
    in an image, which is difficult or impossible for a non-human to
    do. Alaveteli uses this to prevent incoming spam.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          use the config settings
          <code><a href="{{site.baseurl}}docs/customising/config/#recaptcha_public_key">RECAPTCHA_PUBLIC_KEY</a></code>
          and
          <code><a href="{{site.baseurl}}docs/customising/config/#recaptcha_private_key">RECAPTCHA_PRIVATE_KEY</a></code>
          to set this up.
        </li>
        <li>
          see the <a href="http://www.google.com/recaptcha/">recaptcha website</a> for more details
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="redact">redacting</a> (also: redaction)
  </dt>
  <dd>
    <strong>Redacting</strong> means removing or hiding part of a message so it
    cannot be read: you are effectively removing part of a document from
    your site.
    <p>
      This may be necessary for a variety of reasons. For example, a user may
      accidentally put personal information into their request, or an
      authority may include it in their response. You may also need to
      redact parts of requests or responses that are libellous or legally
      sensitive.
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          see the
          <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a>
          for more about how and when you may need to redact information
        </li>
        <li>
          you can do text-only redaction with Alaveteli's
          <a href="#censor-rule" class="glossary">censor rules</a>
        </li>
        <li>
          some things are easier to redact than others &mdash; especially in PDFs,
          things like signatures or images can be difficult to partially remove.
          In such cases, you may need to remove the document entirely.
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="regexp">regular expression</a> (also: regexp)
  </dt>
  <dd>
    A <strong>regular expression</strong> is a concise way to describe a
    pattern or sequence of characters, letters or words. As an administrator,
    you may find regular expressions useful if you need to define <a
    href="#censor-rule" class="glossary">censor rules</a>. For example, instead
    of <a href="#redact" class="glossary">redacting</a> just one specific
    phrase, you can describe a whole range of <em>similar</em> phrases with one
    single regular expression.
    <p>
      Regular expressions can be complicated, but also powerful. If you're not
      familiar with using them, it's easy to make mistakes. Be careful!
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          for example, the regular expression
          <code>Jo(e|ey|seph)\s+Blogg?s</code> would match names
          including
          "<code>Joe Bloggs</code>", "<code>Joey Bloggs</code>" and
          "<code>Joseph Blogs</code>", but not
          "<code>John Bloggs</code>".
        </li>
        <li>
          see <a href="http://en.wikibooks.org/wiki/Regular_Expressions"><em>Regular
          Expressions</em> on wikibooks</a> for more information
        </li>
    </div>
  </dd>

  <dt>
    <a name="request">request</a>
  </dt>
  <dd>
    In Alaveteli, a <strong>request</strong> is the
    <a href="#foi" class="glossary">Freedom of Information</a> request
    that a user enters, and which the site then emails to the relevant
    <a href="#authority" class="glossary">authority</a>.
    Alaveteli automatically <a href="#publish" class="glossary">publishes</a>
    the <a href="#response" class="glossary">responses</a>
    to all the requests it sends.
  </dd>

  <dt>
    <a name="rails">Ruby on Rails</a> (also Rails)
  </dt>
  <dd>
    Alaveteli is written in the Ruby programming language, using
    the web application framework "Ruby on Rails".
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          <a href="http://rubyonrails.org/">Ruby on Rails</a> website
        </li>
        <li>
          Alavateli's <a href="{{ site.baseurl }}docs/developers/directory_structure/">directory structure</a>
          is influenced by its use of Ruby on Rails
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="sass">Sass</a> (for generating CSS)
  </dt>
  <dd>
    Alaveteli's cascading stylesheets (CSS) control how the pages appear, and
    are defined using <strong>Sass</strong>. It's technically a CSS extension
    language, and we use it because it's easier to manage than writing CSS
    directly (for example, Sass lets you easily make a single change that will
    be applied to many elements across the whole site).
    <a href="#rails" class="glossary">Rails</a> notices if you change any of
    the Sass files, and automatically re-generates the CSS files that the
    website uses.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          <a href="http://sass-lang.com">Sass website</a>
        </li>
        <li>
          more about <a href="{{ site.baseurl }}docs/customising/themes/#changing-the-colour-scheme">changing
          your colour scheme</a>, which uses Sass
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="staging">staging server</a> (also: staging site)
  </dt>
  <dd>
    A <strong>staging server</strong> is one that you use for testing code or configuration
    before it goes live. This is different from a <a href="#development"
    class="glossary">development server</a>, on which you change the code and settings to
    make everything work, or the
    <a href="#production" class="glossary">production server</a>, which is the
    site your users visit running with live data.
    <p>
      On your staging server, you should set
      <code><a href="{{site.baseurl}}docs/customising/config/#staging_site">STAGING_SITE</a></code>
      to <code>1</code>.
    </p>
    <p>
      If you have a staging server, the system environment of your staging and
      production servers should be identical.
    </p>
    <p>
      You should never need to edit code directly on your production or staging servers.
      We strongly recommend you use Alaveteli's
      <a href="{{ site.baseurl }}docs/installing/deploy/">deployment mechanism</a>
      (using Capistrano) to make changes to these sites.
    </p>
  </dd>

  <dt>
    <a name="state">state</a>
  </dt>
  <dd>
    Each <a href="#request" class="glossary">request</a> passes through different
    <strong>states</strong> as it progresses through the system.
    States help Alaveteli administrators, as well as the public,
    understand the current situation with any request and what
    action, if any, is required.
    <p>
      The states available can be customised within
      your site's <a href="#theme" class="glossary">theme</a>.
    </p>
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
          <a href="{{ site.baseurl }}docs/running/states">example states for WhatDoTheyKnow</a>
          (Alaveteli site running in the UK)
        </li>
        <li>
          for comparison, <a href="{{ site.baseurl }}docs/running/states_informatazyrtare">example states for InformataZyrtare</a>
          (Alaveteli site running in Kosovo)
        </li>
        <li>
          to customise or add your own states, see <a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a>
        </li>
      </ul>
    </div>
  </dd>

  <dt>
    <a name="theme">theme</a>
  </dt>
  <dd>
    A <strong>theme</strong> is the collection of changes to the templates
    and the code that causes the site to look or behave differently from the
    default. Typically you'll need a theme to make Alaveteli show your own
    brand.
    <div class="more-info">
      <p>More information:</p>
      <ul>
        <li>
      <a href="{{ site.baseurl }}docs/customising
/themes">about themes</a>
        </li>
      </ul>
    </div>
  </dd>

</dl>