Use note formatting in installation and upgrade guide

6 files changed, 57 insertions, 54 deletions

diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli
index 400b61e..a2a6864 100644
--- a/BOOTSTRAP-MINGW.cli
+++ b/BOOTSTRAP-MINGW.cli
@@ -44,11 +44,11 @@ the \c{build2-mingw} package), for example:
 > .\build-mingw.bat --make mingw32-make --make -j8 g++
 \
 
-Note also that at about half way through (\c{bpkg fetch} at step 4 below) the
+\N|Note that at about half way through (\c{bpkg fetch} at step 4 below) the
 script will stop and prompt you to verify the authenticity of the repository
 certificate. To run the script unattended you can specify the certificate
 fingerprint with the \c{--trust} option (see \c{build-mingw.bat /?} for
-details).
+details).|
 
 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
@@ -60,9 +60,9 @@ versions. It can also be used to uninstall the toolchain:
 > bpkg uninstall build2 bpkg
 \
 
-Note also that in both cases (manual or scripted bootstrap), if something
-goes wrong and you need to restart the process, you \b{must} start with a
-clean toolchain source by unpacking it afresh from the archive.
+\N|Note that in both cases (manual or scripted bootstrap), if something goes
+wrong and you need to restart the process, you \b{must} start with a clean
+toolchain source by unpacking it afresh from the archive.|
 
 The rest of this section outlines the manual bootstrap process.
 
diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli
index 7076deb..e1c4104 100644
--- a/BOOTSTRAP-MSVC.cli
+++ b/BOOTSTRAP-MSVC.cli
@@ -26,11 +26,11 @@ prompt) like this:
 > .\build-msvc.bat
 \
 
-Note also that at about half way through (\c{bpkg fetch} at step 4 below) the
+\N|Note that at about half way through (\c{bpkg fetch} at step 4 below) the
 script will stop and prompt you to verify the authenticity of the repository
 certificate. To run the script unattended you can specify the certificate
 fingerprint with the \c{--trust} option (see \c{build-msvc.bat /?} for
-details).
+details).|
 
 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
@@ -42,9 +42,9 @@ versions. It can also be used to uninstall the toolchain:
 > bpkg uninstall build2 bpkg
 \
 
-Note also that in both cases (manual or scripted bootstrap), if something
-goes wrong and you need to restart the process, you \b{must} start with a
-clean toolchain source by unpacking it afresh from the archive.
+\N|Note that in both cases (manual or scripted bootstrap), if something goes
+wrong and you need to restart the process, you \b{must} start with a clean
+toolchain source by unpacking it afresh from the archive.|
 
 The rest of this section outlines the manual bootstrap process.
 
diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
index 9e5b37d..e7dbc8a 100644
--- a/BOOTSTRAP-UNIX.cli
+++ b/BOOTSTRAP-UNIX.cli
@@ -13,10 +13,10 @@ Cygwin) where you already have a UNIX shell with standard utilities.
 
 \li|\b{1. Create Build Directory}\n
 
-Note that you will want to keep this directory around in order to upgrade to
-new toolchain versions in the future. In this guide we will use
-\c{~/build2-build/} as the build directory and \c{/usr/local/} as the
-installation directory but you can use other paths.
+You will want to keep this directory around in order to upgrade to new
+toolchain versions in the future. In this guide we use \c{~/build2-build/} as
+the build directory and \c{/usr/local/} as the installation directory but you
+can use other paths.
 
 \
 $ cd
@@ -86,10 +86,10 @@ instead of \c{make} on some platforms), for example:
 $ ./build.sh --make make --make -j8 g++
 \
 
-Note also that at about half way through (\c{bpkg fetch} at step 4 below) the
+\N|Note that at about half way through (\c{bpkg fetch} at step 4 below) the
 script will stop and prompt you to verify the authenticity of the repository
 certificate. To run the script unattended you can specify the certificate
-fingerprint with the \c{--trust} option (see \c{build.sh -h} for details).
+fingerprint with the \c{--trust} option (see \c{build.sh -h} for details).|
 
 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
@@ -101,9 +101,9 @@ $ cd build2-toolchain-X.Y
 $ bpkg uninstall build2 bpkg
 \
 
-Note also that in both cases (manual or scripted bootstrap), if something
-goes wrong and you need to restart the process, you \b{must} start with a
-clean toolchain source by unpacking it afresh from the archive.
+\N|Note that in both cases (manual or scripted bootstrap), if something goes
+wrong and you need to restart the process, you \b{must} start with a clean
+toolchain source by unpacking it afresh from the archive.|
 
 The rest of this section outlines the manual bootstrap process.
 
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
index 6e7ec6e..c053573 100644
--- a/BOOTSTRAP-WINDOWS.cli
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -9,10 +9,10 @@ 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.
 
