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

1 files changed, 18 insertions, 11 deletions

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>