Normalize usage of "workspace", "workspace directory" and "build root" in

documentation. Replaces instances of "build root" with "workspace directory"
as appropriate.

Makes the following changes:

- /docs/build-ref.html: Adds definition of workspace
- /docs/external.md: Replaces "build root" terminology with "workspace"
- /docs/getting-started.md: Adds link to workspace definition
- /docs/bazel-user-manual.html: Adds link to workspace definition

--
MOS_MIGRATED_REVID=101885966

4 files changed, 40 insertions, 31 deletions

diff --git a/site/docs/bazel-user-manual.html b/site/docs/bazel-user-manual.html
index 28222992b5..b0359ab2d2 100644
--- a/site/docs/bazel-user-manual.html
+++ b/site/docs/bazel-user-manual.html
@@ -143,7 +143,7 @@
 <p>
   To run Bazel, go to
 
-  your base workspace directory
+  your base <a href="/docs/build-ref.html#workspaces">workspace</a> directory
   or any of its subdirectories and type <code>bazel</code>.
 </p>
 
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html
index 1d849126f9..36c687c5b5 100644
--- a/site/docs/build-ref.html
+++ b/site/docs/build-ref.html
@@ -139,7 +139,8 @@
 
 <ul>
   <li><a href="#intro">Introduction</a></li>
-  <li><a href="#packages_targets">Packages and Targets</a>
+
+  <li><a href="#packages_targets">Workspace, Packages and Targets</a>
     <ul>
       <li><a href="#packages">Packages</a></li>
       <li><a href="#targets">Targets</a></li>
@@ -168,26 +169,32 @@
 
 <h2 id="intro">Introduction</h2>
 
-<p>Bazel can build and test software from source
-  code stored in any source tree that is organized as described
-  in this document. This source tree descends from a single top-level
-  directory and contains a nested hierarchy of packages, each of which contain
-  source files and metadata that specifies what software targets, for
-  example, compiled executables or libraries, can be built from the source.
+<p>Bazel builds software from source code organized in a directory called
+   a workspace. Source files in the workspace are organized in a nested
+   hierarchy of packages, where each package is a directory that contains a set
+   of related source files and a BUILD file. The BUILD file specifies what
+   software outputs can be built from the source.
 </p>
-<h2 id="packages_targets">Packages and Targets</h2>
+<h2 id="packages_targets">Workspace, Packages and Targets</h2>
+<h3 id="workspaces">Workspace</h3>
 
+<p>A <em>workspace</em> is a directory on your filesystem that contains the
+   source files for the software you want to build, as well as symbolic links
+   to directories that contain the build outputs. Each workspace directory has
+   a text file named <code>WORKSPACE</code> which may be empty,  or may contain
+   references to <a href="/docs/external.html">external dependencies</a>
+   required to build the outputs.
+</p>
 <h3 id="packages">Packages</h3>
-
 <p>
-  The primary unit of code organization in the source tree is
+  The primary unit of code organization a workspace is
   the <i>package</i>.  A package is collection of related files and a
   specification of the dependencies among them.
 </p>
 <p>
   A package is defined as a directory containing a file
   named <code>BUILD</code>, residing beneath the top-level directory in the
-  source tree.  A package includes all files in its directory, plus all
+  workspace.  A package includes all files in its directory, plus all
   subdirectories beneath it, except those which themselves contain a BUILD
   file.
 </p>
diff --git a/site/docs/external.md b/site/docs/external.md
index e11f49fdd9..34ffe1b9a2 100644
--- a/site/docs/external.md
+++ b/site/docs/external.md
@@ -5,15 +5,16 @@ layout: documentation
 # Working with external dependencies
 
 Bazel is designed to have absolutely everything needed for a build, from source
-code to libraries to compilers, under one directory (the build root). This is
-impractical for some version control systems and goes against how many existing
-projects are structured. Thus, Bazel has a system for pulling in dependencies
-from outside of the build root.
-
-External dependencies can be specified in a `WORKSPACE` file in the build root.
-This `WORKSPACE` file uses the same Python-like syntax of BUILD files, but
-allows a different set of rules. See the full list of rules that are allowed in
-the [Workspace](/docs/build-encyclopedia.html) list of rules in the Build
+code to libraries to compilers, under one directory (the workspace directory).
+This is impractical for some version control systems and goes against how many
+existing projects are structured. Thus, Bazel has a system for pulling in
+dependencies from outside of the workspace.
+
+External dependencies can be specified in a `WORKSPACE` file in the
+[workspace directory](/docs/build-ref.html#workspaces). This `WORKSPACE` file
+uses the same Python-like syntax of BUILD files, but allows a different set of
+rules. See the full list of rules that are allowed in the
+[Workspace](/docs/build-encyclopedia.html#workspace) list of rules in the Build
 Encyclopedia.
 
 ## Fetching dependencies
@@ -25,7 +26,7 @@ you would like to disable this behavior or prefetch dependencies, use
 <a name="transitive-dependencies"></a>
 ## Transitive dependencies
 
-Bazel only reads dependencies listed in your build root's `WORKSPACE` file. This
+Bazel only reads dependencies listed in your `WORKSPACE` file. This
 means that if your project (`A`) depends on another project (`B`) which list a
 dependency on project `C` in its `WORKSPACE` file, you'll have to add both `B`
 and `C` to your project's `WORKSPACE` file. This can balloon the `WORKSPACE`
diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md
index 9615dc17b6..479a5332bf 100644
--- a/site/docs/getting-started.md
+++ b/site/docs/getting-started.md
@@ -23,12 +23,13 @@ _**Note:** Bazel may support a binary installation at a later time._
 
 ## Using a workspace
 
-A *workspace* is a directory on your filesystem that contains source code for
-the software you want to build, as well symbolic links to directories that
-contain the build outputs (for example, `bazel-bin` and `bazel-out`). The
-location of the workspace directory is not significant, but it must contain an
-empty file called `WORKSPACE` in the top-level directory. This file marks the
-directory as the workspace root.
+A [workspace](/docs/build-ref.html#workspaces) is a directory on your filesystem
+that contains source code for the software you want to build, as well symbolic
+links to directories that contain the build outputs (for example, `bazel-bin`
+and `bazel-out`). The location of the workspace directory is not significant,
+but it must contain a file called `WORKSPACE` in the top-level directory. The
+`WORKSPACE` file may be an empty file, or it may contain references to
+[external dependencies](/docs/external.html) required to build the outputs.
 
 One workspace can be shared among multiple projects if desired.  To get
 started, we'll focus on a simple example with one project.
@@ -39,8 +40,8 @@ Suppose that you have an existing project in a directory, say,
 
 ## Sanity Check: Building an Example
 
-To make sure everything is set up correctly in your build root, build one of the
-examples from the `examples/` directory.
+To make sure that you have installed Bazel correctly, build one of the examples
+from the `examples/` directory.
 
 {% highlight bash %}
 $ cd ~/gitroot/my-project
@@ -104,7 +105,7 @@ If you have no actual Java project you're using, you can use the following
 commands to make a fake project for this example:
 
 {% highlight bash %}
-$ # If you're not already there, move to your build root directory.
+$ # If you're not already there, move to your workspace directory.
 $ cd ~/gitroot/base_workspace
 $ mkdir -p my-project/java/com/example
 $ cat > my-project/java/com/example/ProjectRunner.java <<EOF