Proofread GN docs and update links
Change-Id: Idb78bd2d8fdc6a194f1bda9db233f56fb21090eb
Reviewed-on: https://chromium-review.googlesource.com/573527
Commit-Queue: Quinten Yearsley <qyearsley@chromium.org>
Reviewed-by: Dirk Pranke <dpranke@chromium.org>
Cr-Original-Commit-Position: refs/heads/master@{#487492}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: 55b93fe82e7fa4f1ea2a31d652b50968503fdb84diff --git a/tools/gn/README.md b/tools/gn/README.md
index ef61ca9..0d6fa99 100644
--- a/tools/gn/README.md
+++ b/tools/gn/README.md
@@ -1,8 +1,7 @@
# What is GN?
-GN is a meta-build system that generates
-[NinjaBuild](https://ninja-build.org)
-files so that you can build Chromium with Ninja.
+GN is a meta-build system that generates [Ninja](https://ninja-build.org)
+build files so that you can build Chromium with Ninja.
## Why did you switch from GYP?
@@ -39,9 +38,9 @@
* [Quick start](docs/quick_start.md)
* [FAQ](docs/faq.md)
* [Language and operation details](docs/language.md)
- * [Reference](docs/reference.md) The built-in `gn help` documentation.
+ * [Reference](docs/reference.md): The built-in `gn help` documentation.
* [Style guide](docs/style_guide.md)
* [Cross compiling and toolchains](docs/cross_compiles.md)
* [Hacking on GN itself](docs/hacking.md)
- * [GNStandalone](docs/standalone.md) Standalone GN projects
- * [UpdateGNBinaries](docs/update_binaries.md) Pushing new binaries
+ * [Standaline GN projects](docs/standalone.md)
+ * [Pushing new binaries](docs/update_binaries.md)
diff --git a/tools/gn/docs/cross_compiles.md b/tools/gn/docs/cross_compiles.md
index 52f9559..6da6654 100644
--- a/tools/gn/docs/cross_compiles.md
+++ b/tools/gn/docs/cross_compiles.md
@@ -80,8 +80,8 @@
By default, dependencies listed in the `deps` variable of a rule use the
same (currently active) toolchain. You may specify a different toolchain
-using the `foo(bar)` label notation as described in
-[GNLanguage#Labels](language.md#Labels).
+using the `foo(bar)` label notation as described in [the label section
+of the reference doc](reference.md#Toolchains).
Here's an example of when to use `target_cpu` vs `current_cpu`:
@@ -111,9 +111,7 @@
## As a //build/config or //build/toolchain author
-As described in
-[GNLanguage#Overall-build-flow](language.md#Overall-build-flow), the
-`default_toolchain` is declared in the `//build/config/BUILDCONFIG.gn`
+The `default_toolchain` is declared in the `//build/config/BUILDCONFIG.gn`
file. Usually the `default_toolchain` should be the toolchain for the
`target_os` and `target_cpu`. The `current_toolchain` reflects the
toolchain that is currently in effect for a rule.
diff --git a/tools/gn/docs/hacking.md b/tools/gn/docs/hacking.md
index ab94b58..be3f132 100644
--- a/tools/gn/docs/hacking.md
+++ b/tools/gn/docs/hacking.md
@@ -2,9 +2,9 @@
## Building GN itself
-GN is part of the Chromium tree. If you have a Chromium checkout, you
-already have the source and you can do `ninja -C out/Debug gn` to
-build it.
+GN is part of the Chromium tree, in [//tools/gn/](../). If you have a
+Chromium checkout, you already have the source and you can do `ninja -C
+out/Debug gn` to build it.
To build gn using gn, run (in the root `src` directory):
diff --git a/tools/gn/docs/language.md b/tools/gn/docs/language.md
index 0d60cb5..dcc6c9e 100644
--- a/tools/gn/docs/language.md
+++ b/tools/gn/docs/language.md
@@ -90,8 +90,8 @@
c = "foo${a}bar.cc" # c -> "foomypathbar.cc"
```
-You can encode 8-bit haracters using "$0xFF" syntax, so a string with newlines
-(hex 0A) would `"look$0x0Alike$0x0Athis"
+You can encode 8-bit characters using "$0xFF" syntax, so a string with newlines
+(hex 0A) would `"look$0x0Alike$0x0Athis"`.
### Lists
@@ -291,7 +291,7 @@
* `component`: Either a source set or shared library, depending on the
build type.
- * `test`: A test executable. On mobile this will create the appropritate
+ * `test`: A test executable. On mobile this will create the appropriate
native app type for tests.
* `app`: Executable or Mac/iOS application.
* `android_apk`: Make an APK. There are a _lot_ of other Android ones, see
@@ -514,8 +514,7 @@
Blaze is Google's internal build system, now publicly released as
[Bazel](http://bazel.io/). It has inspired a number of other systems such as
-[Pants](https://github.com/twitter/commons/tree/master/src/python/twitter/pants)
-and [Buck](http://facebook.github.io/buck/).
+[Pants](http://www.pantsbuild.org/) and [Buck](http://facebook.github.io/buck/).
In Google's homogeneous environment, the need for conditionals is very
low and they can get by with a few hacks (`abi_deps`). Chrome uses
diff --git a/tools/gn/docs/quick_start.md b/tools/gn/docs/quick_start.md
index 8b064de..629b36d 100644
--- a/tools/gn/docs/quick_start.md
+++ b/tools/gn/docs/quick_start.md
@@ -5,7 +5,7 @@
## Running GN
You just run `gn` from the command line. There is a script in
-depot\_tools (which is presumably on your path) with this name. The
+`depot_tools`, which is presumably in your PATH, with this name. The
script will find the binary in the source tree containing the current
directory and run it.
@@ -45,10 +45,9 @@
gn args --list out/my_build
```
-on the command line. See "Taking build arguments" below for information
-on how to use these in your code. (Note that you have to specify the
-build directory for this command because the available arguments can
-change according to what's set.
+on the command line. Note that you have to specify the build directory
+for this command because the available arguments can change according
+to what's set.
Chrome developers can also read the [Chrome-specific build
configuration](http://www.chromium.org/developers/gn-build-configuration)
diff --git a/tools/gn/docs/standalone.md b/tools/gn/docs/standalone.md
index 81dd896..29d6236 100644
--- a/tools/gn/docs/standalone.md
+++ b/tools/gn/docs/standalone.md
@@ -39,6 +39,6 @@
(e.g., to do the full Chrome build instead), you can use the command-line
flags `--root` and `--dotfile` to set the values you want.
-If you want a completely standalone build that has nothing to do w/ Chrome
-and doesn't use Chrome's //build files, you can look at an example in
+If you want a completely standalone build that has nothing to do with Chrome
+and doesn't use Chrome's `//build` files, you can look at an example in
[//tools/gn/example](../example).
diff --git a/tools/gn/docs/style_guide.md b/tools/gn/docs/style_guide.md
index a87ad8f..466f872 100644
--- a/tools/gn/docs/style_guide.md
+++ b/tools/gn/docs/style_guide.md
@@ -1,25 +1,27 @@
-# GN Style Guide
+# GN Style Guide
[TOC]
+
## Naming and ordering within the file
### Location of build files
It usually makes sense to have more build files closer to the code than
-fewer ones at the toplevel (this is in contrast with what we did with
-GYP). This makes things easier to find and owners reviews easier since
-changes are more focused.
+fewer ones at the top level; this is in contrast with what we did with
+GYP. This makes things easier to find, and also makes the set of owners
+required for reviews smaller since changes are more focused to particular
+subdirectories.
### Targets
- * Most BUILD files should have a target with the same name of the
+ * Most BUILD files should have a target with the same name as the
directory. This target should be the first target.
- * Other targets should be in "some order that makes sense." Usually
+ * Other targets should be in some logical order -- usually
more important targets will be first, and unit tests will follow the
corresponding target. If there's no clear ordering, consider
alphabetical order.
* Test support libraries should be static libraries named "test\_support".
- So "//ui/compositor:test\_support". Test support libraries should
+ For example, "//ui/compositor:test\_support". Test support libraries should
include as public deps the non-test-support version of the library
so tests need only depend on the test\_support target (rather than
both).
@@ -99,7 +101,7 @@
GN contains a built-in code formatter which defines the formatting style.
Some additional notes:
- * Variables are `lower_case_with_underscores`
+ * Variables are `lower_case_with_underscores`.
* Comments should be complete sentences with periods at the end.
* Compiler flags and such should always be commented with what they do
and why the flag is needed.
@@ -165,7 +167,7 @@
loadable module, you normally need to use source sets. This is because
object files with no symbols referenced from within the shared library will
not be linked into the final library at all. This omission will happen even
- if that object file has a symbol marked for export that targets dependant
+ if that object file has a symbol marked for export that targets dependent
on that shared library need. This will result in undefined symbols when
linking later targets.
@@ -203,14 +205,14 @@
to be linked statically in a large binary, but for developers to use shared
libraries for most operations.
-A shared library will be listed on the link line of dependant targets and will
+A shared library will be listed on the link line of dependent targets and will
be loaded automatically by the operating system when the application starts
and symbols automatically resolved. A loadable module will not be linked
directly and the application must manually load it.
On Windows and Linux shared libraries and loadable modules result in the same
type of file (`.dll` and `.so`, respectively). The only difference is in how
-they are linked to dependant targets. On these platforms, having a `deps`
+they are linked to dependent targets. On these platforms, having a `deps`
dependency on a loadable module is the same as having a `data_deps`
(non-linked) dependency on a shared library.
diff --git a/tools/gn/docs/update_binaries.md b/tools/gn/docs/update_binaries.md
index 738da3c..d3e3bbc 100644
--- a/tools/gn/docs/update_binaries.md
+++ b/tools/gn/docs/update_binaries.md
@@ -1,4 +1,5 @@
-# How to update the [GN binaries](gn.md) that Chromium uses.
+# How to update the GN binaries that Chromium uses.
-Any committer should be able to do a roll by running //tools/gn/bin/roll_gn.py
-on linux or mac.
+Any committer should be able to do a roll by running
+[//tools/gn/bin/roll_gn.py](../bin/roll_gn.py) on Linux or Mac.
+
