Minor install/upgrade documentation improvements

9 files changed, 37 insertions, 28 deletions

diff --git a/BOOTSTRAP-MACOSX.cli b/BOOTSTRAP-MACOSX.cli
index 7200fc5..da7e968 100644
--- a/BOOTSTRAP-MACOSX.cli
+++ b/BOOTSTRAP-MACOSX.cli
@@ -26,5 +26,5 @@ To install Command Line Tools, run:
 $ xcode-select --install
 \
 
-Once this is done continue with \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}.
+Once this is done continue with \l{#bootstrap-unix Bootstrapping on UNIX}.
 "
diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli
index b1f913f..e2c07ee 100644
--- a/BOOTSTRAP-MINGW.cli
+++ b/BOOTSTRAP-MINGW.cli
@@ -3,7 +3,7 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-Continuing from \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 require a number of DLLs in order to run. It is therefore
 recommended that you copy the following files from your MinGW \c{bin\\}
@@ -52,7 +52,7 @@ 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
-\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:
 
 \
diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli
index 75af7d0..24255f5 100644
--- a/BOOTSTRAP-MSVC.cli
+++ b/BOOTSTRAP-MSVC.cli
@@ -3,7 +3,7 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-Continuing from \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
@@ -34,7 +34,7 @@ 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
-\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:
 
 \
diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
index bfa1e2a..5ede024 100644
--- a/BOOTSTRAP-UNIX.cli
+++ b/BOOTSTRAP-UNIX.cli
@@ -5,7 +5,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
+\l{#bootstrap-macosx Bootstrapping on Mac OS X}. These instructions should
 also be used for UNIX emulation layers on Windows (for example, MSYS or
 Cygwin) where you already have a UNIX shell with standard utilities.
 
@@ -93,7 +93,7 @@ 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
-\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:
 
 \
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
index 4058287..47085a1 100644
--- a/BOOTSTRAP-WINDOWS.cli
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -6,7 +6,7 @@
 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, MSYS or Cygwin) and already have a UNIX shell
-with standard utilities, then you most likely should follow \l{#BOOTSTRAP-UNIX
+with standard utilities, then you most likely should follow \l{#bootstrap-unix
 Bootstrapping on UNIX} instead.
 
 \N|Note that if you continue with these instructions but you already have your
@@ -142,9 +142,9 @@ directory:
 
 ||
 
-If building with MSVC, continue with \l{#BOOTSTRAP-MSVC Bootstrapping with
+If building with MSVC, continue with \l{#bootstrap-msvc Bootstrapping with
 MSVC}.
 
-If building with MinGW, continue with \l{#BOOTSTRAP-MINGW Bootstrapping with
+If building with MinGW, continue with \l{#bootstrap-mingw Bootstrapping with
 MinGW}.
 "
diff --git a/INSTALL.cli b/INSTALL.cli
index fc95a8f..1e61f92 100644
--- a/INSTALL.cli
+++ b/INSTALL.cli
@@ -6,7 +6,7 @@
 One of the primary goals of the \c{build2} toolchain is to provide a uniform
 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
+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
@@ -72,12 +72,12 @@ 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,
-then instead refer to \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}.
+\l{#bootstrap-windows Bootstrapping on Windows}. If using MSYS or Cygwin,
+then instead refer to \l{#bootstrap-unix Bootstrapping on UNIX}.
 
-For Mac OS X, continue with \l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}.
+For Mac OS X, continue with \l{#bootstrap-macosx Bootstrapping on Mac OS X}.
 
 For other UNIX-like operating systems (GNU/Linux, FreeBSD, etc; this also
-includes MSYS/Cygwin), continue with \l{#BOOTSTRAP-UNIX Bootstrapping on
+includes MSYS/Cygwin), continue with \l{#bootstrap-unix Bootstrapping on
 UNIX}.
 "
diff --git a/UPGRADE.cli b/UPGRADE.cli
index 964749c..baa00fa 100644
--- a/UPGRADE.cli
+++ b/UPGRADE.cli
@@ -28,9 +28,15 @@ 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.
 
-\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.|
+\N|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.|
+
+\N|The below upgrade process does not cover upgrading the \c{baseutils} and
+\c{mingw} packages on Windows (see \l{#bootstrap-windows Bootstrapping on
+Windows} for details). We recommend using the bootstrap process to upgrade
+these packages since all the straightforward upgrade sequences would lead to
+either the old toolchain using the new utilities or vice versa.|
 
 The dirty upgrade is straightforward:
 
diff --git a/doc/cli.sh b/doc/cli.sh
index 05faa4d..316e14b 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -61,7 +61,7 @@ gen install --html-heading-map 2=h2
 #
 function gen_txt () # <name>
 {
-  cli --generate-txt --omit-link-check --link-regex '%#(.*)%\1 file%' \
+  cli --generate-txt --omit-link-check --link-regex '%#(.*)%\U\1\E file%' \
 -o .. --txt-suffix "" ../$1.cli
 }
 
diff --git a/doc/install.cli b/doc/install.cli
index ec14af1..b84ddf3 100644
--- a/doc/install.cli
+++ b/doc/install.cli
@@ -14,8 +14,8 @@
 "
 \h0#preface|Preface|
 
-The recommended way to install the \c{build2} toolchain in most circumstances
-is using the automated install scripts as described on the
+The recommended way to install and upgrade the \c{build2} toolchain in most
+circumstances is using the automated install scripts as described on the
 \l{https://build2.org/install.xhtml Install} page. This document describes the
 manual installation and upgrade process which offers greater control can be
 helpful in situations where the automated scripts cannot be used (offline
@@ -23,37 +23,40 @@ installation, packaging for system package managers, unsupported
 platform/compiler, etc).
 "
 
+// NOTE: The following ids must correspond to the file names (used in
+// plain-text links).
+
 "
-\h#INSTALL|Introduction|
+\h#install|Introduction|
 "
 source "../INSTALL.cli";
 
 "
-\h#BOOTSTRAP-WINDOWS|Bootstrapping on Windows|
+\h#bootstrap-windows|Bootstrapping on Windows|
 "
 source "../BOOTSTRAP-WINDOWS.cli";
 
 "
-\h2#BOOTSTRAP-MSVC|Bootstrapping with MSVC|
+\h2#bootstrap-msvc|Bootstrapping with MSVC|
 "
 source "../BOOTSTRAP-MSVC.cli";
 
 "
-\h2#BOOTSTRAP-MINGW|Bootstrapping with MinGW|
+\h2#bootstrap-mingw|Bootstrapping with MinGW|
 "
 source "../BOOTSTRAP-MINGW.cli";
 
 "
-\h#BOOTSTRAP-MACOSX|Bootstrapping on Mac OS X|
+\h#bootstrap-macosx|Bootstrapping on Mac OS X|
 "
 source "../BOOTSTRAP-MACOSX.cli";
 
 "
-\h#BOOTSTRAP-UNIX|Bootstrapping on UNIX|
+\h#bootstrap-unix|Bootstrapping on UNIX|
 "
 source "../BOOTSTRAP-UNIX.cli";
 
 "
-\h#UPGRADE|Upgrading|
+\h#upgrade|Upgrading|
 "
 source "../UPGRADE.cli";