Improve documentation, update FSF address

This is the result of spell-checking and proof-reading all the
documentation shipped with mod_ucam_webauth.

CHANGES

@@ -14,6 +14,12 @@
 
  . Multiple C code fixes (const-correctness, error handling, etc.)
 
+ . Debian & Ubuntu .debs available
+
+ . Documentation fixes (typing errors, etc.)
+
+ . Update FSF's address in licence texts.
+
 1.4.4 - 2013-05-25 mcv21
 
  . Add support for Apache2.4. This required a small change to the code

COPYING

@@ -2,7 +2,7 @@
 		       Version 2.1, February 1999
 
  Copyright (C) 1991, 1999 Free Software Foundation, Inc.
-     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -483,9 +483,11 @@ convey the exclusion of warranty; and each file should have at least the
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.
 
+
     You should have received a copy of the GNU Lesser General Public
     License along with this library; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
+    MA  02110-1301  USA
 
 Also add information on how to contact you by electronic and paper mail.
 

INSTALL

@@ -1,5 +1,5 @@
      ===============================================================
-     University of Cambridge Web Authentication System (UcamWebauth)
+     University of Cambridge Web Authentication System (UcamWebAuth)
        Apache Authentication Agent (mod_ucam_webauth) Installation
      ===============================================================
 
@@ -18,7 +18,7 @@
 Note that a pre-compiled binary version of the module is available for
 use on Microsoft Windows. Windows users should see README.WIN32 and
 then read sections 3 'Operating requirements' and 4 'Initial
-Configuration' below.
+configuration' below.
 
 1. Build requirements
 =====================
@@ -38,18 +38,17 @@ Configuration' below.
 
 * OpenSSL
 
-  The module uses the OpenSSL library. Again this comes as part of
-  most Unix/Linux distributions, and again it may be necessary to
-  install an additional package, perhaps called openssl-devel for
+  The module uses the OpenSSL library. Again, this comes as part of
+  most Unix/Linux distributions, and it may be necessary to install an
+  additional package, perhaps called openssl-devel or libssl-dev, for
   access to the tools needed to build the module.
 
 * C compiler
 
-  The module is written in C and all installation options involve
-  compiling it from source so a C compiler is needed. Most Unix and
-  Linux distributions install a C compiler by default. MacOS users
-  should see INSTALL.Platforms for instructions on installing a C
-  compiler and related tools.
+  The module is written in C, so building the module requires a C
+  compiler. Most Unix and Linux distributions install a C compiler by
+  default. MacOS users should see INSTALL.Platforms for instructions
+  on installing a C compiler and related tools.
 
 
 2. Building and installing the module
@@ -62,9 +61,12 @@ Apache is normally built so that new modules can be built as 'shared
 objects' and plugged-in to Apache without having to rebuild the whole
 program. Apache provides a tool, called apxs, to manage this
 process. Providing your copy of Apache supports this, and most do,
-then it's the easiest way to build the module.
+then it's the easiest way to build the module. If, however, you run a
+RPM or .deb based linux distribution, then using the appropriate
+package will be more straightforward (see sections 2.2 & 2.3 below for
+details).
 
-You can check if you copy of Apache supports this feature by running
+You can check if your copy of Apache supports this feature by running
 it with the '-l' command line option - if mod_so.c is shown
 as one of the modules loaded then shared object support is available.
 
@@ -81,8 +83,8 @@ then issue the following command as root:
 
 If your copy of the OpenSSL library isn't in a standard place it may
 be necessary to modify the '-lcrypto' option. apxs may not be on
-root's default path and may be renamed, e.g. to apxs2, on some
-platforms - see INSTALL.Platforms for some further details. apxs and
+root's default path and may be renamed (e.g. to apxs2) on some
+platforms - see INSTALL.Platforms for further details. apxs and
 related files are sometimes provided by a httpd-devel, apache-devel,
 or apache2-devel package which will need to be installed.
 
