05/06: doc: Document the graphical installer some more.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit e1c15e8b8e25e14c253ff1212e289565736f6ea7
Author: Ludovic Courtès <address@hidden>
Date:   Wed Mar 13 21:57:14 2019 +0100

    doc: Document the graphical installer some more.
    
    * doc/guix.texi (Preparing for Installation): Rewrite to specify the two
    installation modes.
    (Guided Graphical Installation): New node.
    (Manual Installation): New node, with the former sections.
    (After System Installation): New node.
    * doc/images/installer-network.png, doc/images/installer-partitions.png,
    doc/images/installer-resume.png: New files.
    * doc/local.mk (dist_infoimage_DATA): Add them.
---
 doc/guix.texi                       | 121 +++++++++++++++++++++++++++---------
 doc/images/installer-network.png    | Bin 0 -> 24342 bytes
 doc/images/installer-partitions.png | Bin 0 -> 55847 bytes
 doc/images/installer-resume.png     | Bin 0 -> 35829 bytes
 doc/local.mk                        |   7 ++-
 5 files changed, 98 insertions(+), 30 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1b2ef37..043aad1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -165,10 +165,17 @@ System Installation
 * Hardware Considerations::     Supported hardware.
 * USB Stick and DVD Installation::  Preparing the installation medium.
 * Preparing for Installation::  Networking, partitioning, etc.
-* Proceeding with the Installation::  The real thing.
+* Guided Graphical Installation::  Easy graphical installation.
+* Manual Installation::         Manual installation for wizards.
+* After System Installation::   When installation succeeded.
 * Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 
+Manual Installation
+
+* Keyboard Layout and Networking and Partitioning:: Initial setup.
+* Proceeding with the Installation::  Installing.
+
 Package Management
 
 * Features::                    How Guix will make your life brighter.
@@ -1777,7 +1784,9 @@ available.
 * Hardware Considerations::     Supported hardware.
 * USB Stick and DVD Installation::  Preparing the installation medium.
 * Preparing for Installation::  Networking, partitioning, etc.
-* Proceeding with the Installation::  The real thing.
+* Guided Graphical Installation::  Easy graphical installation.
+* Manual Installation::         Manual installation for wizards.
+* After System Installation::   When installation succeeded.
 * Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 @end menu
@@ -1963,21 +1972,19 @@ Guix System in a virtual machine (VM).
 @node Preparing for Installation
 @section Preparing for Installation
 
-Once you have successfully booted your computer using the installation medium,
-you should end up with the welcome page of the graphical installer.  The
-graphical installer is a text-based user interface built upon the newt
-library.  It shall guide you through all the different steps needed to install
address@hidden System.  However, as the graphical installer is still under heavy
-development, you might want to fallback to the original, shell based install
-process, by switching to TTYs 3 to 6 with the shortcuts CTRL-ALT-F[3-6]. The
-following sections describe the installation procedure assuming you're using
-one of those TTYs. They are configured and can be used to run commands as
-root.
+Once you have booted, you can use the guided graphical installer, which makes
+it easy to get started (@pxref{Guided Graphical Installation}).  Alternately,
+if you are already familiar with GNU/Linux and if you want more control than
+what the graphical installer provides, you can choose the ``manual''
+installation process (@pxref{Manual Installation}).
 
-TTY2 shows this documentation, browsable using the Info reader commands
-(@pxref{Top,,, info-stnd, Stand-alone GNU Info}).  The installation system
-runs the GPM mouse daemon, which allows you to select text with the left mouse
-button and to paste it with the middle button.
+The graphical installer is available on TTY1.  You can obtain root shells on
+TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc.  TTY2 shows
+this documentation and you can reach it with @kbd{ctrl-alt-f2}.  Documentation
+is browsable using the Info reader commands (@pxref{Top,,, info-stnd,
+Stand-alone GNU Info}).  The installation system runs the GPM mouse daemon,
+which allows you to select text with the left mouse button and to paste it
+with the middle button.
 
 @quotation Note
 Installation requires access to the Internet so that any missing
@@ -1985,12 +1992,65 @@ dependencies of your system configuration can be 
downloaded.  See the
 ``Networking'' section below.
 @end quotation
 
-The installation system includes many common tools needed for this task.
-But it is also a full-blown Guix System, which means that you can
-install additional packages, should you need it, using @command{guix
-package} (@pxref{Invoking guix package}).
address@hidden Guided Graphical Installation
address@hidden Guided Graphical Installation
+
+The graphical installer is a text-based user interface.  It will guide you,
+with dialog boxes, through the steps needed to install address@hidden System.
+
+The first dialog boxes allow you to set up the system as you use it during the
+installation: you can choose the language, keyboard layout, and set up
+networking, which will be used during the installation.  The image below shows
+the networking dialog.
+
address@hidden/installer-network,5in,, networking setup with the graphical 
installer}
+
+Later steps allow you to partition your hard disk, as shown in the image
+below, to choose whether or not to use encrypted file systems, to enter the
+host name and root password, and to create an additional account, among other
+things.
+
address@hidden/installer-partitions,5in,, partitioning with the graphical 
installer}
+
+Note that, at any time, the installer allows you to exit the current
+installation step and resume at a previous step, as show in the image below.
+
address@hidden/installer-resume,5in,, resuming the installation process}
+
+Once you're done, the installer produces an operating system configuration and
+displays it (@pxref{Using the Configuration System}).  At that point you can
+hit ``OK'' and installation will proceed.  On success, you can reboot into the
+new system and enjoy.  @xref{After System Installation}, for what's next!
+
 
