[bug#69302] [PATCH 1/2] doc: Add “Getting Started with the System” section.

["Ludovic Courtès" <ludo@gnu.org>]

* doc/guix.texi (Getting Started with the System): New node.
(After System Installation): Refer to it.  Remove note about ‘sudo guix
pull’.
(Getting Started): Refer to it.  Remove note about ‘guix system roll-back’.
(Features): Refer to it.
(Using the Configuration System): Adjust intro.  Add “Troubleshooting”
note that mentions ‘guix style -f’ for misplaced parens.
(Instantiating the System): Simplify and cross-reference “Getting
Started with the System”.

Change-Id: Ie74f598450e8059a4579a016e2aeca2edd7696a7
---
 doc/guix.texi | 310 +++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 234 insertions(+), 76 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 9966a8e697..e7f59c8bfd 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -357,6 +357,7 @@ Top
 
 System Configuration
 
+* Getting Started with the System:: Your first steps.
 * Using the Configuration System::  Customizing your GNU system.
 * operating-system Reference::  Detail of operating-system declarations.
 * File Systems::                Configuring file system mounts.
@@ -2875,8 +2876,8 @@ Proceeding with the Installation
 @node After System Installation
 @section 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:
+Success, you've now booted into Guix System!  You can upgrade the system
+whenever you want by running:
 
 @example
 guix pull
@@ -2884,24 +2885,10 @@ After System Installation
 @end example
 
 @noindent
-This builds a new system generation with the latest packages and services
-(@pxref{Invoking guix system}).  We recommend doing that regularly so that
-your system includes the latest security updates (@pxref{Security Updates}).
+This builds a new system @dfn{generation} with the latest packages and
+services.
 
-@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
-@quotation Note
-@cindex sudo vs. @command{guix pull}
-Note that @command{sudo guix} runs your user's @command{guix} command and
-@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged.  To
-explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
-
-The difference matters here, because @command{guix pull} updates
-the @command{guix} command and package definitions only for the user it is run
-as.  This means that if you choose to use @command{guix system reconfigure} in
-root's login shell, you'll need to @command{guix pull} separately.
-@end quotation
-
-Now, @pxref{Getting Started}, and
+Now, @pxref{Getting Started with the System}, and
 join us on @code{#guix} on the Libera Chat IRC network or on
 @email{guix-devel@@gnu.org} to share your experience!
 
@@ -3155,22 +3142,9 @@ Getting Started
 @end example
 
 Upon completion, the system runs the latest versions of its software
-packages.  When you eventually reboot, you'll notice a sub-menu in the
-bootloader that reads ``Old system generations'': it's what allows you
-to boot @emph{an older generation of your system}, should the latest
-generation be ``broken'' or otherwise unsatisfying.  Just like for
-packages, you can always @emph{roll back} to a previous generation
-@emph{of the whole system}:
-
-@example
-sudo guix system roll-back
-@end example
-
-There are many things you'll probably want to tweak on your system:
-adding new user accounts, adding new system services, fiddling with the
-configuration of those services, etc.  The system configuration is
-@emph{entirely} described in the @file{/etc/config.scm} file.
-@xref{Using the Configuration System}, to learn how to change it.
+packages.  Just like for packages, you can always @emph{roll back} to a
+previous generation @emph{of the whole system}.  @xref{Getting Started
+with the System}, to learn how to manage your system.
 
 Now you know enough to get started!
 
@@ -3279,7 +3253,7 @@ Features
 of their profile, which was known to work well.  Similarly, the global
 system configuration on Guix is subject to
 transactional upgrades and roll-back
-(@pxref{Using the Configuration System}).
+(@pxref{Getting Started with the System}).
 
 All packages in the package store may be @emph{garbage-collected}.
 Guix can determine which packages are still referenced by user
@@ -17088,6 +17062,7 @@ System Configuration
 instance to support new system services.
 
 @menu
+* Getting Started with the System:: Your first steps.
 * Using the Configuration System::  Customizing your GNU system.
 * operating-system Reference::  Detail of operating-system declarations.
 * File Systems::                Configuring file system mounts.
@@ -17108,14 +17083,212 @@ System Configuration
 * Defining Services::           Adding new service definitions.
 @end menu
 
+@node Getting Started with the System
+@section Getting Started
+
+@cindex system configuration file
+@cindex configuration file, of the system
+You're reading this section probably because you have just installed
+Guix System (@pxref{System Installation}) and would like to know where
+to go from here.  If you're already familiar with GNU/Linux system
+administration, the way Guix System is configured is very different from
+what you're used to: you won't install a system service by running
+@command{guix install}, you won't configure services by modifying files
+under @file{/etc}, and you won't create user accounts by invoking
+@command{useradd}; instead, all these aspects are spelled out in a
+@dfn{system configuration file}.
+
+The first step with Guix System is thus to write the @dfn{system
+configuration file}; luckily, system installation already generated one
+for you and stored it under @file{/etc/config.scm}.
+
+@quotation Note
+You can store your system configuration file anywhere you like---it
+doesn't have to be at @file{/etc/config.scm}.  It's a good idea to keep
+it under version control, for instance in a Git repository.
+@end quotation
+
+The @emph{entire} configuration of the system---user accounts, system
+services, timezone, locale settings---is declared this file, which
+follows this template:
+
+@lisp
+(use-modules (gnu))
+(use-package-modules @dots{})
+(use-service-modules @dots{})
+
+(operating-system
+  (host-name @dots{})
+  (timezone @dots{})
+  (locale @dots{})
+  (bootloader @dots{})
+  (file-systems @dots{})
+  (users @dots{})
+  (packages @dots{})
+  (services @dots{}))
+@end lisp
+
+This configuration file is in fact a Scheme program; the first lines
+pull in modules providing variables you might need in the rest of the
+file---e.g., packages, services, etc.  The @code{operating-system} form
+declares the system configuration as a @dfn{record} with a number of
+@dfn{fields}.  @xref{Using the Configuration System}, to view complete
+examples and learn what to put in there.
+
+The second step, once you have this configuration file, is to test it.
+Of course, you can skip this step if you're feeling lucky---you choose!
+To do that, pass your configuration file to @command{guix system vm} (no
+need to be root, you can do that as a regular user):
+
+@example
+guix system vm /etc/config.scm
+@end example
+
+@noindent
+This command returns the name of a shell script that starts a virtual
+machine (VM) running the system @emph{as described in the configuration
+file}:
+
+@example
+/gnu/store/@dots{}-run-vm.sh
+@end example
+
+@noindent
+In this VM, you can log in as @code{root} with no password.  That's a
+good way to check that your configuration file is correct and that it
+gives the expected result, without touching your system.  @xref{Invoking
+guix system}, for more information.
+
+@cindex system instantiation
+@cindex reconfiguring the system
+The third step, once you're happy with your configuration, is to
+@dfn{instantiate} it---make this configuration effective on your system.
+To do that, run:
+
+@example
+sudo guix system reconfigure /etc/config.scm
+@end example
+
+@cindex upgrading system services
+@cindex system services, upgrading
+@noindent
+This operation is @dfn{transactional}: either it succeeds and you end up
+with an upgraded system, or it fails and nothing has changed.  Note that
+it does @emph{not} restart system services that were already running.
+Thus, to upgrade those services, you have to reboot or to explicitly
+restart them; for example, to restart the secure shell (SSH) daemon, you
+would run:
+
+@example
+sudo herd restart sshd
+@end example
+
+@quotation Note
+System services are managed by the Shepherd (@pxref{Jump Start,,,
+shepherd, The GNU Shepherd Manual}).  The @code{herd} command lets you
+inspect, start, and stop services.  To view the status of services, run:
+
+@example
+sudo herd status
+@end example
+
+To view detailed information about a given service, add its name to the
+command:
+
+@example
+sudo herd status sshd
+@end example
+
+@xref{Services}, for more information.
+@end quotation
+
+@cindex provenance, of the system
+The system records its @dfn{provenance}---the configuration file and
+channels that were used to deploy it.  You can view it like so:
+
+@example
+guix system describe
+@end example
+
+Additionally, @command{guix system reconfigure} preserves previous
+system generations, which you can list:
+
+@example
+guix system list-generations
+@end example
+
+@noindent
+@cindex roll back, for the system
+Crucially, that means that you can always @emph{roll back} to an earlier
+generation should something go wrong!  When you eventually reboot,
+you'll notice a sub-menu in the bootloader that reads ``Old system
+generations'': it's what allows you to boot @emph{an older generation of
+your system}, should the latest generation be ``broken'' or otherwise
+unsatisfying.  You can also ``permanently'' roll back, like so:
+
+@example
+sudo guix system roll-back
+@end example
+
+@noindent
+Alternatively, you can use @command{guix system switch-generation} to
+switch to a specific generation.
+
+Once in a while, you'll want to delete old generations that you do not
+need anymore to allow @dfn{garbage collection} to free space
+(@pxref{Invoking guix gc}).  For example, to remove generations older
+than 4 months, run:
+
+@example
+sudo guix system delete-generations 4m
+@end example
+
+From there on, anytime you want to change something in the system
+configuration, be it adding a user account or changing parameters of a
+service, you will first update your configuration file and then run
+@command{guix system reconfigure} as shown above.
+@cindex upgrade, of the system
+Likewise, to @emph{upgrade} system software, you first fetch an
+up-to-date Guix and then reconfigure your system with that new Guix:
+
+@example
+guix pull
+sudo guix system reconfigure /etc/config.scm
+@end example
+
+@noindent
+We recommend doing that regularly so that your system includes the
+latest security updates (@pxref{Security Updates}).
+
+@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
+@quotation Note
+@cindex sudo vs. @command{guix pull}
+@command{sudo guix} runs your user's @command{guix} command and
+@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged.
+
+The difference matters here, because @command{guix pull} updates
+the @command{guix} command and package definitions only for the user it is run
+as.  This means that if you choose to use @command{guix system reconfigure} in
+root's login shell, you'll need to @command{guix pull} separately.
+@end quotation
+
+That's it!  If you're getting starting with Guix entirely,
+@pxref{Getting Started}.  The next sections dive in more detail into the
+crux of the matter: system configuration.
+
 @node Using the Configuration System
 @section Using the Configuration System
 
+The previous section showed the overall workflow you would follow when
+administrating a Guix System machine (@pxref{Getting Started with the
+System}).  Let's now see in more detail what goes into the system
+configuration file.
+
 The operating system is configured by providing an
 @code{operating-system} declaration in a file that can then be passed to
-the @command{guix system} command (@pxref{Invoking guix system}).  A
-simple setup, with the default Linux-Libre
-kernel, initial RAM disk, and a couple of system services added to those
+the @command{guix system} command, as we've seen before (@pxref{Invoking
+guix system}).  A simple setup, with the default Linux-Libre kernel,
+initial RAM disk, and a couple of system services added to those
 provided by default looks like this:
 
 @findex operating-system