@@ -92,8 +94,8 @@ or apache2-devel package which will need to be installed.
 
 The module is distributed as a pair of 'Source RPMs', one for Apache
 1.3 and one for Apache 2.0/2.1/2.2/2.4. On RPM-based Linux systems it
-is straight forward to use one of these to build a binary RPM which
-can then be installed as for any other package. This is particularly
+is straightforward to use one of these to build a binary RPM which
+can then be installed like any other package. This is particularly
 useful if you need to install the module on a number of similar
 systems. This approach will only work with copies of Apache that
 include shared object support (see above). This is almost always the
@@ -115,26 +117,31 @@ can be installed by issuing, e.g., the command
 
 Linux distributions vary somewhat in how they package Apache-related
 software so the source RPMs are unlikely to install on every possible
-system. Even with only a little experience of modifying RPMs it should
-be easy enough to install the source RPM and modify the '.spec' file
-to work with a new system. If you find you need to do this, please
-inform raven-support@ucs.cam.ac.uk so that any changes can be included
-in future versions.
+system. With a little experience of modifying RPMs it should be easy
+enough to install the source RPM and modify the '.spec' file to work
+with a new system. If you find you need to do this, please inform
+raven-support@ucs.cam.ac.uk so that any changes can be included in
+future versions.
 
 2.4 Installing from .deb
 ------------------------
 
-A binary .deb for "wheezy" (the current stable Debian release) on the
-amd64 architecture is available; if this is suitable for your system,
-you can install it thus:
+Binary .debs are available for Debian and Ubuntu. The Debian .debs
+should be suitable for releases from "wheezy" (the current stable
+release) onwards, whilst the Ubuntu .debs should be suitable for
+releases from "lucid" (10.04.4 LTS) onwards. They are available for
+i386 (32-bit) and amd64 (64-bit) archiectures. The four .debs have the
+following filenames:
 
-dpkg -i libapache-mod-ucam-webauth_<ver>_amd64.deb
+libapache2-mod-ucam-webauth_<ver>_amd64.deb        [Debian, 64-bit]
+libapache2-mod-ucam-webauth_<ver>_i386.deb         [Debian, 32-bit]
+libapache2-mod-ucam-webauth_<ver>ubuntu_amd64.deb  [Ubuntu, 64-bit]
+libapache2-mod-ucam-webauth_<ver>ubuntu_i386.deb   [Ubuntu, 32-bit]
 
-This binary package is also expected to work on the "precise",
-"quantal", and "raring" Ubuntu releases.
+Install the appropriate .deb using dpkg -i.
 
-Otherwise, you can build a binary .deb yourself; to do so, download
-libapache2-mod-ucam-webauth_<ver>.dsc and
+Alternatively, you can build a binary .deb yourself; to do so,
+download libapache2-mod-ucam-webauth_<ver>.dsc and
 libapache2-mod-ucam-webauth_<ver>.tar.gz, unpack the source archive:
 
 dpkg-source -x libapache-mod-ucam-webauth_<ver>.dsc
@@ -149,8 +156,8 @@ You can then install the resulting (unsigned) .deb as above.
 2.4  Static Linking
 -------------------
 
-Apache can be built with all modules linked into the main program - so
-called 'static linking'. To add mod_ucam_webauth to such an
+Apache can be built with all its modules linked into the main program
+- so-called 'static linking'. To add mod_ucam_webauth to such an
 installation it is necessary to copy the module into the unpacked
 Apache source tree and then to rebuild Apache.
 
@@ -189,29 +196,30 @@ Apache server. It should be listed as mod_ucam_webauth.c.
 
 * RSA Public Keys
 
-  UcamWebauth uses RSA public key cryptography to verify that
+  UcamWebAuth uses RSA public key cryptography to verify that
   authentication responses are sent only by the trusted authentication
   server. The module needs access to the relevant RSA public
   keys. Within the University of Cambridge, the keys used by the Raven
   service are available from https://raven.cam.ac.uk/project/keys/
 
   By default the module expects to find keys in a directory called
