1 files changed, 30 insertions, 16 deletions

diff --git a/tools/docker_rbclient/README b/tools/docker_rbclient/README
index 48026f2140..4073e069af 100644
--- a/tools/docker_rbclient/README
+++ b/tools/docker_rbclient/README
@@ -1,35 +1,49 @@
-This directory builds a Docker container image for a rockbox build
+Docker build client
+===================
+
+This directory builds a Docker container image for a Rockbox build
 client with all toolchains except android.
 
 There is a pre-built client available as built1n/rbclient on Docker
 Hub if you would like to avoid having to build all the toolchains. See
-the Docker documentation on how to pull and run it.
+below for how to pull and run it.
+
+Building from scratch
+=====================
 
-To build from scratch:
+1. Make sure you have Docker installed and running (i.e. `systemctl
+start docker').
 
-1. Make sure you have Docker installed and running.
+2. Build the image:
 
-2. Run:
+    docker build . -t myclient
 
-  docker build . -t myclient
+  This will build the image and tag it as `myclient.' The build process
+  can take several hours, as it downloads and compiles every Rockbox
+  toolchain. Fortunately, Docker will cache intermediate images, saving
+  you work if you must rebuild.
 
-  This will build the image and tag it as `myclient.'
+3. Run your image:
 
-3. To run your client:
+    docker run -e USER=your username -e PASS=anything -e NAME=clientname \
+               myclient
 
-  docker run -e USER=your username -e PASS=anything -e NAME=clientname \
-             myclient
+  This will spin up a build image container in the background.
 
   You can also run a bash shell interactively by issuing:
 
-  docker run -it myclient bash
+    docker run -it myclient bash
 
-  This will drop you into a fully-equiped rockbox development
+  This will drop you into a fully-equipped Rockbox development
   environment.
 
-It is also possible to pull straight from Docker Hub. Run:
+Prebuilt image
+==============
+
+Run:
 
-  docker pull built1n/rbclient
+    docker pull built1n/rbclient
 
-Then you can use all the commands above, with `myclient' replaced with
-`built1n/rbclient'.
+This will download a pre-built image from Docker Hub (fairly large,
+will take some time). You can then use all the commands above, with
+`myclient' replaced with `built1n/rbclient'.