Documentation improvements

8 files changed, 110 insertions, 89 deletions

diff --git a/BOOTSTRAP-MACOSX.cli b/BOOTSTRAP-MACOSX.cli
index a60a145..391aa36 100644
--- a/BOOTSTRAP-MACOSX.cli
+++ b/BOOTSTRAP-MACOSX.cli
@@ -5,8 +5,8 @@
 "
 The \c{build2} toolchain requires Mac OS version 10.5 (Leopard) or later. We
 will also be using the system C++ toolchain that comes with the Xcode Command
-Line Tools (you should be able to use a custom C++ toolchain, however, this
-is the only configuration that is tested and guaranteed to work).
+Line Tools. You should be able to use other/custom C++ toolchains, however,
+this is the only configuration that is tested and guaranteed to work.
 
 To verify Command Line Tools are installed, run:
 
diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli
index 3dc9cb9..8f6591d 100644
--- a/BOOTSTRAP-MINGW.cli
+++ b/BOOTSTRAP-MINGW.cli
@@ -3,7 +3,7 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-Continuing with \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}, if you are
+Continuing from \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}, if you are
 using your own MinGW distribution, then the resulting \c{build2} binaries will
 most likely required a number of DLLs in order to run. It is therefore
 recommended that you copy the following files from your MinGW \c{bin\\}
diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli
index 835cf50..5916d55 100644
--- a/BOOTSTRAP-MSVC.cli
+++ b/BOOTSTRAP-MSVC.cli
@@ -3,7 +3,7 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-Continuing with \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}, if you have
+Continuing from \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}, if you have
 already started an appropriate Visual Studio command prompt, then you can
 continue using it. Otherwise, start the \"x64 Native Tools Command Prompt\" if
 you are on 64-bit Windows or \"x86 Native Tools Command Prompt\" if you are on
@@ -14,7 +14,7 @@ you are on 64-bit Windows or \"x86 Native Tools Command Prompt\" if you are on
 \
 
 To build with MSVC you can either perform the following steps manually or, if
-if after reviewing the steps you are happy with using the defaults, run the
+after reviewing the steps you are happy with using the defaults, run the
 \c{build-msvc.bat} batch file. It performs (and echoes) the same set of steps
 as outline below but only allows you to customization the installation
 directory (run \c{build-msvc.bat /?} for usage). You can also specify an
diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
index f97e6f5..68b5fee 100644
--- a/BOOTSTRAP-UNIX.cli
+++ b/BOOTSTRAP-UNIX.cli
@@ -6,7 +6,7 @@
 The following instructions are for bootstrapping \c{build2} on UNIX-like
 operating systems (GNU/Linux, FreeBSD, etc). For Mac OS X first see
 \l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}. These instructions should
