Polish documentation.

--
MOS_MIGRATED_REVID=88821025

README.md

@@ -2,7 +2,7 @@
 
 *{Fast, Correct} - Choose two*
 
-Bazel is an build tool that builds code quickly and reliably.
+Bazel is a build tool that builds code quickly and reliably.
 It executes as few build steps as possible by tracking dependencies and outputs,
 controls the build environment to keep builds hermetic, and uses its
 knowledge of dependencies to parallelize builds.
@@ -13,9 +13,9 @@ knowledge of dependencies to parallelize builds.
 
   * How to [install Bazel](docs/install.md)
   * How to [get started using Bazel](docs/getting-started.md)
-  * How to [use the query command](docs/bazel-query-v2.html)
-  * How to [extend Bazel](docs/skylark/index.md)
   * The rule reference documentation is in the [build encyclopedia](docs/build-encyclopedia.html).
+  * How to [use the query command](docs/bazel-query.html)
+  * How to [extend Bazel](docs/skylark/index.md)
   * TODO(bazel-team): link to the user-manual
   * TODO(bazel-team): link to the test encyclopedia?
 

docs/FAQ.md

@@ -13,8 +13,9 @@ What is special about Bazel?
 Bazel was designed to fit the way software is developed at Google. It
 has the following features:
 
-* Multi-language support: Bazel supports Java and C++ out of the box,
-  and can be extended to support arbitrary programming languages.
+* Multi-language support: Bazel supports Java, Objective-C and C++ out
+  of the box, and can be extended to support arbitrary programming
+  languages.
 
 * High-level build language: Projects are described in the BUILD
   language, a concise text format that describes a project as sets of
@@ -106,7 +107,7 @@ that this is fast enough for most of our users.
 How does the Google development process work?
 ----------------------------------------------
 
-For our server code, we use the following development workflow:
+For our server code base, we use the following development workflow:
 
 * All of our server code base is in a single, gigantic version control
   system.
@@ -119,7 +120,7 @@ For our server code, we use the following development workflow:
 * Branching is primarily used for managing releases, so everybody
   develops their software at head.
 
-Bazel is a cornerstones of this philosophy: since Bazel requires all
+Bazel is a cornerstone of this philosophy: since Bazel requires all
 dependencies to be fully specified, we can predict which programs and
 tests are affected by a change, and vet them before submission.
 
@@ -185,11 +186,11 @@ straightforward, provided a JDK is available for the platform.
 What about Windows?
 -------------------
 
-We have experimented with a Windows port using MinGW/MSYS (see
-README.windows), but have no plans to invest in this port right
-now. Due to its Unix heritage, porting Bazel is significant work. For
-example, Bazel uses symlinks extensively, which has varying levels of
-support across Windows versions.
+We have experimented with a Windows port
+[using MinGW/MSYS](windows.md), but have no plans to invest in this
+port right now. Due to its Unix heritage, porting Bazel is significant
+work. For example, Bazel uses symlinks extensively, which has varying
+levels of support across Windows versions.
 
 
 What should I not use Bazel for?
@@ -220,19 +221,8 @@ versions multiple times every month.
 
 In short, except for features marked as experimental, at any point in
 time, Bazel should Just Work. Changes to non-experimental rules will
-be backward compatible.
-
-You can recognize the different experimental features as follows:
-
-* Options: Experimental features start with --experimental_.
-
-* Rules: Experimental rules are undocumented in the
-  build encyclopedia. TODO(bazel-team): add link.
-
-* Attributes: Experimental rule attributes are undocumented in the
-  build encyclopedia. TODO(bazel-team): add link.
-
-* TODO(bazel-team): document skylark status more precisely.
+be backward compatible. A more detailed list of feature support
+statuses can be found in our [support document](support.md).
 
 
 How stable is Bazel as a binary?
@@ -247,7 +237,7 @@ How can I start using Bazel?
 
 See our [getting started doc](getting-started.md)
 
