diff options
Diffstat (limited to 'docs/glossary.md')
| -rw-r--r-- | docs/glossary.md | 351 |
1 files changed, 299 insertions, 52 deletions
diff --git a/docs/glossary.md b/docs/glossary.md index 3ae5e6a3c..6b3eedca3 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -15,24 +15,29 @@ Definitions ----------- <ul class="definitions"> - <li><a href="#alaveteli">Alaveteli</a></li> <li><a href="#admin">admin interface</a></li> + <li><a href="#advanced-search">advanced search</a></li> + <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="#bounce-message">bounce message</a></li> <li><a href="#capistrano">Capistrano</a></li> + <li><a href="#category">category</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="#mta">Mail Transfer Agent</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> @@ -41,46 +46,19 @@ Definitions <li><a href="#response">response</a></li> <li><a href="#rails">Ruby on Rails</a></li> <li><a href="#sass">Sass</a></li> + <li><a href="#spam-address-list">spam address list</a></li> <li><a href="#staging">staging site</a></li> <li><a href="#state">state</a></li> <li><a href="#super">superuser</a></li> + <li><a href="#tag">tag</a></li> <li><a href="#theme">theme</a></li> + <li><a href="#wdtk">WhatDoTheyKnow</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="https://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="https://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="admin">admin interface</a> (also: admin) </dt> <dd> @@ -102,7 +80,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> @@ -115,6 +93,61 @@ Definitions </dd> <dt> + <a name="advanced-search">advanced search</a> + </dt> + <dd> + Alaveteli's <strong>advanced search</strong> lets users search using + more complex criteria than just words. This includes Boolean operators, + date ranges, and specific indexes such as <code>status:</code>, + <code>requested_by:</code>, <code>status:</code> and so on. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + Advanced search is available on your Alaveteli site at + <code>/advancedsearch</code>. That page shows suggestions and examples + of the searches that are supported. + </li> + <li> + For more about constructing complex queries, see + <a href="http://xapian.org/docs/queryparser.html">Xapian + search parser</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="alaveteli">Alaveteli</a> + </dt> + <dd> + <strong>Alaveteli</strong> is the name of the open source software platform created + by <a href="https://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="#wdtk" class="glossary__link">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> @@ -144,7 +177,8 @@ Definitions <p>More information:</p> <ul> <li> - An administrator can add, edit, or remove authorities in the admin + An <a href="#super" class="glossary__link">administrator</a> + 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 @@ -154,6 +188,10 @@ Definitions 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> + <li> + You can organise your authorities using + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a>. + </li> </ul> </div> </dd> @@ -224,6 +262,34 @@ Definitions </dd> <dt> + <a name="category">category</a> + </dt> + <dd> + You can arrange your <a href="#authority" class="glossary__link">authorities</a> + into <strong>categories</strong> so that they are easier for your users + to find. For example, you might put all different schools into the + "School" category, and universities into "Universities". You can also + group categories under headings (such as "Education"). + <p> + These categories and headings appear on the list of public authorities that + is displayed on your site. + </p> + <p> + Use <a href="#tag" class="glossary__link">tags</a> to associate + authorities with specific categories. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + </li> + </ul> + </div> + </dd> + + <dt> <a name="censor-rule">censor rule</a> </dt> <dd> @@ -268,6 +334,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 +371,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> @@ -364,24 +450,78 @@ Definitions <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. + The <strong>holding pen</strong> is the conceptual place where responses + that could not be delivered are held. They need attention from an + <a href="#super" class="glossary__link">administrator</a>. + <p> + In fact, the holding pen is really a special "sticky" <a href="#request" + class="glossary__link">request</a> that only exists to accept unmatched + responses. Whenever Alaveteli receives an email but can't work out which + request it is a response to, it attaches it to the holding pen instead. + </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 + 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 </li> + <li> + The most common reason for a response to be in the holding pen is that + an <a href="#authority" class="glossary__link">authority</a> replied + to a request with the wrong email address (for example, by copying + the email address incorrectly). + </li> </ul> </div> </dd> <dt> - <a name="mta">MTA</a> (Mail Transfer Agent) + <a name="i18n">internationalisation</a> (also: i18n) </dt> <dd> - A <strong>Mail Tranfer Agent</strong> is the the program which actually sends + <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">Mail Transfer Agent</a> (MTA) + </dt> + <dd> + A <strong>Mail Transfer 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__link">responses</a> and replies it receives. All this email goes through the MTA, which is a seperate service on your system. @@ -428,12 +568,13 @@ Definitions <a name="po"><code>.po</code> file</a> (and <code>.pot</code> file) </dt> <dd> - These are the files needed by the gettext mechanism Alaveteli uses for - localisation. A <code>.pot</code> file is effectively a list of all the - strings in the application that need translating. Each <code>.po</code> - file contains the mapping between those strings, used as keys, and their - translations for one particular language. The key is called the - <em>msgid</em>, and its corresponding translation is the <em>msgstr</em>. + These are the files needed by the <code>gettext</code> mechanism Alaveteli + uses for localisation. A <code>.pot</code> file is effectively a list of + all the strings in the application that need translating. Each + <code>.po</code> file contains the mapping between those strings, used as + keys, and their translations for one particular language. The key is called + the <em>msgid</em>, and its corresponding translation is the + <em>msgstr</em>. <div class="more-info"> <p>More information:</p> <ul> @@ -450,6 +591,11 @@ Definitions website, which lets translators work on Alaveteli in a browser, without needing to worry about this underlying structure. </li> + <li> + See more about the + <a href="https://www.gnu.org/software/gettext/"><code>gettext</code> + system</a>. + </li> </ul> </div> </dd> @@ -500,6 +646,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> @@ -619,7 +788,7 @@ Definitions </li> <li> We try to coordinate releases with any active translation work too. - See <a href="http://localhost:4000/docs/customising/translation/">translating + See <a href="{{ site.baseurl }}docs/customising/translation/">translating Alaveteli</a> for more information. </li> <li> @@ -699,6 +868,33 @@ Definitions </dd> <dt> + <a name="spam-address-list">spam address list</a> + </dt> + <dd> + Alaveteli maintains a <strong>spam address list</strong>. Any incoming message to an email + address on that list will be rejected and won't appear in the admin. + <p> + This is mainly for email addresses whose messages are ending up + in the <a href="#holding_pen" class="glossary__link">holding pen</a>, because + those are typically addresses that can be safely ignored as they do not + relate to an active <a href="#request" class="glossary__link">request</a>. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + To add addresses to the spam address list , see + <a href="{{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting + spam that arrives in the holding pen</a>. + </li> + <li> + The spam address list is available on your site at <code>/admin/spam_addresses</code>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="staging">staging server</a> (also: staging site) </dt> <dd> @@ -757,12 +953,19 @@ Definitions </dd> <dt> - <a name="super">superuser</a> (also: super privilege) + <a name="super">superuser</a> (also: super privilege, administrator) </dt> <dd> - A <strong>superuser</strong> is an Alaveteli user who has been granted - the privilege to use all features of the - <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>. + A <strong>superuser</strong>, or <strong>administrator</strong>, is an + Alaveteli user who has been granted the privilege to use all features of the + <a href="{{ site.baseurl }}docs/glossary/#admin" + class="glossary__link">admin interface</a>. + <p> + The only way to access the admin without being an Alaveteli superuser + is as the <a href="{{ site.baseurl }}docs/glossary/#emergency" + class="glossary__link">emergency user</a>, which should be disabled in + normal operation. + </p> <div class="more-info"> <p>More information:</p> <ul> @@ -773,7 +976,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> @@ -799,4 +1002,48 @@ Definitions </div> </dd> + <dt> + <a name="tag">tag</a> + </dt> + <dd> + A <strong>tag</strong> is a keyword added to an + <a href="#authority" class="glossary__link">authority</a>. Tags + are searchable, so can be useful to help users find authorities based + by topic or even unique data (for example, in the + <a href="#wdtk" class="glossary__link">WhatDoTheyKnow</a> we tag every + registered charity with its official charity number). You can also use + tags to assign authorities to + <a href="#category" class="glossary__link">categories</a>. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + </li> + </ul> + </div> + </dd> + + <dt> + <a name="wdtk">WhatDoTheyKnow</a> + </dt> + <dd> + The website <strong>WhatDoTheyKnow</strong>.com is the UK installation of + Alaveteli, run by <a href="http://mysociety.org">mySociety</a>. + <p> + In fact, WhatDoTheyKnow predates Alaveteli because the site started in + 2008, and was the foundation of the redeployable, customisable + Alaveteli plattorm released in 2011. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow.com</a> + </li> + </ul> + </div> + </dd> + </dl> |