Prefer --keep-stage-std for compiler rebuilds

Author: Zalathar

src/building/how-to-build-and-run.md

@@ -249,7 +249,7 @@ You will probably find that building the stage1 `std` is a bottleneck for you,
 but fear not, there is a (hacky) workaround...
 see [the section on avoiding rebuilds for std][keep-stage].
 
-[keep-stage]: ./suggested.md#faster-builds-with---keep-stage
+[keep-stage]: ./suggested.md#faster-rebuilds-with---keep-stage-std
 
 Sometimes you don't need a full build. When doing some kind of
 "type-based refactoring", like renaming a method, or changing the

src/building/suggested.md

@@ -306,7 +306,7 @@ steps, meaning it will have two precompiled compilers: stage0 compiler and `down
 for `stage > 0` steps. This way, it will never need to build the in-tree compiler. As a result, your
 build time will be significantly reduced by not building the in-tree compiler.
 
-## Faster builds with `--keep-stage`.
+## Faster rebuilds with `--keep-stage-std`
 
 Sometimes just checking whether the compiler builds is not enough. A common
 example is that you need to add a `debug!` statement to inspect the value of
@@ -319,32 +319,26 @@ that is easily detected and fixed).
 The sequence of commands you want is as follows:
 
 - Initial build: `./x build library`
-  - As [documented previously], this will build a functional stage1 compiler as
-    part of running all stage0 commands (which include building a `std`
-    compatible with the stage1 compiler) as well as the first few steps of the
-    "stage 1 actions" up to "stage1 (sysroot stage1) builds std".
-- Subsequent builds: `./x build library --keep-stage 1`
-  - Note that we added the `--keep-stage 1` flag here
+- Subsequent builds: `./x build library --keep-stage-std=1`
+  - Note that we added the `--keep-stage-std=1` flag here
 
-[documented previously]: ./how-to-build-and-run.md#building-the-compiler
-
-As mentioned, the effect of `--keep-stage 1` is that we just _assume_ that the
+As mentioned, the effect of `--keep-stage-std=1` is that we just _assume_ that the
 old standard library can be re-used. If you are editing the compiler, this is
-almost always true: you haven't changed the standard library, after all. But
+often true: you haven't changed the standard library, after all. But
 sometimes, it's not true: for example, if you are editing the "metadata" part of
 the compiler, which controls how the compiler encodes types and other states
 into the `rlib` files, or if you are editing things that wind up in the metadata
 (such as the definition of the MIR).
 
 **The TL;DR is that you might get weird behavior from a compile when using
-`--keep-stage 1`** -- for example, strange [ICEs](../appendix/glossary.html#ice)
-or other panics. In that case, you should simply remove the `--keep-stage 1`
+`--keep-stage-std=1`** -- for example, strange [ICEs](../appendix/glossary.html#ice)
+or other panics. In that case, you should simply remove the `--keep-stage-std=1`
 from the command and rebuild. That ought to fix the problem.
 
-You can also use `--keep-stage 1` when running tests. Something like this:
+You can also use `--keep-stage-std=1` when running tests. Something like this:
 
 - Initial test run: `./x test tests/ui`
-- Subsequent test run: `./x test tests/ui --keep-stage 1`
+- Subsequent test run: `./x test tests/ui --keep-stage-std=1`
 
 ## Using incremental compilation