diff options
Diffstat (limited to 'docs/glossary.md')
| -rw-r--r-- | docs/glossary.md | 380 |
1 files changed, 358 insertions, 22 deletions
diff --git a/docs/glossary.md b/docs/glossary.md index b5239a32a..585ca67be 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -15,23 +15,30 @@ Definitions ----------- <ul class="definitions"> + <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="#categorisation-game">categorisation game</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> @@ -40,15 +47,79 @@ 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="#transifex">Transifex</a></li> + <li><a href="#wdtk">WhatDoTheyKnow</a></li> </ul> <dl class="glossary"> <dt> + <a name="admin">admin interface</a> (also: admin) + </dt> + <dd> + The <strong>admin interface</strong> allows users who have + <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> + administrator privilege to manage some aspects of how your + Alaveteli site runs. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + You can access your installation's <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> + at <code>/admin</code>. + </li> + <li> + To grant a user admin privilege, log into the admin and change + their <em>Admin level</em> to "super" (or revoke the privilege + by changing it to "none"). + </li> + <li> + On a newly-installed Alaveteli system, you can grant yourself + admin privilege by using the + <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + user</a>. + </li> + <li> + For lots more about running an Alaveteli site, see the + <a href="{{ site.baseurl }}running/admin_manual">adminstrator's guide</a>. + </li> + </ul> + </div> + </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> @@ -57,7 +128,7 @@ Definitions managing and archiving Freedom of Information requests. <p> It grew from the successful FOI UK project - <a href="https://www.whatdotheyknow.com">WhatDoTheyKnow</a>. + <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> @@ -108,7 +179,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 @@ -118,6 +190,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> @@ -188,6 +264,41 @@ 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> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> +</dd> + <dt> + <a name="categorisation-game">categorisation game</a> + </dt> + <dd> + The categorisation game is a way that users of an Alaveteli site can help the site stay current and accurate by updating the status of old requests where the original requester has never said whether the authority responded with the information or not. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + the categorisation game on the <a href="http://demo.alaveteli.org/categorise/play">demo Alaveteli site</a>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="censor-rule">censor rule</a> </dt> <dd> @@ -232,6 +343,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> @@ -249,7 +380,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> @@ -266,7 +397,7 @@ Definitions </dd> <dt> - <a name="foi">Freedom of Information</a> (also FOI) + <a name="foi">Freedom of Information</a> (also: FOI) </dt> <dd> <strong>Freedom of information</strong> laws allow access by the general public @@ -287,7 +418,7 @@ Definitions </dd> <dt> - <a name="git">git</a> (also github, git repository, and git repo) + <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 @@ -328,24 +459,79 @@ 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 - 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 + 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. @@ -392,12 +578,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> @@ -410,10 +597,15 @@ Definitions Alaveteli</a> for more technical details. </li> <li> - Alaveteli is on the <a href="https://www.transifex.net/projects/p/alaveteli/">Transifex</a> + Alaveteli is on the <a href="https://www.transifex.com/projects/p/alaveteli/">Transifex</a> 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> @@ -464,6 +656,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> @@ -583,7 +798,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> @@ -617,7 +832,7 @@ Definitions </dd> <dt> - <a name="rails">Ruby on Rails</a> (also Rails) + <a name="rails">Ruby on Rails</a> (also: Rails) </dt> <dd> Alaveteli is written in the Ruby programming language, using @@ -663,6 +878,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> @@ -721,6 +963,62 @@ Definitions </dd> <dt> + <a name="super">superuser</a> (also: super privilege, administrator) + </dt> + <dd> + 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> + <li> + To grant a user admin privilege, log into the admin and change + their <em>Admin level</em> to "super" (or revoke the privilege + by changing it to "none"). + </li> + <li> + On a newly-installed Alaveteli system, you can grant yourself + admin privilege by using the + <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + user</a>. + </li> + </ul> + </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="theme">theme</a> </dt> <dd> @@ -728,11 +1026,49 @@ Definitions 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> + <dt> + + <a name="transifex">Transifex</a> + </dt> + <dd> + + <a href="https://www.transifex.com/">Transifex</a> is a website that helps translators add translations for software projects. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + The Transifex project for Alaveteli is at <a href="https://www.transifex.com/projects/p/alaveteli">https://www.transifex.com/projects/p/alaveteli</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="{{ site.baseurl }}docs/customising/themes/">about themes</a> + <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow.com</a> </li> </ul> </div> |