Cleanup the README file

1 files changed, 44 insertions, 27 deletions

diff --git a/README.md b/README.md
index d23baaf5..a99f8510 100644
--- a/README.md
+++ b/README.md
@@ -4,41 +4,54 @@
 
 [![coverage report](https://gitlab.com/gitlab-org/gitlab-pages/badges/master/coverage.svg)](https://gitlab.com/gitlab-org/gitlab-pages/commits/master)
 
-This is simple HTTP server written in Go made to serve GitLab Pages with CNAMEs and SNI using HTTP/HTTP2.
-The minimum supported Go version is 1.8.
+This is a simple HTTP server written in Go, made to serve GitLab Pages with
+CNAMEs and SNI using HTTP/HTTP2. The minimum supported Go version is 1.8.
 
-This is made to work in small-to-medium scale environments.
-In large environment it can be time consuming to list all directories, and CNAMEs.
+This is made to work in small to medium-scale environments. Start-up time scales
+with the number of projects being served, so the daemon is currently unsuitable
+for very large-scale environments.
 
 ### How it generates routes
 
-1. It reads the `pages-root` directory to list all groups
-2. It looks for `config.json` file in `pages-root/group/project` directory, reads them and creates mapping for custom domains and certificates.
-3. It generates virtual-host from these data.
-4. Periodically (every second) it checks the `pages-root/.update` file and reads its content to verify if there was update.
+1. It reads the `pages-root` directory to list all groups.
+2. It looks for `config.json` files in `pages-root/group/project` directories,
+   reads them and creates mapping for custom domains and certificates.
+3. It generates virtual hosts from these data.
+4. Periodically (every second) it checks the `pages-root/.update` file and reads
+   its content to verify if there was an update.
 
-To force route refresh, reload of configs fill the `pages-root/.update` with random content.
-The reload will be done asynchronously, and it will not interrupt the current requests.
+To reload the configuration, fill the `pages-root/.update` file with random
+content. The reload will be done asynchronously, and it will not interrupt the
+current requests.
 
 ### How it serves content
 
-1. When client initiates the TLS connection, the GitLab-Pages daemon looks in hash map for virtual hosts and tries to use loaded from `config.json` certificate.
+1. When client initiates the TLS connection, the GitLab-Pages daemon looks in
+  the generated configuration for virtual hosts. If present, it uses the TLS
+  key and certificate in `config.json`, otherwise it falls back to the global
+  configuration.
 
-2. When client asks HTTP server the GitLab-Pages daemon looks in hash map for registered virtual hosts.
+2. When client connects to a HTTP port the GitLab-Pages daemon looks in the
+   generated configuration for a matching virtual host.
 
-3. The URL.Path is split into `/<project>/<subpath>` and we daemon tries to load: `pages-root/group/project/public/subpath`.
+3. The URL.Path is split into `/<project>/<subpath>` and the daemon tries to
+   load: `pages-root/group/project/public/subpath`.
 
-4. If file was not found it will try to load `pages-root/group/<host>/public/<URL.Path>`.
+4. If the file is not found, it will try to load `pages-root/group/<host>/public/<URL.Path>`.
 
-5. If requested path is directory, the `index.html` will be served.
+5. If requested path is a directory, the `index.html` will be served.
+
+6. If `.../path.gz` exists, it will be served instead of the main file, with
+   a `Content-Encoding: gzip` header. This allows compressed versions of the
+   files to be precalculated, saving CPU time and network bandwidth.
 
 ### How it should be run?
 
-Ideally the GitLab Pages should run without load balancer.
+Ideally the GitLab Pages should run without any load balancer in front of it.
 
-If load balancer is required, the HTTP can be served in HTTP mode.
-For HTTPS traffic load balancer should be run in TCP-mode.
-If load balancer is run in SSL-offloading mode the custom TLS certificate will not work.
+If a load balancer is required, the HTTP can be served in HTTP mode. For HTTPS
+traffic, the load balancer should be run in TCP mode. If the load balancer is
+run in SSL-offloading mode, custom TLS certificates will not work.
 
 ### How to run it
 
@@ -57,10 +70,12 @@ To enter this mode, run `gitlab-pages` as the root user and pass it the
 `-daemon-uid` and `-daemon-gid` arguments to specify the user you want it to run
 as.
 
-The daemon start listening on ports as root, reads certificates as root and re-executes itself as specified user.
-When re-executing it copies it's own binary to `pages-root` and changes root to that directory.
+The daemon starts listening on ports and reads certificates as root, then
+re-executes itself as the specified user. When re-executing it copies its own
+binary to `pages-root` and changes root to that directory.
 
-This make it possible to listen on privileged ports and makes it harded the process to read files outside of `pages-root`.
+This make it possible to listen on privileged ports and makes it harder for the
+process to read files outside of `pages-root`.
 
 Example:
 ```
@@ -70,7 +85,8 @@ $ sudo ./gitlab-pages -listen-http ":80" -pages-root path/to/gitlab/shared/pages
 
 ### Listen on multiple ports
 
-Each of the `listen-http`, `listen-https` and `listen-proxy` arguments can be provided multiple times. Gitlab Pages will accept connections to them all.
+Each of the `listen-http`, `listen-https` and `listen-proxy` arguments can be
+provided multiple times. Gitlab Pages will accept connections to them all.
 
 Example:
 ```
@@ -78,13 +94,14 @@ $ make
 $ ./gitlab-pages -listen-http "10.0.0.1:8080" -listen-https "[fd00::1]:8080" -pages-root path/to/gitlab/shared/pages -pages-domain example.com
 ```
 
-This is most useful in dual-stack environments (IPv4+IPv6) where both Gitlab Pages and another HTTP server have to co-exist on the same server.
+This is most useful in dual-stack environments (IPv4+IPv6) where both Gitlab
+Pages and another HTTP server have to co-exist on the same server.
 
 ### Enable Prometheus Metrics
 
-For monitoring purposes, one could pass the `-metrics-address` flag when
-starting. This will expose general metrics about the Go runtime and pages
-application for [Prometheus](https://prometheus.io/) to scrape.
+For monitoring purposes, you can pass the `-metrics-address` flag when starting.
+This will expose general metrics about the Go runtime and pages application for
+[Prometheus](https://prometheus.io/) to scrape.
 
 Example:
 ```