@@ -17123,8 +17296,8 @@ Using the Configuration System
 @include os-config-bare-bones.texi
 @end lisp
 
-The configuration is declarative and hopefully mostly self-describing.
-It is actually code in the Scheme programming language; the whole
+The configuration is declarative.
+It is code in the Scheme programming language; the whole
 @code{(operating-system @dots{})} expression produces a @dfn{record}
 with a number of @dfn{fields}.
 Some of the fields defined
@@ -17133,16 +17306,21 @@ Using the Configuration System
 which case they get a default value.  @xref{operating-system Reference},
 for details about all the available fields.
 
-Below we discuss the effect of some of the most important fields,
-and how to @dfn{instantiate} the operating system using
-@command{guix system}.
+Below we discuss the meaning of some of the most important fields.
 
-@quotation Do not panic
-@cindex Scheme programming language, getting started
-Intimidated by the Scheme language or curious about it?  The Cookbook
-has a short section to get started that explains the fundamentals, which
-you will find helpful when hacking your configuration.  @xref{A Scheme
-Crash Course,,, guix-cookbook, GNU Guix Cookbook}.
+@quotation Troubleshooting
+The configuration file is a Scheme program and you might get the syntax
+or semantics wrong as you get started.  Syntactic issues such as
+misplaced parentheses can often be identified by reformatting your file:
+
+@example
+guix style -f config.scm
+@end example
+
+The Cookbook has a short section to get started with the Scheme
+programming language that explains the fundamentals, which you will find
+helpful when hacking your configuration.  @xref{A Scheme Crash Course,,,
+guix-cookbook, GNU Guix Cookbook}.
 @end quotation
 
 @unnumberedsubsec Bootloader
