docs/user_guide.md: document how to invoke embedded scripts from custom ones.

Also improve README.md.

README.md

@@ -12,7 +12,7 @@ ready-to-run images by injecting source code into a Docker container and letting
 
 For a deep dive on S2I you can view [this presentation](https://www.youtube.com/watch?v=flI6zx9wH6M).
 
-Want to try it right now?  Download the [latest release](https://github.com/openshift/source-to-image/releases/tag/v1.1.0) and run:
+Want to try it right now?  Download the [latest release](https://github.com/openshift/source-to-image/releases/latest) and run:
 
 	$ s2i build git://github.com/openshift/django-ex centos/python-35-centos7 hello-python
 	$ docker run -p 8080:8080 hello-python
@@ -40,9 +40,6 @@ For example, to create a reproducible build pipeline for Tomcat (the popular Jav
 
 By placing our build logic inside of images, and by combining the images into multiple steps, we can keep our runtime environment close to our build environment (same JDK, same Tomcat JARs) without requiring build tools to be deployed to production.
 
-Learn more about [building your own images](#getting-started) and [how to use a non-builder image for the final application image](https://github.com/openshift/source-to-image/blob/master/docs/runtime_image.md).
-
-
 ## Goals
 
 ### Reproducibility
@@ -71,7 +68,7 @@ image:
 Additionally for the best user experience and optimized `s2i` operation we suggest images
 to have `/bin/sh` and `tar` commands available.
 
-See a practical tutorial on how to create a builder image [here](examples/README.md) and read [this](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md) for a detailed description of the requirements and scripts along with examples of builder images.
+See [a practical tutorial on how to create a builder image](examples/README.md) and read [a detailed description of the requirements and scripts along with examples of builder images](docs/builder_image.md).
 
 ## Build workflow
 
@@ -240,7 +237,10 @@ $ s2i build git://github.com/bparees/openshift-jee-sample openshift/wildfly-100-
 $ docker run --rm -i -p :8080 -t test-jee-app
 ```
 
-Interested in more advanced `s2i` usage? See [here](https://github.com/openshift/source-to-image/blob/master/docs/cli.md)
-for detailed descriptions of the different CLI commands with examples.
+Want to know more? Read the following resources:
 
-Running into some issues and need some advice debugging?  Peruse [here](https://github.com/openshift/source-to-image/blob/master/docs/debugging-s2i.md) for some tips.
+* [Descriptions and examples of the S2I commands](docs/cli.md)
+* [Instructions for using builder images](docs/user_guide.md)
+* [Guidance for S2I builder image creators](docs/builder_image.md)
+* [Using a non-builder image for the base of the application image](docs/runtime_image.md)
+* [Troubleshooting and debugging S2I problems](docs/debugging-s2i.md)

docs/user_guide.md

@@ -0,0 +1,46 @@
+# Using S2I images
+
+S2I builder images normally include `assemble` and `run` scripts, but the default behavior of those scripts may not be suitable for all users. This document will cover a few approaches for customizing the behavior of an S2I builder that includes default scripts.
+
+## Invoking scripts embedded in an image
+
+Typically builder images provide their own version of the [S2I scripts](builder_image.md#s2i-scripts) that cover the most common use-cases. If these scripts don't fulfill your needs, S2I provides a way of overriding them by adding custom ones in the `.s2i/bin` directory. However, by doing this you are completely replacing the standard scripts. In some cases this is acceptable but in other scenarios you may prefer to execute a few commands before (or after) the scripts while retaining the logic of the script provided in the image. In this case it is possible to create a wrapper script that will execute custom logic and delegate further work to the default script in the image.
+
+To determine the location of the scripts inside of the builder image, we need to look at at the value of `io.openshift.s2i.scripts-url` label. We can use `docker inspect` for that:
+
+```console
+$ docker inspect --format='{{ index .Config.Labels "io.openshift.s2i.scripts-url" }}' openshift/wildfly-100-centos7
+image:///usr/libexec/s2i
+```
+
+Here we are inspected the `openshift/wildfly-100-centos7` builder image and found out that the scripts are in the `/usr/libexec/s2i` directory.
+
+With this knowledge we can invoke any of these scripts from our own by wrapping its invocation.
+
+Example of `.s2i/bin/assemble` script:
+```bash
+#!/bin/bash
+echo "Before assembling"
+
+/usr/libexec/s2i/assemble
+rc=$?
+
+if [ $rc -eq 0 ]; then
+    echo "After successful assembling"
+else
+    echo "After failed assembling"
+fi
+
+exit $rc
+```
+
+The example shows a custom `assemble` script that prints the message, executes standard `assemble` script from the image and prints another message depending on the exit code of the `assemble` script.
+
+Wrapping the `run` script is a bit tricky because we have to use `exec` for invoking it (see chapter ["Always `exec` in Wrapper Scripts" in the Guidance for Docker Image Authors](http://www.projectatomic.io/docs/docker-image-author-guidance/)). As a consequence, it is impossible to have a post-run step because the code after `exec /usr/libexec/s2i/run` never gets executed.
+
+Example of `.s2i/bin/run` script:
+```bash
+#!/bin/bash
+echo "Before running application"
+exec /usr/libexec/s2i/run
+```