Document how to get binaries for Qbs

Move the section on how to build Qbs from sources to the end, and
instead start with how to get precompiled Qbs binaries. This is
arguably what most people prefer.

Change-Id: Ibbfc7e3fcb9994840ab5d647a4846b88278deac5
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
Reviewed-by: Jake Petroules <jake.petroules@qt.io>

4 files changed, 132 insertions, 21 deletions

diff --git a/doc/doc.qbs b/doc/doc.qbs
index ae9f0dbaf..1dba7dae9 100644
--- a/doc/doc.qbs
+++ b/doc/doc.qbs
@@ -9,6 +9,7 @@ Product {
     Depends { name: "qbsversion" }
 
     files: [
+        "external-resources.qdoc",
         "howtos.qdoc",
         "qbs.qdoc",
         "config/*.qdocconf",
diff --git a/doc/external-resources.qdoc b/doc/external-resources.qdoc
new file mode 100644
index 000000000..2e8ab0cbf
--- /dev/null
+++ b/doc/external-resources.qdoc
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \externalpage https://login.qt.io/
+    \title Qt Account
+*/
+
+/*!
+    \externalpage https://www.qt.io/ide/
+    \title Qt Creator
+*/
+
+/*!
+    \externalpage https://www.qt.io/download/
+    \title Qt SDK
+*/
+
+/*!
+    \externalpage https://chocolatey.org/packages/qbs
+    \title Chocolatey
+*/
+
+/*!
+    \externalpage https://www.macports.org/ports.php?by=name&substr=qbs
+    \title MacPorts
+*/
+
+/*!
+    \externalpage https://brew.sh/
+    \title Homebrew
+*/
+
+/*!
+    \externalpage nolink
+    \title macOS
+    \internal
+*/
diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index 3195ae80b..733eca941 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -56,8 +56,7 @@
        \li  \l{Introduction}
        \li  \l{Setup}
            \list
-               \li  \l{System Requirements}
-               \li  \l{Building}
+               \li  \l{Installing}
                \li  \l{Configuring}
                \li  \l{Managing Qt Versions}
            \endlist
@@ -73,6 +72,7 @@
            \endlist
        \li  \l{How-tos}
        \li  \l{Reference}
+       \li  \l{Appendix A: Building Qbs}
     \endlist
 */
 
@@ -96,39 +96,29 @@
     \contentspage index.html
     \previouspage overview.html
     \page setup.html
-    \nextpage system-requirements.html
+    \nextpage installing.html
 
     \title Setup
 
     \list
-        \li  \l{System Requirements}
-        \li  \l{Building}
+        \li  \l{Installing}
         \li  \l{Configuring}
         \li  \l{Managing Qt Versions}
     \endlist
 */
 
-
 /*!
     \contentspage index.html
-    \previouspage setup.html
-    \page system-requirements.html
-    \nextpage building.html
-
-    \title System Requirements
-
-    To build \QBS from the source, you need Qt 5.6.0, or later
+    \previouspage reference.html
+    \page building-qbs.html
 
-*/
+    \title Appendix A: Building Qbs
 
+    \section1 System Requirements
 
-/*!
-    \contentspage index.html
-    \previouspage system-requirements.html
-    \page building.html
-    \nextpage configuring.html
+    To build \QBS from the source, you need Qt 5.6.0, or later
 
-    \title Building
+    \section1 Building
 
     To build \QBS, enter the following command:
 
@@ -157,7 +147,64 @@
 
 /*!
     \contentspage index.html
-    \previouspage building.html
+    \previouspage setup.html
+    \page installing.html
+    \nextpage configuring.html
+
+    \title Installing
+
+    \QBS binaries are available for Windows, macOS, Linux, and FreeBSD.
+
+    On all platforms, \QBS binaries are part of the \l{Qt Creator} and \l{Qt SDK}
+    installers. You can find the \c qbs executable in the \c bin directory of
+    Qt Creator, or within the application bundle's \c MacOS directory on macOS.
+
+    \QBS can also be built locally from sources. For more information, see
+    \l{Appendix A: Building Qbs}.
+
+    \section1 Windows
+
+    The Qt Project provides prebuilt binaries for Windows (x86 and x64) at
+    \l{https://download.qt.io/official_releases/qbs/}. For commercial customers of
+    The Qt Company, the binaries are available in the \l {Qt Account}.
+    The binaries are packaged in a .zip folder that can be extracted to a location
+    of your choice.
+
+    \QBS is also available as a \l Chocolatey package, which can be installed in
+    the usual way:
+
+    \code
+    choco install qbs
+    \endcode
+
+    The \c .nupkg file can also be downloaded directly from
+    \l{https://download.qt.io/official_releases/qbs/} for
+    \l{https://chocolatey.org/security#organizational-use-of-chocolatey}{offline installation}.
+
+    \section1 macOS
+
+    \QBS can be conveniently installed on macOS with the \l{MacPorts} or \l{Homebrew}
+    package managers:
+
+    \code
+    brew install qbs
+    \endcode
+
+    or
+
+    \code
+    port install qbs
+    \endcode
+
+    \section1 Linux and FreeBSD
+
+    \QBS is \l{https://repology.org/metapackage/qbs/versions}{available via the
+    package management systems} of Linux distributions, and FreeBSD.
+*/
+
+/*!
+    \contentspage index.html
+    \previouspage installing.html
     \page configuring.html
     \nextpage qt-versions.html
 
diff --git a/doc/reference/reference.qdoc b/doc/reference/reference.qdoc
index 5677b6844..f6222601b 100644
--- a/doc/reference/reference.qdoc
+++ b/doc/reference/reference.qdoc
@@ -28,6 +28,7 @@
     \contentspage index.html
     \previouspage howtos.html
     \page reference.html
+    \nextpage building-qbs.html
 
     \title Reference