-  conf/webauth_keys/ within Apache's server's 'ServerRoot'
-  directory. INSTALL.Platforms documents server root for some
-  systems. If all else fails, trying to use the module with no keys
-  installed will result in an error message in the server's error log
-  which includes the expected path to the keys. The key file location
-  can also be set using the AAKeyDir directive (see README.Config).
-
-  The names of the key files should not be changed - beware that they
-  have no filename suffix but that some browsers may add .txt or
+  conf/webauth_keys/ within the Apache server's 'ServerRoot'
+  directory. INSTALL.Platforms documents the default ServerRoot for
+  some systems. If all else fails, trying to use the module with no
+  keys installed will result in an error message in the server's error
+  log which includes the expected path to the keys. The key file
+  location can also be set using the AAKeyDir directive (see
+  README.Config).
+
+  The names of the key files should not be changed - be aware that
+  they have no filename suffix but that some browsers may add .txt or
   similar when downloading them.
 
 * Timekeeping
 
   The protocol used to communicate between the module and the
   authentication server requires that both have access to accurate
-  time values. UcamWebauth servers use NTP (Network Time Protocol) to
+  time values. UcamWebAuth servers use NTP (Network Time Protocol) to
   set their clocks. Providing the server using the module has a clock
   synchronised by NTP or something similar then the default values for
   the time-related parameters in the module should be fine.
@@ -227,16 +235,16 @@ Apache server. It should be listed as mod_ucam_webauth.c.
 4. Initial configuration
 ========================
 
-If the module has been built as a dynamic shared objects then it must
+If the module has been built as a dynamic shared object then it must
 first be loaded into Apache. Your distribution may have its own way of
 managing modules (see INSTALL.Platforms) but a default Apache
 installation would require a 'LoadModule' directive such as:
 
   LoadModule ucam_webauth_module modules/mod_ucam_webauth.so
 
 in the Apache configuration file, replacing
-'modules/mod_ucam_webauth.so' if necessary with the path to the the
-file containing the module, relative to ServerRoot if it doesn't start
+'modules/mod_ucam_webauth.so' if necessary with the path to the file
+containing the module, relative to ServerRoot if it doesn't start
 '/'. This is not necessary if the module has been statically linked
 into the httpd program.
 
@@ -251,7 +259,7 @@ will also be required somewhere. mod_ucam_webauth does not depend on
 load order.
 
 The minimum configuration required to restrict access to resources in
-a particular directory to users with a Ucam-WebAuth login is, e.g.
+a particular directory to users with a UcamWebAuth login is, e.g.:
 
   AACookieKey "some random string"
   <Directory "/path/to/protected/directory">
@@ -262,8 +270,8 @@ a particular directory to users with a Ucam-WebAuth login is, e.g.
 The AACookieKey directive is required. It provides data used to sign
 and verify the session cookie, providing detection of any
 tampering. See README.Config for further important information about
-this. See standard Apache documentation for other ways to use the
-'Require' directive to restrict access to identified individuals.
+this. See the Apache documentation for other ways to use the 'Require'
+directive to restrict access to identified individuals.
 
 In this example the protected resources is selected with a <Directory>
 directive; resources specified by <Location> or <Files> directives can

INSTALL.Platforms

@@ -1,5 +1,5 @@
      ===============================================================
-     University of Cambridge Web Authentication System (UcamWebauth)
+     University of Cambridge Web Authentication System (UcamWebAuth)
                  Platform-specific Installation Notes
      ===============================================================
 
@@ -16,10 +16,9 @@ raven-support@ucs.cam.ac.uk
 1. Debian/Ubuntu
 ================
 
-Only Apache 2 is available, in the apache2 package.
-
-The binary .deb package (either the provided one for wheezy/amd64 or
-one compiled from the source package) will install the module
+Only Apache 2.2 is available, via the apache2 metapackage. Installing
+from a .deb file (see INSTALL for more details on how to obtain/build
+an appropriate .deb for your system) will install the module
 correctly; you can enable it with the command "a2enmod
 ucam_webauth". It will still require configuration to meet your needs,
 however.
