From 29b419eed5c37853e50d2f75b99904da230bc84e Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Mon, 26 Jun 2017 18:46:45 -0700
Subject: [PATCH] Some builder docs improvements

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 docs/reference/builder.md           | 16 ++++++++--------
 docs/reference/commandline/build.md | 12 ++++++------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/reference/builder.md b/docs/reference/builder.md
index 9ab4ba4df9..d6274407e6 100644
--- a/docs/reference/builder.md
+++ b/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
-location `PATH` or `URL`. The `PATH` is a directory on your local filesystem.
-The `URL` is a Git repository location.
+a `Dockerfile` and a *context*. The build's context is the set of files at a
+specified location `PATH` or `URL`. The `PATH` is a directory on your local
+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
-that uses the current directory as context:
+the `URL` includes the repository and its submodules. This example shows a
+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
-is provided, it will be relative to the path of the previous `WORKDIR`
-instruction. For example:
+The `WORKDIR` instruction can be used multiple times in a `Dockerfile`. If a
+relative path is provided, it will be relative to the path of the previous
+`WORKDIR` instruction. For example:
 
     WORKDIR /a
     WORKDIR b
diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md
index 9f587372c6..443ea015b2 100644
--- a/docs/reference/commandline/build.md
+++ 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 files located in the specified `PATH` or `URL`. The build process can refer
-to any of the files in the context. For example, your build can use an
-[*ADD*](../builder.md#add) instruction to reference a file in the
-context.
+The `docker build` command builds Docker images from a Dockerfile and a
+"context". A build's context is the set of files located in the specified
+`PATH` or `URL`. The build process can refer to any of the files in the
+context. For example, your build can use a [*COPY*](../builder.md#copy)
+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.