-also be used for UNIX emulation layers on Windows (for example, MSYS2 or
+also be used for UNIX emulation layers on Windows (for example, MSYS or
 Cygwin) where you already have a UNIX shell with standard utilities.
 
 \dl|
@@ -30,9 +30,10 @@ $ cd build2-build
 
 Download \c{build2-toolchain-X.Y.Z.tar.xz} (or its \c{.tar.gz} variant if you
 don't have \cb{xz(1)}) as well as its \c{.sha256} checksum from
-\l{https://download.build2.org}, into \c{~/build2-build/} (build directory).
+\l{https://download.build2.org}.
 
-Verify the archive checksum matches:
+Place everything into \c{~/build2-build/} (build directory) and verify the
+archive checksum matches:
 
 \
 # Linux, MSYS, Cygwin:
@@ -86,7 +87,7 @@ the \c{--trust} option.
 
 The end result of the bootstrap process (performed either with the script or
 manually) is the installed toolchain as well as the \c{bpkg} configuration in
-\c{build2-toolchain-X.Y} that can be used to \l{#UPGRADE upgrade} to newer
+\c{build2-toolchain-X.Y/} that can be used to \l{#UPGRADE upgrade} to newer
 versions. It can also be used to uninstall the toolchain:
 
 \
@@ -102,7 +103,7 @@ continued from the above list.
 \li|3. Bootstrap, Phase 1\n
 
 First, we build a minimal build system with the provided \c{bootstrap.sh}
-script. Normally the only argument you will pass to this script is the
+script. Normally, the only argument you will pass to this script is the
 C++ compiler to use but there is also a way to specify compile options
 and a few other things; run \c{bootstrap.sh -h} and see the \c{build2/INSTALL}
 file for details.
@@ -139,15 +140,15 @@ program (remove the \c{config.install.sudo} line if you don't need one).
 The strange-looking \c{config.install.data_root=root/stage} means install
 data files (as opposed to executable files) into the \c{stage/} subdirectory
 of wherever \c{config.install.root} points (so in our case it will be
-/usr/local/stage). Note that this subdirectory is temporary and will be
+\c{/usr/local/stage/}). Note that this subdirectory is temporary and will be
 removed in a few steps. But if you don't like the default location, feel
 free to change it (for example, to \c{/tmp/stage}).
 
 You may also need to remove the \c{config.bin.rpath} line if your target
 doesn't support \i{rpath}. Specifically, if building on Windows (with MSYS or
 Cygwin), remove both \c{.rpath} and \c{.sudo}. But if unsure, leave \c{.rpath}
-in \- if your target doesn't support it, you will get an error and will just
-need to reconfigure without it.
+in \- if your target doesn't support it, you will get an error and will need
+to reconfigure without it.
 
 \
 $ run cd ..  # Back to build2-toolchain-X.Y.Z/
@@ -191,8 +192,26 @@ Strictly speaking this is not absolutely necessary and you can adjust
 the rest of the commands to use absolute paths. This, however, does not make
 for very readable examples so below we assume the installation's \c{bin/}
 subdirectory is in \c{PATH}.
+
+On the next step we will use \c{bpkg} to build and install the \"final\"
+toolchain. If for some reason you prefer not to build from packages (for
+example, because the machine is offline), then you can convert this step into
+the \"final\" installation and skip the rest. For this your will need to
+change the \c{configure} command line above along these lines:
+
+\
+$ build2/build2/b-boot configure  \
+  config.cxx=g++                  \
+  config.cc.coptions=-O3          \
+  config.bin.lib=shared           \
+  config.bin.rpath=/usr/local/lib \
+  config.install.root=/usr/local  \
+  config.install.sudo=sudo
+\
+
 |
 
+
 \li|\n6. Install\n
 
 Next, we use the staged toolchain to build and install the \"final\" toolchain
@@ -205,13 +224,13 @@ $ cd ..  # Back to build2-build/
 $ mkdir build2-toolchain-X.Y
 $ cd build2-toolchain-X.Y
 
-$ bpkg-stage create \
-  cc \
-  config.cxx=g++ \
-  config.cc.coptions=-O3 \
-  config.bin.lib=shared \
+$ bpkg-stage create               \
+  cc                              \
+  config.cxx=g++                  \
+  config.cc.coptions=-O3          \
+  config.bin.lib=shared           \
   config.bin.rpath=/usr/local/lib \
-  config.install.root=/usr/local \
+  config.install.root=/usr/local  \
   config.install.sudo=sudo
 \
 
@@ -244,7 +263,7 @@ $ bpkg-stage --version
 The last thing we need to do is uninstall the staged toolchain:
 
 \
-$ cd ../build2-toolchain-X.Y.Z/  # Back to the bootstrap directory.
+$ cd ../build2-toolchain-X.Y.Z/  # Back to bootstrap.
 $ b uninstall
 \
 
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
index 245f5c4..3a91dbb 100644
--- a/BOOTSTRAP-WINDOWS.cli
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -5,16 +5,15 @@
 "
 The following instructions are for bootstrapping \c{build2} with either MSVC
 or MinGW using the Windows command prompt. If you are using any kind of UNIX
-emulation layer (for example, MSYS2 or Cygwin) and already have a UNIX shell
+emulation layer (for example, MSYS or Cygwin) and already have a UNIX shell
 with standard utilities, then you most likely should follow \l{#BOOTSTRAP-UNIX
 Bootstrapping on UNIX} instead.
 
 The \c{build2} toolchain on Windows requires a set of extra utilities
-(\c{install}, \c{diff}, \c{wget}, \c{tar}, etc). These are provided in the
+(\c{install}, \c{diff}, \c{wget}, \c{tar}, etc). These are provided by the
 \c{build2-baseutils} package (see the \c{README} file inside for details).
-Normally the \c{build2} toolchain itself is installed into the same directory
-as the utilities in order to produce a combined \c{build2+utilities}
-installation.
+Normally, the \c{build2} toolchain itself is installed into the same directory
+as the utilities in order to produce the  combined installation.
 
 To build on Windows you will need either MSVC 14 Update 2 or later or MinGW
 GCC 4.8 or later. Note also that MinGW GCC must be configured with the
@@ -24,7 +23,10 @@ implements C++11 threads; run \c{g++ --version} to verify).
 If you don't already have a suitable C++ compiler, then you can use the
 \c{build2-mingw} package which provides a minimal MinGW-W64 GCC distribution
 (see the \c{README} file inside for details). If used, then it should be
-unpacked into the same directory as \c{build2-baseutils} as described below.
+unpacked into the same directory as \c{build2-baseutils}.
+
+To bootstrap on Windows with either MSVC or MinGW start with the following
+common steps:
 
 \dl|
 
@@ -55,8 +57,7 @@ installation directory but you can use other paths.
 
 Download the following files as well as their \c{.sha256} checksums from
 \l{https://download.build2.org}, replacing \i{<arch>} with \c{x86_64} for
-64-bin Windows and with \c{i686} for 32-bit. Place everything into
-\c{C:\\build2-build\\} (build directory).
+64-bin Windows and with \c{i686} for 32-bit.
 
 \
 build2-baseutils-X.Y.Z-<arch>.zip
@@ -64,7 +65,7 @@ build2-mingw-X.Y.Z-<arch>.tar.xz    (if required)
 build2-toolchain-X.Y.Z.tar.xz
 \
 
-|
+Place everything into \c{C:\\build2-build\\} (build directory).|
 
 \li|\n4. Verify Archive Checksums\n
 
@@ -79,15 +80,16 @@ Verify archive checksums match (compare visually):
 
 \li|\n5. Unpack \c{build2-baseutils}\n
 
-Unpack the \c{build2-baseutils-X.Y.Z-<arch>.zip} archive into to \c{C:\\} using
-Windows Explorer (for example, copy the archive directory and paste it).
+Unpack the \c{build2-baseutils-X.Y.Z-<arch>.zip} archive into \c{C:\\} using
+Windows Explorer (for example, copy the archive directory and then paste it).
 Rename it to \c{C:\\build2\\}. This will be the toolchain installation
 directory.
 |
 
 \li|\n6. Set \c{PATH}\n
 
-Also verify the utilities are found and work:
+Set the \c{PATH} environment variable and verify the utilities are found and
+work:
 
 \
 > set PATH=C:\build2\bin;%PATH%
diff --git a/INSTALL.cli b/INSTALL.cli
index a8442fa..31a99e4 100644
--- a/INSTALL.cli
+++ b/INSTALL.cli
@@ -4,24 +4,24 @@
 
 "
 One of the primary goals of the \c{build2} toolchain is to provide a uniform
-build interface across all the platforms and compilers. If you already have
-the toolchain installed and would like to upgrade to a newer version, then
-there is a single set of \l{#UPGRADE upgrade instructions} for all the
-platforms.
+build interface across all the platforms and compilers. As a result, if you
+already have the toolchain installed and would like to upgrade to a newer
+version, then there is a single set of \l{#UPGRADE upgrade instructions} for
+all the platforms.
 
 If, however, you need to install the toolchain for the first time, then it has
 to be bootstrapped and that process is platform-specific. The rest of this
 section discusses a few general bootstrap considerations and then directs
-you to appropriate platform-specific instructions.
+you to the appropriate platform-specific instructions.
 
 The \c{build2} toolchain requires a C++14 compiler. From the commonly-used
-options, GCC 4.8, Clang 3.4, and MSVC 2015/14 Update 2 or later
-versions are known to work. Note also that the C++ compiler that you use to
-build the \c{build2} toolchain and the one that you will use to build your
+options, GCC 4.8, Clang 3.4, and MSVC 2015/14 Update 2 or any later versions
+of these compilers should work. Note also that the C++ compiler that you use
+to build the \c{build2} toolchain and the one that you will use to build your
 projects need not be the same. For example, if you are using MSVC 2013/12
-(which cannot build \c{build2}), it is perfectly fine to get a minimal
-MinGW toolchain and use that to build \c{build2}; you will still be able
-to use MSVC to build your own projects.
+(which cannot build \c{build2}), it is perfectly fine to get a minimal MinGW
+toolchain and use that to build \c{build2}; you will still be able to use MSVC
+to build your own code.
 
 At the high level, the bootstrap process involves the following 5 steps.
 
@@ -44,8 +44,8 @@ On this step the entire toolchain is built and staged.|
 
 \li|\n4. Install\n
 
-Next, the staged toolchain is used to build and install the toolchain from
-the package repository and using the \c{bpkg} package manager.|
+Next, the staged toolchain is used to build and install the \"final\"
+toolchain from the package repository and using the \c{bpkg} package manager.|
 
 \li|\n5. Clean\n
 
@@ -53,12 +53,12 @@ Finally, the staged toolchain is uninstalled.||
 
 The end result of the bootstrap process is the installed toolchain as well as
 the \c{bpkg} configuration (created on step 4) that can be used to upgrade to
-newer versions. You can also skip step 4 and instead install on step 3 if
-you would prefer not to use the package manager (for example, because the
-machine is offline).
+newer versions. You can also skip step 4 and instead install on step 3 if for
+some reason you prefer not to use the package manager (for example, because
+the machine is offline).
 
 
-For Windows, if using either MSVC or MinGW, continue with
+For Windows, if you are using either MSVC or MinGW, continue with
 \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}. If using MSYS or Cygwin,
 then instead refer to \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}.
 
diff --git a/UPGRADE.cli b/UPGRADE.cli
index d6bb448..bae07a9 100644
--- a/UPGRADE.cli
+++ b/UPGRADE.cli
@@ -5,12 +5,12 @@
 "
 At this point we assume that you have the build2 toolchain installed and would
 like to upgrade it to a newer version. We also expect that you have the
-toolchain \c{bpkg} configuration in the \c{build2-toolchain-X.Y} directory, as
-produced by the bootstrap process. If you don't have the \c{bpkg}
+toolchain \c{bpkg} configuration in the \c{build2-toolchain-X.Y/} directory,
+as produced by the bootstrap process. If you don't have the \c{bpkg}
 configuration but do have the toolchain installed somehow (for example, using
-your distribution's package manager), then you can create one as shown at the
-end. If you have neither, then you will need to go through the bootstrap
-process.
+your distribution's package manager), then you can create the configuration as
+shown at the end. If you have neither, then you will need to go through the
+bootstrap process.
 
 There are two ways to upgrade: dirty (but quick) and staged (but more
 involved). In the \i{dirty upgrade} we override the existing installation
@@ -21,15 +21,15 @@ functional.
 
 In the \i{staged upgrade} we first install a \c{-stage} build of the new
 toolchain (similar to what we did during bootstrap), test it, uninstall the
-old toolchain, install the new toolchain as non-staged, and finally uninstall
-the \c{-stage} installation.
-
-We recommend that you use a dirty upgrade for a bugfix-only release (the same
-\c{MAJOR.MINOR} version) and a staged upgrade otherwise. With bugfix-only
-releases we guarantee not to alter the installation file set. Note also that
-without periodic upgrades your version of the toolchain may become too old to
-be able to upgrade itself. In this case you will have to fall back onto the
-bootstrap process.
+old toolchain, install the new toolchain as \"final\", and finally uninstall
+\c{-stage}.
+
+We recommend that you use a dirty upgrade for  bugfix-only releases (the same
+\c{X.Y} (\c{MAJOR.MINOR}) version) and a staged upgrade otherwise. With
+bugfix-only releases we guarantee not to alter the installation file set. Note
+also that without periodic upgrades your version of the toolchain may become
+too old to be able to upgrade itself. In this case you will have to fall back
+onto the bootstrap process.
 
 The dirty upgrade is fairly simple:
 
@@ -60,8 +60,8 @@ The staged upgrade consists of several steps:
 
 There is no harm in running \c{bpkg fetch} in the existing configuration so
 we can use it to determine if any updates are available, whether we can use
-the simpler dirty upgrade, and, if not, the target \c{MAJOR.MINOR} version
-for a staged upgrade:
+the simpler dirty upgrade, and, if not, the target \c{X.Y} (\c{MAJOR.MINOR})
+version for the staged upgrade:
 
 \
 $ cd build2-toolchain-X.Y
@@ -95,7 +95,7 @@ Or, using Windows command prompt:
 \li|\n2. Build and Install as \c{-stage}\n
 
 This step is similar to the dirty upgrade except we use the copied
-configuration and install the toolchain with the \c{-stage} suffix.
+configuration and install the toolchain with the \c{-stage} suffix:
 
 \
 $ cd build2-toolchain-X.Z
@@ -138,8 +138,8 @@ $ bpkg-stage install build2 bpkg
 
 \li|\n5. Uninstall Staged\n
 
-Finally we clean up by removing the staged toolchain (hint: use command line
-history to find the corresponding \c{install} command and change it to
+Finally, we clean up by removing the staged toolchain (hint: use the command
+line history to find the corresponding \c{install} command and change it to
 \c{uninstall}):
 
 \
@@ -149,14 +149,14 @@ $ bpkg uninstall                      \
   build2 bpkg
 \
 
-You can also remove the old configuration in \c{build2-toolchain-X.Y} if you
+You can also remove the old configuration in \c{build2-toolchain-X.Y/} if you
 think you no longer need it.
 
 ||
 
 If you ever need to (re-)create the \c{bpkg} configuration for the toolchain
 from scratch, it is fairly simple (you may need to adjust the compiler,
-options, installation directory, etc):
+options, installation directory, etc; see the bootstrap steps for details):
 
 For UNIX-like operating systems (GNU/Linux, Mac OS X, FreeBSD, etc):
 
diff --git a/doc/intro.cli b/doc/intro.cli
index 9cc777a..a9e877f 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -43,8 +43,8 @@ fetching build2.org/hello/stable
 2 package(s) in 1 repository(s)
 
 $ bpkg build hello
-build libhello/1.0.0 (required by hello)
-build hello/1.0.0
+  build libhello/1.0.0 (required by hello)
+  build hello/1.0.0
 continue? [Y/n] y
 libhello-1.0.0.tar.gz        100% of 2428  B  983 kBps 00m01s
 fetched libhello/1.0.0
@@ -273,8 +273,8 @@ business:
 
 \
 $ bpkg build hello
-build libhello/1.0.0 (required by hello)
-build hello/1.0.0
+  build libhello/1.0.0 (required by hello)
+  build hello/1.0.0
 continue? [Y/n]
 \
 
@@ -318,8 +318,8 @@ $ bpkg drop hello
 following prerequisite packages were automatically built and will no longer be necessary:
   libhello
 drop prerequisite packages? [Y/n] y
-drop hello
-drop libhello
+  drop hello
+  drop libhello
 continue? [Y/n] y
 disfigured hello
 disfigured libhello
@@ -445,10 +445,10 @@ thumbs. Let's tell \c{bpkg} to build us \c{libhello} instead:
 
 \
 $ bpkg build libhello
-build libformat/1.0.0 (required by libhello)
-build libprint/1.0.0 (required by libhello)
-upgrade libhello/1.1.0
-reconfigure hello (dependent of libhello)
+  build libformat/1.0.0 (required by libhello)
+  build libprint/1.0.0 (required by libhello)
+  upgrade libhello/1.1.0
+  reconfigure hello (dependent of libhello)
 continue? [Y/n]
 \
 
@@ -541,8 +541,8 @@ the desired version for upgrades).
 
 \
 $ bpkg build libhello/1.0.0
-downgrade libhello/1.0.0
-reconfigure hello (dependent of libhello)
+  downgrade libhello/1.0.0
+  reconfigure hello (dependent of libhello)
 continue? [Y/n] y
 update dependent packages? [Y/n] y
 disfigured hello/1.0.0
@@ -1029,7 +1029,7 @@ archives or package directories):
 
 \
 $ bpkg build -d /tmp/hello-gcc5-release/ ./hello2/
-build hello2/1.0.0
+  build hello2/1.0.0
 continue? [Y/n] y
 unpacked hello2/1.0.0
 configured hello2/1.0.0
@@ -1042,10 +1042,10 @@ Let's upgrade \c{libhello} and see what happens:
 
 \
 $ bpkg build -d /tmp/hello-gcc5-release/ -L libhello
-build libformat/1.0.0 (required by libhello)
-build libprint/1.0.0 (required by libhello)
-upgrade libhello/1.1.0
-reconfigure hello2 (dependent of libhello)
+  build libformat/1.0.0 (required by libhello)
+  build libprint/1.0.0 (required by libhello)
+  upgrade libhello/1.1.0
+  reconfigure hello2 (dependent of libhello)
 continue? [Y/n] y
 disfigured hello2/1.0.0
 disfigured libhello/1.0.0
@@ -1091,8 +1091,8 @@ fetching build2.org/hello/stable (complements build2.org/hello/testing)
 5 package(s) in 2 repository(s)
 
 $ bpkg build libhello/1.0.0 path/to/hello2/
-build libhello/1.0.0
-build hello2/1.0.0
+  build libhello/1.0.0
+  build hello2/1.0.0
 continue? [Y/n] y
 libhello-1.0.0.tar.gz        100% of 2428  B  983 kBps 00m01s
 fetched libhello/1.0.0