@@ -29,9 +28,9 @@ apxs is installed as /usr/bin/apxs2
 Apache runs with a ServerRoot of /etc/apache2/
 
 The module should be installed into
-/usr/lib/apache2/modules/. According to Debian/Ubuntu conventions (see
-/etc/apache2/README), it should be loaded from a file in
-/etc/apache2/mods-available called ucam_webauth.load containing:
+/usr/lib/apache2/modules/. According to Debian/Ubuntu conventions, it
+should be loaded from a file in /etc/apache2/mods-available called
+ucam_webauth.load containing:
 
   LoadModule ucam_webauth_module /usr/lib/apache2/modules/mod_ucam_webauth.so
 
@@ -89,8 +88,8 @@ Apache logs are stored at /private/var/log/httpd/
 Apache on OS 10 server uses Apple's own authentication module,
 mod_auth_apple, in place of the standard Apache module, mod_auth. In
 OS version 10.4.6 (and probably in subsequent versions) mod_auth_apple
-won't inter-work with mod_ucam_webauth. Instructions for working
-around this problem appear in the wiki document noted above.
+is incompatible with mod_ucam_webauth. Instructions for working around
+this problem appear in the wiki document noted above.
 
 
 3. Red Hat, Fedora
@@ -157,8 +156,8 @@ Linux 10.1 and OpenSuSE 10.2.
 
 apxs is installed as /usr/sbin/apxs2. Alternate versions
 (apxs2-prefork, apxs2-worker, etc) are available for building modules
-customise for particular MPMs (see
-/usr/share/doc/packages/apache2/README.SuSE)
+customised for particular MPMs (see
+/usr/share/doc/packages/apache2/README.SUSE)
 
 Apache runs with a ServerRoot of /srv/www/
 
@@ -205,19 +204,19 @@ All versions
 
 See README.WIN32. Binary builds of the module are available - the
 correct binary module must be used to match the version of Apache in
-use (1.3, 2.0, or 2.2).
+use (2.2 or 2.4).
 
 By default, the Apache project binary installer installs into one of
 the following. This is the default ServerRoot:
 
-  C:\Program Files\Apache Group\Apache\                  [Apache 1.3]
-  C:\Program Files\Apache Group\Apache2\                 [Apache 2.0]
   C:\Program Files\Apache Software Foundation\Apache2.2\ [Apache 2.2]
+  C:\Program Files\Apache Software Foundation\Apache2.4\ [Apache 2.4]
 
 The module should be installed into the modules\ directory within the
-apache directory. The 'Microsoft Visual C++ 2005 Redistributable
-Package' supplied in the file vcredist_x86.exe must be installed if
-not already present.
+apache directory. The 'Microsoft Visual C++ 2010 Redistributable
+Package' supplied in the file vcredist_x86.exe or vcredist_x64.exe
+(for 32-bit or 64-bit versions of Windows) must be installed if not
+already present.
 
 The module should be loaded with a LoadModule line in httpd.conf or
 otherwise in a file included into httpd.conf:

README

@@ -1,10 +1,10 @@
      ===============================================================
-     University of Cambridge Web Authentication System (UcamWebauth)
+     University of Cambridge Web Authentication System (UcamWebAuth)
      ===============================================================
 
 The University of Cambridge Web Authentication System Apache
 Authentication Agent (mod_ucam_webauth) allows Apache to use a
-Cambridge Web Authentication System (UcamWebauth) to identify
+Cambridge Web Authentication System (UcamWebAuth) to identify
 users. Within the University, such a system is provided by Raven:
 http://raven.cam.ac.uk/.
 
@@ -35,9 +35,8 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
-License along with this toolkit; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-USA
+License along with this toolkit. If not, see
+<http://www.gnu.org/licenses/>.
 
 See the file COPYING for details.