adapted documentation including note about docker port testing

README.adoc

 = wait-for-it
 
-`wait-for-it.sh` is a pure sh script that will wait on the availability of a host and TCP port.
+`wait-for-it.sh` is a *sh* script that will wait on the availability of a host and TCP port.
 It is useful for synchronizing the spin-up of interdependent services, such as linked docker containers.
-Since it is a pure sh script, it does not have any external dependencies.
+External dependencies are either `nc`, `python` or `bash`.
+This version is a fork of https://github.com/vishnubob/wait-for-it with improvements that it works with a *plain sh*.
 
 == Usage
 
@@ -21,6 +22,8 @@ wait-for-it.sh host:port [-s] [-t timeout] [-- command args]
 
 == Examples
 
+=== Basic usage
+
 For example, let's test to see if we can access port 80 on www.google.com, and if it is available, echo the message `google is up`.
 
 [source, sh]
@@ -42,20 +45,7 @@ wait-for-it.sh: www.google.com:80 is available after 0 seconds
 google is up
 ----
 
-The subcommand will be executed regardless if the service is up or not.
-If you wish to execute the subcommand only if the service is up, add the `--strict` argument.
-In this example, we will test port 81 on www.google.com which will fail:
-
-[source, sh]
-----
-$ ./wait-for-it.sh www.google.com:81 --timeout=1 --strict -- echo "google is up"
-wait-for-it.sh: waiting 1 seconds for www.google.com:81
-wait-for-it.sh: timeout occurred after waiting 1 seconds for www.google.com:81
-wait-for-it.sh: strict mode, refusing to execute subprocess
-----
-
-If you don't want to execute a subcommand, leave off the `--` argument.
-This way, you can test the exit condition of `wait-for-it.sh` in your own scripts, and determine how to proceed:
+You can test the exit condition of `wait-for-it.sh` in your own scripts, and determine how to proceed:
 
 [source, sh]
 ----
@@ -71,6 +61,37 @@ $ echo $?
 124
 ----
 
-== Community
+=== Subcommands
+
+A subcommand will be executed regardless of whether the service is up or not.
+If you wish to execute the subcommand only if the service is up, add the `--strict` argument.
+In this example, we will test port 81 on www.google.com which will fail:
 
-_Debian_: There is a https://tracker.debian.org/pkg/wait-for-it[Debian package].
+[source, sh]
+----
+$ ./wait-for-it.sh www.google.com:81 --timeout=1 --strict -- echo "google is up"
+wait-for-it.sh: waiting 1 seconds for www.google.com:81
+wait-for-it.sh: timeout occurred after waiting 1 seconds for www.google.com:81
+wait-for-it.sh: strict mode, refusing to execute subprocess
+----
+
+=== Docker
+
+[NOTE]
+====
+Take care when using this utility to test for a running service within a docker container. When Docker is starting up a container, the ports will become available ver early even if the backing service is not running already! To account for this behavior you need to do some sort of communication with the backend to ensure it is up and running. 
+====
+
+.Protocol level service test
+[source, sh]
+----
+$ ./wait-for-it.sh --host=localhost --port=51200 --strict --timeout=20 -- \
+    /usr/bin/timeout 40 sh -c 'while true; do \
+      printf "GET / HTTP/1.0\r\n\r\n" | nc localhost 51200 | grep -q "^HTTP.*200.*OK" && break; \
+      printf "."; sleep 1; \
+    done'
+
+wait-for-it.sh: waiting 20 seconds for localhost:51200
+wait-for-it.sh: localhost:51200 is available after 3 seconds
+...................
+----