Docs: Rewrite Bazel pages to clarify intended user PiperOrigin-RevId: 359812571
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html index ddb99fc..6bc3efc 100644 --- a/site/docs/build-ref.html +++ b/site/docs/build-ref.html
@@ -316,7 +316,7 @@ </p> <p>While it is common to use <code>/</code> in the name of a file - target, we recommend that you avoid the use of <code>/</code> in the + target, it is recommended that you avoid the use of <code>/</code> in the names of rules. Especially when the shorthand form of a label is used, it may confuse the reader. The label <code>//foo/bar/wiz</code> is always a shorthand @@ -436,8 +436,8 @@ <p> The previous section described packages, targets and labels, and the - build dependency graph abstractly. In this section, we'll look at - the concrete syntax used to define a package. + build dependency graph abstractly. This section describes the + concrete syntax used to define a package. </p> <p> @@ -608,7 +608,7 @@ <code>B</code> if <code>B</code> is needed by <code>A</code> at build or execution time. The <i>depends upon</i> relation induces a <a href="https://en.wikipedia.org/wiki/Directed_acyclic_graph">Directed - Acyclic Graph</a> (DAG) over targets, and we call this a + Acyclic Graph</a> (DAG) over targets, and it is called a <em>dependency graph</em>. A target's <em>direct</em> dependencies are those other targets @@ -646,7 +646,7 @@ For correct builds, the graph of actual dependencies <i>A</i> must be a subgraph of the graph of declared dependencies <i>D</i>. That is, every pair of directly-connected nodes <code>x --> y</code> - in <i>A</i> must also be directly connected in <i>D</i>. We say + in <i>A</i> must also be directly connected in <i>D</i>. It can be said that <i>D</i> is an <em>overapproximation</em> of <i>A</i>. </p> @@ -893,8 +893,8 @@ <p>A build target might need some data files to run correctly. These data files aren't source code: they don't affect how the target is built. For example, a unit test might compare a function's output - to the contents of a file. When we build the unit test, we - don't need the file; but we do need it when we run the test. The + to the contents of a file. When you build the unit test you + don't need the file, but you do need it when you run the test. The same applies to tools that are launched during execution. <p>The build system runs tests in an isolated directory where only files