@@ -17337,16 +17515,13 @@ Using the Configuration System
 
 @unnumberedsubsec Instantiating the System
 
+@cindex system instantiation
+@cindex reconfiguring the system
 Assuming the @code{operating-system} declaration
-is stored in the @file{my-system-config.scm}
-file, the @command{guix system reconfigure my-system-config.scm} command
-instantiates that configuration, and makes it the default GRUB boot
-entry (@pxref{Invoking guix system}).
-
-@quotation Note
-We recommend that you keep this @file{my-system-config.scm} file safe
-and under version control to easily track changes to your configuration.
-@end quotation
+is stored in the @file{config.scm}
+file, the @command{sudo guix system reconfigure config.scm} command
+instantiates that configuration, and makes it the default boot
+entry.  @xref{Getting Started with the System}, for an overview.
 
 The normal way to change the system configuration is by updating this
 file and re-running @command{guix system reconfigure}.  One should never
@@ -17356,23 +17531,6 @@ Using the Configuration System
 but also prevent you from rolling back to previous versions of your
 system, should you ever need to.
 
-@cindex roll-back, of the operating system
-Speaking of roll-back, each time you run @command{guix system
-reconfigure}, a new @dfn{generation} of the system is created---without
-modifying or deleting previous generations.  Old system generations get
-an entry in the bootloader boot menu, allowing you to boot them in case
-something went wrong with the latest generation.  Reassuring, no?  The
-@command{guix system list-generations} command lists the system
-generations available on disk.  It is also possible to roll back the
-system via the commands @command{guix system roll-back} and
-@command{guix system switch-generation}.
-
-Although the @command{guix system reconfigure} command will not modify
-previous generations, you must take care when the current generation is not
-the latest (e.g., after invoking @command{guix system roll-back}), since
-the operation might overwrite a later generation (@pxref{Invoking guix
-system}).
-
 @unnumberedsubsec The Programming Interface
 
 At the Scheme level, the bulk of an @code{operating-system} declaration
-- 
2.41.0