Merge pull request #244 from thaJeztah/tiny-builder-docs-improvements

Some builder docs improvements

docs/reference/builder.md

@@ -30,13 +30,13 @@ Practices](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-pr
 ## Usage
 
 The [`docker build`](commandline/build.md) command builds an image from
-a `Dockerfile` and a *context*. The build's context is the files at a specified
+a `Dockerfile` and a *context*. The build's context is the set of files at a
-location `PATH` or `URL`. The `PATH` is a directory on your local filesystem.
+specified location `PATH` or `URL`. The `PATH` is a directory on your local
-The `URL` is a Git repository location.
+filesystem. The `URL` is a Git repository location.
 
 A context is processed recursively. So, a `PATH` includes any subdirectories and
-the `URL` includes the repository and its submodules. A simple build command
+the `URL` includes the repository and its submodules. This example shows a
-that uses the current directory as context:
+build command that uses the current directory as context:
 
     $ docker build .
     Sending build context to Docker daemon  6.51 MB
@@ -1328,9 +1328,9 @@ The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`,
 If the `WORKDIR` doesn't exist, it will be created even if it's not used in any
 subsequent `Dockerfile` instruction.
 
-It can be used multiple times in the one `Dockerfile`. If a relative path
+The `WORKDIR` instruction can be used multiple times in a `Dockerfile`. If a
-is provided, it will be relative to the path of the previous `WORKDIR`
+relative path is provided, it will be relative to the path of the previous
-instruction. For example:
+`WORKDIR` instruction. For example:
 
     WORKDIR /a
     WORKDIR b

docs/reference/commandline/build.md

@@ -63,11 +63,11 @@ Options:
 
 ## Description
 
-Builds Docker images from a Dockerfile and a "context". A build's context is
+The `docker build` command builds Docker images from a Dockerfile and a
-the files located in the specified `PATH` or `URL`. The build process can refer
+"context". A build's context is the set of files located in the specified
-to any of the files in the context. For example, your build can use an
+`PATH` or `URL`. The build process can refer to any of the files in the
-[*ADD*](../builder.md#add) instruction to reference a file in the
+context. For example, your build can use a [*COPY*](../builder.md#copy)
-context.
+instruction to reference a file in the context.
 
 The `URL` parameter can refer to three kinds of resources: Git repositories,
 pre-packaged tarball contexts and plain text files.
@@ -88,7 +88,7 @@ user credentials, VPN's, and so forth.
 
 Git URLs accept context configuration in their fragment section, separated by a
 colon `:`.  The first part represents the reference that Git will check out,
-this can be either a branch, a tag, or a remote reference. The second part
+and can be either a branch, a tag, or a remote reference. The second part
 represents a subdirectory inside the repository that will be used as a build
 context.