More proof-reading of documentation.

galene-install.md

@@ -180,7 +180,7 @@ galenectl set-password -group city-watch -user vimes
 ```
 
 You should now be able to test your Galene installation by pointing a web
-browser at <https://galene.example.org:8443/group/testing/>.
+browser at <https://galene.example.org:8443/group/city-watch/>.
 
 Create an ordinary user:
 
@@ -201,7 +201,7 @@ information.
 
 ## Advanced configuration
 
-Galene is designed to be exposed directly to the internet.  If your server
+Galene is designed to be exposed directly to the Internet.  If your server
 is behind a firewall or NAT router, some extra configuration is necessary.
 
 ### Running behind a firewall
@@ -234,7 +234,7 @@ failures, this is nothing to worry about.
 
 If your server is behind NAT, then currently the only option is to use
 a STUN, or, preferably, TURN server on a separate host, one that is not
-behind NAT.  See Section "Connectivity issues and ICE servers" below.
+behind NAT.  See Section *Connectivity issues and ICE servers* below.
 
 Galene has some support for running behind NAT without a helpful server,
 but this has not been exhaustively tested.  Please see the section
@@ -274,7 +274,7 @@ Galene over plain HTTP instead of HTTPS by using the command-line flag
 
 Note that even if you're using a reverse proxy, clients will attempt to
 establish direct UDP flows with Galene and direct TCP connections to
-Galene's TURN server; see the section on "Configuring your firewall"
+Galene's TURN server; see the section *Configuring your firewall*
 above.
 
 ## Connectivity issues and ICE servers

galene.md

@@ -1,7 +1,7 @@
 # Galene manual
 
 Please see the file [galene-install.md][1] for installation instructions.
-Please see the section "Server administration" below for detailed
+Please see the section *Server administration* below for detailed
 administration instructions.
 
 ## Usage
@@ -38,7 +38,7 @@ chat.
 
 ### Buttons
 
-There are up to three buttons at the top.  The most important is The
+There are up to three buttons at the top.  The most important is the
 *Enable*/*Disable* button, which switches on or off both the camera and
 the microphone.
 
@@ -52,14 +52,14 @@ individual window.
 
 There is a menu on the right of the user interface.  It allows switching
 off the camera (for audio-only sessions), choosing the camera and
-microphone and setting the video throughput.  The *Blackboard mode*
+microphone, and setting the video throughput.  The *Blackboard mode*
-checkbox increases resolution and sacrifices framerate in favour of image
+checkbox increases resolution and sacrifices frame rate in favour of image
-quality.  The *Play local file* dialog streams a video from a local file.
+quality.  The *Play local file* dialogue streams a video from a local file.
 
 ### User list
 
 There is a user list on the left, starting with the current user and
-continuing with all users that have joined the current group.
+followed by all the users that have joined the current group.
 
 The user list doubles as a set of menus.  Clicking on the current user (the
 first entry in the user list) opens the *group menu*, a menu with actions
@@ -68,7 +68,7 @@ a *user menu*, a menu that applies to that specific user.
 
 ### Chat pane
 
-The center pane is a traditional chat interface, with an input form at the
+The centre pane is a traditional chat interface, with an input form at the
 bottom and the chat history above it.  Chat history is never saved to
 disk, and is erased after four hours (or whatever is specified in the
 `"max-history-age"` field of the group definition).
@@ -84,7 +84,7 @@ commands.
 
 ### Inviting users
 
-In order to generate an invitation link, choose the entry "Invite user" in
+In order to generate an invitation link, choose the entry *Invite user* in
 the group menu.  This generates a link of the form
 
     https://galene.example.org:8443/group/city-watch/?token=XXX
@@ -98,22 +98,21 @@ however, groups may be configured with the `"unrestricted-tokens"` option,
 which allows all users to generate tokens.
 
 Tokens can be created, modified, and expired using the `/invite`,
-`/reinvite` and `/revoke` commands.
+`/reinvite`, and `/revoke` commands.
 
 ### File transfer
 
 Galene includes a peer-to-peer, end-to-end encrypted file transfer protocol.
 In order to transfer a file, click on the receiver's entry in the user
-list and choose "Send file".
+list and choose *Send file*.
 
 ### Group moderation
 
-If a user has the *op* permission (short for *Operator*), then they have
+If a user has the *op* permission (short for *operator*), then they have
-access to a number of moderation tools.
+access to a number of moderation tools.  The contextual menu that opens
-
+when clicking on an entry in the user list is expanded with commands for
-For a moderator, the contextual menu that opens when clicking on an entry
+muting a user, sending them a warning, retrieving their IP address, or
-in the user list is expanded with commands for muting a user, sending them
+kicking them out from a group.
-a warning, retrieving their IP address, or kicking them out from a group.
 
 The group menu (opened by clicking on one's own entry in the user's list)
 is extended with options to lock or to unlock a group (a locked group is
@@ -124,7 +123,6 @@ All of the moderation commands are also available as command-line commands
 
 # Server administration
 
-
 ## The global configuration file
 
 The server may be configured in the JSON file `data/config.json`.  This
@@ -153,7 +151,7 @@ or, better, with a hashed password:
 }
 ```
 
