From 39ea3597690e1ece9e0d1f23e8ff200674e2a406 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 7 Dec 2018 14:15:19 +0200 Subject: Minor install/upgrade documentation improvements --- BOOTSTRAP-MACOSX.cli | 2 +- BOOTSTRAP-MINGW.cli | 4 ++-- BOOTSTRAP-MSVC.cli | 4 ++-- BOOTSTRAP-UNIX.cli | 4 ++-- BOOTSTRAP-WINDOWS.cli | 6 +++--- INSTALL.cli | 10 +++++----- UPGRADE.cli | 12 +++++++++--- doc/cli.sh | 2 +- doc/install.cli | 21 ++++++++++++--------- 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 () # { - 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"; -- cgit v1.1