address@hidden Keyboard Layout
address@hidden Manual Installation
address@hidden Manual Installation
+
+This section describes how you would ``manually'' install address@hidden System
+on your machine.  This option requires familiarity with GNU/Linux, with the
+shell, and with common administration tools.  If you think this is not for
+you, consider using the guided graphical installer (@pxref{Guided Graphical
+Installation}).
+
+The installation system provides root shells on TTYs 3 to 6; press
address@hidden, @kbd{ctrl-alt-f4}, and so on to reach them.  It includes
+many common tools needed to install the system.  But it is also a full-blown
+Guix System, which means that you can install additional packages, should you
+need it, using @command{guix package} (@pxref{Invoking guix package}).
+
address@hidden
+* Keyboard Layout and Networking and Partitioning:: Initial setup.
+* Proceeding with the Installation::  Installing.
address@hidden menu
+
address@hidden Keyboard Layout and Networking and Partitioning
address@hidden Keyboard Layout, Networking, and Partitioning
+
+Before you can install the system, you may want to adjust the keyboard layout,
+set up networking, and partition your target hard disk.  This section will
+guide you through this.
+
address@hidden Keyboard Layout
 
 @cindex keyboard layout
 The installation image uses the US qwerty keyboard layout.  If you want
@@ -2005,7 +2065,7 @@ See the files under 
@file{/run/current-system/profile/share/keymaps} for
 a list of available keyboard layouts.  Run @command{man loadkeys} for
 more information.
 
address@hidden Networking
address@hidden Networking
 
 Run the following command to see what your network interfaces are called:
 
@@ -2098,7 +2158,7 @@ herd start ssh-daemon
 Make sure to either set a password with @command{passwd}, or configure
 OpenSSH public key authentication before logging in.
 
address@hidden Disk Partitioning
address@hidden Disk Partitioning
 
 Unless this has already been done, the next step is to partition, and
 then format the target partition(s).
@@ -2219,7 +2279,7 @@ file in its file system as described above, then the 
encryption also
 protects the swap file, just like any other file in that file system.
 
 @node Proceeding with the Installation
address@hidden Proceeding with the Installation
address@hidden Proceeding with the Installation
 
 With the target partitions ready and the target root mounted on
 @file{/mnt}, we're ready to go.  First, run:
@@ -2303,9 +2363,14 @@ in the new system is initially empty; other users' 
passwords need to be
 initialized by running the @command{passwd} command as @code{root},
 unless your configuration specifies otherwise
 (@pxref{user-account-password, user account passwords}).
address@hidden System Installation}, for what's next!
+
 
address@hidden upgrading Guix System
-From then on, you can update the system whenever you want by running, say:
address@hidden After System Installation
address@hidden After System Installation
+
+Success, you've now booted into Guix System!  From then on, you can update the
+system whenever you want by running, say:
 
 @example
 guix pull
@@ -2326,8 +2391,8 @@ explicitly run root's @command{guix}, type @command{sudo 
-i guix @dots{}}.
 @end quotation
 
 Join us on @code{#guix} on the Freenode IRC network or on
address@hidden@@gnu.org} to share your experience---good or not so
-good.
address@hidden@@gnu.org} to share your experience!
+
 
 @node Installing Guix in a VM
 @section Installing Guix in a Virtual Machine
diff --git a/doc/images/installer-network.png b/doc/images/installer-network.png
new file mode 100644
index 0000000..bd72f7f
Binary files /dev/null and b/doc/images/installer-network.png differ
diff --git a/doc/images/installer-partitions.png 
b/doc/images/installer-partitions.png
new file mode 100644
index 0000000..2632e9a
Binary files /dev/null and b/doc/images/installer-partitions.png differ
diff --git a/doc/images/installer-resume.png b/doc/images/installer-resume.png
new file mode 100644
index 0000000..db10169
Binary files /dev/null and b/doc/images/installer-resume.png differ
diff --git a/doc/local.mk b/doc/local.mk
index adb7b51..18115fb 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -1,6 +1,6 @@
 # GNU Guix --- Functional package management for GNU
 # Copyright © 2016 Eric Bavier <address@hidden>
-# Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018 Ludovic Courtès 
<address@hidden>
+# Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès 
<address@hidden>
 # Copyright © 2013 Andreas Enge <address@hidden>
 # Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <address@hidden>
 # Copyright © 2016, 2018 Mathieu Lirzin <address@hidden>
@@ -111,7 +111,10 @@ $(srcdir)/%D%/contributing.%.texi: po/doc/guix-manual.%.po
 infoimagedir = $(infodir)/images
 dist_infoimage_DATA =                          \
   $(DOT_FILES:%.dot=%.png)                     \
-  %D%/images/coreutils-size-map.png
+  %D%/images/coreutils-size-map.png            \
+  %D%/images/installer-network.png             \
+  %D%/images/installer-partitions.png          \
+  %D%/images/installer-resume.png
 
 # Try hard to obtain an image size and aspect that's reasonable for inclusion
 # in an Info or PDF document.