-The file is initially set up using `galenectl initial-setup`, but may be
+The file is initially created using `galenectl initial-setup`, but may be
 manually edited at any time (there is no need to restart the server).  The
 fields are as follows:
 
@@ -165,7 +163,7 @@ fields are as follows:
    to modify group definitions; if unset or false, then only read-only
    access is allowed;
 
- - `allowOrigin` is an array that contains the list of HTTP origins that
+ - `allowOrigin` is an array containing the list of HTTP origins that
    are allowed to access the server;
 
  - `allowAdminOrigin` is like `allowOrigin`, but applies to the
@@ -181,7 +179,7 @@ fields are as follows:
 
 ## Group definitions
 
-Groups are described by JSON files in the `./groups/` directory.  These
+Groups are described by JSON files in the `groups/` directory.  These
 files are normally administered using the `galenectl` utility, but may
 also be edited manually (there is no need to restart the server).
 
@@ -204,11 +202,11 @@ galenectl create-group -group city-watch -unrestricted-tokens
 ```
 
 For more advanced configuration, `galenectl create-group` can be invoked
-with the `-json` flag, in which case it takes a JSON template on standard
+with the `-json` flag, in which case it takes a JSON template from standard
 input.  The syntax of a JSON template is just like that of a group
 definition file (see below), except that it must not contain the fields
 `users` and `wildcard-user`.  For example, in order to create a redirect
-(see the section "Group description reference" below):
+(see the section *Group description reference* below):
 
 ```sh
 echo '{"redirect": "https://galene.example.org:8443/group/city-watch/"}' | galenectl create-group -group amcw -json
@@ -236,7 +234,7 @@ galenectl delete-group -group amcw
 
 #### Creating, modifying, and deleting users
 
-A user entry is created with the `galenectl create-user` command :
+A user entry is created with the `galenectl create-user` command:
 
 ```sh
 galenectl create-user -group city-watch -user vimes -permissions op
@@ -244,7 +242,7 @@ galenectl create-user -group city-watch -user vimes -permissions op
 
 If the `-permissions` flag is not specified, it defaults to `present`,
 meaning that the user can participate in the chat and present videos to
-the group.  The other useful values are `message`, which allows a user
+the group.  Other useful values are `message`, which allows a user
 to participate in the chat only, and `observe`, which doesn't allow any
 active participation.
 
@@ -260,8 +258,8 @@ galenectl set-password -group city-watch -user vimes
 
 #### The fallback user
 
-It is sometimes useful to allow multiple users to log-in using the same
+It is sometimes useful to allow multiple users to log in using the same
-password.  This is achieved by defining the *wildcard* user:
+password.  This can be achieved by defining the *wildcard* user:
 
 ```sh
 galenectl create-user -group city-watch -wildcard
@@ -275,18 +273,18 @@ user's password is set to the password of type `wildcard`:
 galenectl set-password -group city-watch -wildcard -type wildcard
 ```
 
-See the section "Client authorisation" below for more information about
+See the section *Client authorisation* below for more information about
 password types.
 
 #### Automatic subgroups
 
-It is sometimes necessary to create large numbers of identical groups.
+It is sometimes necessary to create a large number of identical groups.
 For example, the author has been using Galene to supervise computer
 science practicals, where up to 40 students are working in groups of two.
 
-While it is possible to automate the creation of groups, by accessing
+While it is possible to automate the creation of groups by accessing
-Galene's API, by scripting calls to galenectl, or by directly generating
+Galene's API, by scripting calls to galenectl, or by generating files
-files under `groups/`, Galene provides a facility known as *automatic
+directly under `groups/`, Galene provides a facility called *automatic
 subgroups* that can be used to generate groups on demand.
 
 Automatic subgroups are enabled by setting the `"auto-subgroups"`
@@ -304,7 +302,7 @@ group's operator can view the list of populated subgroups with the command
 
 #### Managing tokens
 
-Tokens are normally managed using the `/invite`, `/reinvite` and `/expire`
+Tokens are normally managed using the `/invite`, `/reinvite`, and `/expire`
 commands in Galene's user interface, but they may also be managed using
 the `galenectl` utility's `create-token`, `revoke-token`, `delete-token`
 and `list-tokens` commands:
@@ -340,10 +338,10 @@ a file `groups/teaching/networking.json` defines a group called
 Every group definition file contains a single JSON dictionary.  All fields
 are optional.  The following fields are allowed:
 
- - `users`: is a dictionary that maps user names to user descriptions (see
+ - `users`: a dictionary that maps user names to user descriptions (see
    below);
 
- - `wildcard-user` is a user description that will be used for usernames
+ - `wildcard-user` a user description that will be used for usernames
    with no matching entry in the `users` dictionary;
 
  - `authKeys`, `authServer` and `authPortal`: see *Authorisation* below;
@@ -362,7 +360,7 @@ are optional.  The following fields are allowed:
  - `comment`: a human-readable string, ignored by the server;
 
  - `max-clients`: the maximum number of clients that may join the group at
-   a time;
+   one time;
 
  - `max-history-age`: the time, in seconds, during which chat history is
    kept (default 14400, i.e. 4 hours);
@@ -390,7 +388,7 @@ are optional.  The following fields are allowed:
  - `redirect`: if set, then attempts to join the group will be redirected
    to the given URL; most other fields are ignored in this case;
 
- - `codecs`: this is a list of codecs allowed in this group, see below for
+ - `codecs`: a list of codecs allowed in this group, see below for
    possible values.  The default is `["vp8", "opus"]`.
 
 A user definition is a dictionary with entries `password` and
@@ -400,14 +398,14 @@ hash-password` command.  The value of the `permissions` field can either
 be an array of individual permissions (not recommended), or one of the
 following strings:
 
