Allow for Dockerfile to be named something else.

Add a check to make sure Dockerfile is in the build context
Add docs and a testcase
Make -f relative to current dir, not build context

Signed-off-by: Doug Davis <dug@us.ibm.com>

docs/sources/reference/commandline/cli.md

@@ -461,11 +461,12 @@ To kill the container, use `docker kill`.
 
     Build a new image from the source code at PATH
 
-      --force-rm=false     Always remove intermediate containers, even after unsuccessful builds
-      --no-cache=false     Do not use cache when building the image
-      -q, --quiet=false    Suppress the verbose output generated by the containers
-      --rm=true            Remove intermediate containers after a successful build
-      -t, --tag=""         Repository name (and optionally a tag) to be applied to the resulting image in case of success
+      -f, --file=""            Location of the Dockerfile to use. Default is 'Dockerfile' at the root of the build context
+      --force-rm=false         Always remove intermediate containers, even after unsuccessful builds
+      --no-cache=false         Do not use cache when building the image
+      -q, --quiet=false        Suppress the verbose output generated by the containers
+      --rm=true                Remove intermediate containers after a successful build
+      -t, --tag=""             Repository name (and optionally a tag) to be applied to the resulting image in case of success
 
 Use this command to build Docker images from a Dockerfile and a
 "context".
@@ -510,6 +511,13 @@ For example, the files `tempa`, `tempb` are ignored from the root directory.
 Currently there is no support for regular expressions. Formats
 like `[^temp*]` are ignored.
 
+By default the `docker build` command will look for a `Dockerfile` at the
+root of the build context. The `-f`, `--file`, option lets you specify
+the path to an alternative file to use instead.  This is useful
+in cases where the same set of files are used for multiple builds. The path
+must be to a file within the build context. If a relative path is specified
+then it must to be relative to the current directory.
+
 
 See also:
 
@@ -612,6 +620,28 @@ repository is used as Dockerfile. Note that you
 can specify an arbitrary Git repository by using the `git://` or `git@`
 schema.
 
+    $ sudo docker build -f Dockerfile.debug .
+
+This will use a file called `Dockerfile.debug` for the build
+instructions instead of `Dockerfile`.
+
+    $ sudo docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
+    $ sudo docker build -f dockerfiles/Dockerfile.prod  -t myapp_prod .
+
+The above commands will build the current build context (as specified by 
+the `.`) twice, once using a debug version of a `Dockerfile` and once using 
+a production version.
+
+    $ cd /home/me/myapp/some/dir/really/deep
+    $ sudo docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
+    $ sudo docker build -f ../../../../dockerfiles/debug /home/me/myapp
+
+These two `docker build` commands do the exact same thing. They both
+use the contents of the `debug` file instead of looking for a `Dockerfile` 
+and will use `/home/me/myapp` as the root of the build context. Note that 
+`debug` is in the directory structure of the build context, regardless of how 
+you refer to it on the command line.
+
 > **Note:** `docker build` will return a `no such file or directory` error
 > if the file or directory does not exist in the uploaded context. This may
 > happen if there is no context, or if you specify a file that is elsewhere