-TODO(bazel-team): more doc links
+TODO(bazel-team): link to an index of all our docs.
 
 
 Why do I need to have a tools/ directory in my source tree?
@@ -265,11 +255,11 @@ do this in a directory called "tools".
 Bazel allows tools such as the JDK to live outside your workspace, but
 the configuration data for this (where is the JDK, where is the C++
 compiler?) still needs to be somewhere, and that place is also the
-tools/ directory.
+`tools/` directory.
 
-Bazel comes with a base_workspace/ directory, containing a minimal set
+Bazel comes with a `base_workspace/` directory, containing a minimal set
 of configuration files, suitable for running toolchains from standard
-system directories, e.g., /usr/bin/.
+system directories, e.g., `/usr/bin/`.
 
 
 Doesn't Docker solve the reproducibility problems?
@@ -284,9 +274,10 @@ It does not address reproducibility with regard to changes in the
 source code.  Running Make with an imperfectly written Makefile inside a
 Docker container can still yield unpredictable results.
 
-Inside Google, we check in tools for reproducibility.  In this way, we
-can vet changes to tools ("upgrade GCC to 4.6.1") with the same
-mechanism as changes to base libraries ("fix bounds check in OpenSSL").
+Inside Google, we check tools into source control for reproducibility.
+In this way, we can vet changes to tools ("upgrade GCC to 4.6.1") with
+the same mechanism as changes to base libraries ("fix bounds check in
+OpenSSL").
 
 
 Will Bazel make my builds reproducible automatically?
@@ -311,7 +302,7 @@ will need to take some extra care:
     traversal is randomized in many programming languages.
 
 TODO(bazel-team): maybe this should be part of the skylark docs
-instead.
+instead, or the genrule docs?
 
 
 Do you have binary releases?
@@ -357,9 +348,11 @@ files for python:
   https://github.com/google/bazel/blob/master/base_workspace/tools/build_rules/py_rules.bzl
   https://github.com/google/bazel/tree/master/base_workspace/examples/py
 
-Our internal Python rules support internal use-cases which rely heavily
-on native extensions, and its supporting infrastructure is specific to
-us, so we have no plans to open-source it.
+We are working on opening up a subset of our internal Python rules, so
+they can be used as helper scripts as part of a build.
+
+We currently have no plans to provide packaging up of self-contained
+Python binaries.
 
 
 
@@ -407,7 +400,8 @@ We are reachable at [email protected].
 Where do I report bugs?
 -----------------------
 
-Send us e-mail at [email protected].
+Send e-mail to [email protected], or file a bug at
+[on github](https://github.com/google/bazel/issues).
 
 
 

docs/getting-started.md

@@ -69,7 +69,7 @@ Writing Your Own Build Rules
 
 Now you can start adding your own build rules. This example assumes that
 _my-project/_ is a Java project.  See the
-[build encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html)
+[build encyclopedia](build-encyclopedia.html)
 for advice on writing rules for other languages.
 
 Note that when we ran "bazel build" above, the third argument started with a
@@ -101,7 +101,7 @@ Python, but each build rule looks like a Python function call and you can use
 "hello-world"). `srcs` lists the Java source files Bazel should
 compile into a Java binary.  `glob(["**/*.java"])` is a handy
 shorthand for "recursively include every file that ends with .java" (see the
-[user manual](https://github.com/google/bazel/blob/master/docs/historical/bazel-user-manual.html)
+[user manual](bazel-user-manual.html)
 for more information about globbing). Replace `com.example.ProjectRunner` with
 the class that contains the main method.
 
@@ -271,7 +271,7 @@ INFO: Running command line: bazel-bin/my-project/java/com/example/cmdline/runner
 Hi!
 ```
 
-See the [build encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html) for more visibility options.
+See the [build encyclopedia](build-encyclopedia.html) for more visibility options.
 
 Deploying
 ---------
@@ -307,9 +307,9 @@ Next Steps
 ----------
 
 You can now create your own targets and compose them.  See the [build
-encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html)
+encyclopedia](build-encyclopedia.html)
 and Bazel
-[user manual](https://github.com/google/bazel/blob/master/docs/historical/bazel-user-manual.html)
+[user manual](bazel-user-manual.html)
 for more information.
 [Let us know](https://groups.google.com/forum/#!forum/bazel-discuss)
 if you have any questions!

docs/install.md

@@ -39,9 +39,10 @@ To build Bazel on Ubuntu:
 
 Using Bazel on Mac OS X requires:
 
-* Xcode and Xcode command line tools
-* MacPorts or Homebrew for installing required packages
-* A JDK 8 installed
+* The Xcode command line tools. Xcode can be downloaded from
+  [Apbple's developer site](https://developer.apple.com/xcode/downloads/).
+* MacPorts or Homebrew for installing required packages.
+* An installation of JDK 8.
 
 To build Bazel on Mac OS X:
 
@@ -59,17 +60,25 @@ To build Bazel on Mac OS X:
         $ cd bazel
         $ ./compile.sh
 
-## Running Bazel
+3. Run it
+
+        $ ./output/bazel help
 
-The Bazel executable is located at `<bazel_home>/output/bazel`.
 
-You must run Bazel from within a _workspace directory_. Bazel provides a default
-workspace directory with sample `BUILD` files and source code in
-`<bazel_home>/base_workspace`. The default workspace contains files and
-directories that must be present in order for Bazel to work. If you want to
-build from source outside the default workspace directory, copy the entire
-`base_workspace` directory to the new location before adding your `BUILD` and
-source files.
+## Running Bazel
+
+The Bazel executable is located at `output/bazel`, under the source
+tree root.
+
+You must run Bazel from within source code tree, which is properly
+configured for use with Bazel. We call such a tree a _workspace
+directory_. Bazel provides a default workspace directory with sample
+`BUILD` files and source code in `base_workspace`. The default
+workspace contains files and directories that must be present in order
+for Bazel to work. If you want to build from source outside the
+default workspace directory, copy the entire `base_workspace`
+directory to the new location before adding your `BUILD` and source
+files.
 
 Build a sample Java application:
 

docs/roadmap.md

@@ -46,9 +46,8 @@ Alpha users will need to build Bazel from source; we will not provide binary
 releases until the beta. We will accept code contributions, but may need to
 reject or defer code contributions related to beta features still under
 development. Some features will be fully supported
-henceforward, others are still experimental or partially supported; see
-bazel/docs/governance.md for details.
-
+henceforward, others are still experimental or partially supported;
+see our [feature support document](support.md) for details.
 
 The following features/capabilities will be available in the alpha:
 

docs/support.md

@@ -1,15 +1,18 @@
 # Support Policy
 
-We generally avoid making incompatible changes. At Google, we run all of the tests in the entire
-depot before every release and check that there are no regressions. It is much more difficult to do
-that outside of Google, because there is no single source repository that contains everything.
+We generally avoid making backward-incompatible changes. At Google, we
+run all of the tests in the entire depot before every release and
+check that there are no regressions. It is much more difficult to do
+that outside of Google, because there is no single source repository
+that contains everything.
 
 All undocumented features (attributes, rules, "Make" variables, and flags) are subject to change at
 any time without prior notice. Features that are documented but marked *experimental* are also
 subject to change at any time without prior notice. The Skylark macro and rules language (anything
 you write in a `.bzl` file) is still subject to change.
 
-Bugs can be reported in the [GitHub bugtracker](https://github.com/google/bazel/issues). We will
+Bugs can be reported in the
+[GitHub bugtracker](https://github.com/google/bazel/issues). We will
 make an effort to triage all reported issues within 2 business days; we will measure our triaging
 process and regularly report numbers.
 

third_party/README.md

@@ -1,3 +1,8 @@
+This file lists license and version information of all code we did not
+author, but ship together with the source so building Bazel requires
+a minimal set of extra dependencies.
+
+
 [aether](http://eclipse.org/aether/)
 --------