- - `op`, a group operator, with all rights except administering the group;
+ - `op`: a group operator, with all rights except administering the group;
  - `present`, an ordinary user with the right to publish audio and video
    streams and send chat messages;
- - `message`, a user with the right to send chat messages;
+ - `message`: a user with the right to send chat messages;
- - `observe`, a user that receives media streams and chat messages, but
+ - `observe`: a user that receives media streams and chat messages, but
    is not allowed to send them;
- - `caption`, a user with the right to display captions (only);
+ - `caption`: a user with the right to display captions (only);
- - `admin`, a user with the right to administer the group (only).
+ - `admin`: a user with the right to administer the group (only).
 
 The value of the `codecs` field is an array of codecs allowed in the
 group.  Supported video codecs include:
@@ -429,14 +427,14 @@ anything except Opus.
 
 Galene implements three authorisation methods: a username/password
 authorisation scheme, a scheme using stateful tokens, and a mechanism
-based on cryptographic tokens.  The former two mechanism are intended to
+based on cryptographic tokens.  The former two mechanisms are intended to
 be used in standalone installations, while the cryptographic mechanism is
 designed to allow easy integration with an existing authorisation
 infrastructure (such as LDAP, OAuth2, or even Unix passwords).
 
 ### Password authorisation
 
-When password authorisation is used, authorised usernames and password are
+When password authorisation is used, authorised usernames and passwords are
 defined directly in the group configuration file, in the `users` and
 `wildcard-user` entries.  The `users` entry is a dictionary that maps user
 names to user descriptions; the `wildcard-user` is a user description
@@ -449,7 +447,7 @@ a dictionary describing a hashed password or a wildcard.  The
 `permissions` field should be one of `op`, `present`, `message` or
 `observe`.  (An array of Galene's internal permissions is also allowed,
 but this is not recommended, since internal permissions may vary from
-version to version).
+version to version.)
 
 For example, the entry
 
@@ -459,15 +457,15 @@ For example, the entry
 }
 ```
 
-specifies that user "vimes" may login as operator with password "sybil", while
+specifies that user "vimes" may log in as operator with password "sybil", while
 
 ```json
 {
     "wildcard-user": {"password": "1234", "permissions": "present"}
 }
-````
+```
 
-allows any username with password *1234*.  Finally,
+allows any username with the password *1234*.  Finally,
 
 ```json
 {
@@ -520,7 +518,7 @@ up without stopping the server.
 In many cases, it is useful to delegate authorisation decisions to a third
 party, such as an LDAP or OAuth2 client.  Galene implements delegation of
 authorisation decisions using cryptographic tokens generated by a third
-party known as an *authorisaton server*.  Two authorisation servers are
+party known as an *authorisation server*.  Two authorisation servers are
 available: an [LDAP client][2], and a [sample server written in Python][3].
 
 When an authorisation server is used, the `"authKeys"` entry of the group
@@ -553,7 +551,7 @@ authorisation portal.  An authorisation server is specified using the
 
 ```json
 {
-    "authServer": "https://auth.example.org",
+    "authServer": "https://auth.example.org"
 }
 ```
 
@@ -563,12 +561,11 @@ join the group using token authentication.  The password is never
 communicated to the server.
 
 Alternatively, the group file may specify an authorisation portal using
-the `"authPortal"` key
+the `"authPortal"` key.  If an authorisation portal is specified, then the
-
+default client will redirect initial client connections to the
-If an authorisation portal is specified, then the default client will
+authorisation portal.  The authorisation portal is expected to authorise
-redirect initial client connections to the authorisation portal.  The
+the client and then redirect it to Galene with the `username` and `token`
-authorisation portal is expected to authorise the client and then redirect
+query parameters set.
-it to Galene with the `username` and `token` query parameters set.
 
 [1]: <galene-install.md>
 [2]: <https://github.com/jech/galene-imap/>