-Note also that if you continue with these instructions but you already have
-your own installation of MSYS and/or MinGW, then make sure that their paths
-are not in your \c{PATH} environment variable when building and using
-\c{build2} since they may provide conflicting DLLs.
+\N|Note that if you continue with these instructions but you already have your
+own installation of MSYS and/or MinGW, then make sure that their paths are not
+in your \c{PATH} environment variable when building and using \c{build2} since
+they may provide conflicting DLLs.|
 
 The \c{build2} toolchain on Windows requires a set of extra utilities
 (\c{install}, \c{diff}, \c{curl}, \c{tar}, etc). These are provided by the
@@ -21,20 +21,20 @@ 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 3 or later or MinGW
-GCC 4.9 or later. Note also that MinGW GCC must be configured with the
-\c{posix} threading model (this is currently the only configuration that
-implements C++11 threads; run \c{g++ -v} to verify).
+GCC 4.9 or later. 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}.
 
-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}.
+\N|If using your own MinGW GCC installation, make sure it is configured with
+the \c{posix} threading model (this is currently the only configuration that
+implements C++11 threads; run \c{g++ -v} to verify).|
 
-Note also that you \b{absolutely must} match the width (32/64-bit) of the
-toolchain build to the \c{baseutils} and \c{mingw} packages. They must all be
-32-bit or all 64-bit. If you are running 64-bit Windows, it is strongly
-recommended that you build the 64-bit (x86_64) version of the toolchain as
-well as use the 64-bit versions of the \c{baseutils} and \c{mingw} packages.
+\N|Note that you \b{must} match the width (32/64-bit) of the toolchain to the
+\c{baseutils} and \c{mingw} packages. They must all be 32-bit or all 64-bit.
+If you are running 64-bit Windows, it is strongly recommended that you build
+the 64-bit (x86_64) version of the toolchain and use the 64-bit versions of
+the \c{baseutils} and \c{mingw} packages.|
 
 To bootstrap on Windows with either MSVC or MinGW start with the following
 common steps:
@@ -50,10 +50,10 @@ for MSVC-specific instructions).
 
 \li|\n\b{2. Create Build Directory}\n
 
-Note that you will want to keep this directory around in order to upgrade
-to new toolchain versions in the future. In this guide we will use
-\c{C:\\build2-build\\} as the build directory and \c{C:\\build2\\} as the
-installation directory but you can use other paths.
+You will want to keep this directory around in order to upgrade to new
+toolchain versions in the future. In this guide we use \c{C:\\build2-build\\}
+as the build directory and \c{C:\\build2\\} as the installation directory but
+you can use other paths.
 
 \
 > C:
@@ -68,7 +68,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.
+64-bit Windows and with \c{i686} for 32-bit:
 
 \
 build2-baseutils-X.Y.Z-<arch>-windows.zip
@@ -109,7 +109,7 @@ and work:
 
 |
 
-\li|\n\b{7. Unpack \c{build2-mingw}}\n
+\li|\n\b{7. Unpack \c{build2-mingw} (optional)}\n
 
 If required, unpack the \c{build2-mingw-X.Y.Z-<arch>-windows.tar.xz} archive
 into \c{C:\\build2\\}:
diff --git a/INSTALL.cli b/INSTALL.cli
index fcdd440..c62a0d8 100644
--- a/INSTALL.cli
+++ b/INSTALL.cli
@@ -26,12 +26,13 @@ a simple matter of adjusting paths and, if used, line continuations.
 
 The \c{build2} toolchain requires a C++14 compiler. From the commonly-used
 options, GCC 4.9, Clang 3.4, and MSVC 14 (2015) Update 3 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 12 (2013)
-(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.
+of these compilers should work.
+
+\N|Note 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 12 (2013) (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.
 
@@ -64,10 +65,11 @@ Finally, the staged at step 3 tools are uninstalled.||
 
 The end result of the bootstrap process is the installed toolchain as well as
 the \c{bpkg} configuration (created at step 4) that can be used to upgrade to
-newer versions. You can also skip step 4 and instead install at step 3 if for
-some reason you prefer not to build from packages (for example, because the
-machine is offline).
+newer versions.
 
+\N|You can skip step 4 and instead install at step 3 if for some reason you
+prefer not to build from packages (for example, because the machine is
+offline).|
 
 For Windows, if you are using either MSVC or MinGW, continue with
 \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}. If using MSYS or Cygwin,
diff --git a/UPGRADE.cli b/UPGRADE.cli
index 01444d5..da078b2 100644
--- a/UPGRADE.cli
+++ b/UPGRADE.cli
@@ -26,10 +26,11 @@ old toolchain, install the new toolchain as \"final\", and finally uninstall
 
 We recommend that you use a dirty upgrade for patch releases with the same
 \c{X.Y} (\c{MAJOR.MINOR}) version and a staged upgrade otherwise. With patch
-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.
+releases we guarantee not to alter the installation file set.
+
+\N|Note 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 straightforward: