Merge pull request #3024 from aanand/update-build-image-docs

Update docs about using build and image together

docs/compose-file.md

@@ -59,6 +59,14 @@ optionally [dockerfile](#dockerfile) and [args](#args).
       args:
         buildno: 1
 
+If you specify `image` as well as `build`, then Compose tags the built image
+with the tag specified in `image`:
+
+    build: ./dir
+    image: webapp
+
+This will result in an image tagged `webapp`, built from `./dir`.
+
 > **Note**: In the [version 1 file format](#version-1), `build` is different in
 > two ways:
 >
@@ -340,13 +348,22 @@ An entry with the ip address and hostname will be created in `/etc/hosts` inside
 
 ### image
 
-Tag or partial image ID. Can be local or remote - Compose will attempt to
-pull if it doesn't exist locally.
+Specify the image to start the container from. Can either be a repository/tag or
+a partial image ID.
 
-    image: ubuntu
-    image: orchardup/postgresql
+    image: redis
+    image: ubuntu:14.04
+    image: tutum/influxdb
+    image: example-registry.com:4000/postgresql
     image: a4bc65fd
 
+If the image does not exist, Compose attempts to pull it, unless you have also
+specified [build](#build), in which case it builds it using the specified
+options and tags it with the specified tag.
+
+> **Note**: In the [version 1 file format](#version-1), using `build` together
+> with `image` is not allowed. Attempting to do so results in an error.
+
 ### labels
 
 Add metadata to containers using [Docker labels](https://docs.docker.com/engine/userguide/labels-custom-metadata/). You can use either an array or a dictionary.