From 8e07eb474891662bee0a6d0bd4116c2371d41e7e Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 18 May 2018 16:41:36 +0200
Subject: Update documentation with new install procedure

---
 BOOTSTRAP-UNIX.cli    |  2 +-
 BOOTSTRAP-WINDOWS.cli |  6 +++---
 doc/install.cli       | 12 ++++++++++++
 doc/intro.cli         |  3 +--
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
index e7dbc8a..8c79922 100644
--- a/BOOTSTRAP-UNIX.cli
+++ b/BOOTSTRAP-UNIX.cli
@@ -30,7 +30,7 @@ $ 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}.
+\l{https://build2.org/download.xhtml Download} page.
 
 Place everything into \c{~/build2-build/} (build directory) and verify the
 archive checksum matches:
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
index c053573..ab47458 100644
--- a/BOOTSTRAP-WINDOWS.cli
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -66,9 +66,9 @@ you can use other paths.
 
 \li|\n\b{3. Download Archives}\n
 
-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-bit Windows and with \c{i686} for 32-bit:
+Download the following files as well as their \c{.sha256} checksums from the
+\l{https://build2.org/download.xhtml Download} page, replacing \i{<arch>} with
+\c{x86_64} for 64-bit Windows and with \c{i686} for 32-bit:
 
 \
 build2-baseutils-X.Y.Z-<arch>-windows.zip
diff --git a/doc/install.cli b/doc/install.cli
index 4885e24..4d241f4 100644
--- a/doc/install.cli
+++ b/doc/install.cli
@@ -12,6 +12,18 @@
 //
 
 "
+\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
+\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
+installation, packaging for system package managers, unsupported
+platform/compiler, etc).
+"
+
+"
 \h#INSTALL|Introduction|
 "
 source "../INSTALL.cli";
diff --git a/doc/intro.cli b/doc/intro.cli
index df62eaf..3487305 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -98,8 +98,7 @@ command output so if you just want to get a sense of what \c{build2} is about,
 then you don't have to install the toolchain and run the commands in order to
 follow along. If at the end you find \c{build2} appealing and would like to
 start using it or try the examples for yourself, you can jump straight to
-\l{build2-toolchain-install.xhtml The \c{build2} Toolchain Installation and
-Upgrade}.
+the \l{https://build2.org/install.xhtml Install} page.
 
 One of the primary goals of the \c{build2} toolchain is to provide a uniform
 interface across all the platforms and compilers. While the examples in this
-- 
cgit v1.1