installer: Add comments and vertical space to the generated config.

* gnu/installer/parted.scm (user-partitions->configuration): Introduce
vertical space and a comment.
* gnu/installer/services.scm (G_): New macro.
(%system-services): Add comment for OpenSSH.
(system-services->configuration): Add vertical space and comments.
* gnu/installer/user.scm (users->configuration): Add comment.
* gnu/installer/steps.scm (format-configuration): Add comment.
(configuration->file): Expound leading comment.  Pass #:format-comment
to 'pretty-print-with-comments/splice'.

4 files changed, 64 insertions, 14 deletions

diff --git a/gnu/installer/parted.scm b/gnu/installer/parted.scm
index ba0a38fff8..d942a2f49b 100644
--- a/gnu/installer/parted.scm
+++ b/gnu/installer/parted.scm
@@ -1,6 +1,6 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2018, 2019 Mathieu Othacehe <m.othacehe@gmail.com>
-;;; Copyright © 2019, 2020 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2019, 2020, 2022 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2020 Tobias Geerinckx-Rice <me@tobias.gr>
 ;;;
 ;;; This file is part of GNU Guix.
@@ -38,6 +38,7 @@
                 #:select (%base-initrd-modules))
   #:use-module (guix build syscalls)
   #:use-module (guix build utils)
+  #:use-module (guix read-print)
   #:use-module (guix records)
   #:use-module (guix utils)
   #:use-module (guix i18n)
@@ -1443,6 +1444,13 @@ USER-PARTITIONS, or return nothing."
             `((mapped-devices
                (list ,@(map user-partition->mapped-device
                             encrypted-partitions)))))
+
+      ,(vertical-space 1)
+      ,(let-syntax ((G_ (syntax-rules () ((_ str) str))))
+         (comment (G_ "\
+;; The list of file systems that get \"mounted\".  The unique
+;; file system identifiers there (\"UUIDs\") can be obtained
+;; by running 'blkid' in a terminal.\n")))
       (file-systems (cons*
                      ,@(user-partitions->file-systems user-partitions)
                      %base-file-systems)))))
diff --git a/gnu/installer/services.scm b/gnu/installer/services.scm
index 6584fcceec..6c5f49622f 100644
--- a/gnu/installer/services.scm
+++ b/gnu/installer/services.scm
@@ -1,6 +1,6 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2018 Mathieu Othacehe <m.othacehe@gmail.com>
-;;; Copyright © 2019 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2019, 2022 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2020 Jan (janneke) Nieuwenhuizen <janneke@gnu.org>
 ;;; Copyright © 2021 Tobias Geerinckx-Rice <me@tobias.gr>
 ;;; Copyright © 2021 Leo Famulari <leo@famulari.name>
@@ -22,6 +22,7 @@
 
 (define-module (gnu installer services)
   #:use-module (guix records)
+  #:use-module (guix read-print)
   #:use-module (srfi srfi-1)
   #:export (system-service?
             system-service-name
@@ -35,6 +36,11 @@
             %system-services
             system-services->configuration))
 
+(define-syntax-rule (G_ str)
+  ;; In this file, translatable strings are annotated with 'G_' so xgettext
+  ;; catches them, but translation happens later on at run time.
+  str)
+
 (define-record-type* <system-service>
   system-service make-system-service
   system-service?
@@ -52,9 +58,7 @@
                                       ((_ fields ...)
                                        (system-service
                                         (type 'desktop)
-                                        fields ...))))
-               (G_ (syntax-rules ()               ;for xgettext
-                     ((_ str) str))))
+                                        fields ...)))))
     (list
      ;; This is the list of desktop environments supported as services.
      (desktop-environment
@@ -94,7 +98,12 @@
      (system-service
       (name (G_ "OpenSSH secure shell daemon (sshd)"))
       (type 'networking)
-      (snippet '((service openssh-service-type))))
+      (snippet `(,(vertical-space 1)
+                 ,(comment
+                   (G_ "\
+;; To configure OpenSSH, pass an 'openssh-configuration'
+;; record as a second argument to 'service' below.\n"))
+                 (service openssh-service-type))))
      (system-service
       (name (G_ "Tor anonymous network router"))
       (type 'networking)
@@ -149,24 +158,38 @@
          (desktop? (find desktop-system-service? services))
          (base     (if desktop?
                        '%desktop-services
-                       '%base-services)))
+                       '%base-services))
+         (heading  (list (vertical-space 1)
+                         (comment (G_ "\
+;; Below is the list of system services.  To search for available
+;; services, run 'guix system search KEYWORD' in a terminal.\n")))))
+
     (if (null? snippets)
         `(,@(if (null? packages)
                 '()
                 `((packages (append (list ,@packages)
                                     %base-packages))))
+
+          ,@heading
           (services ,base))
         `(,@(if (null? packages)
                 '()
                 `((packages (append (list ,@packages)
                                     %base-packages))))
+
+          ,@heading
           (services (append (list ,@snippets
 
                                   ,@(if desktop?
                                         ;; XXX: Assume 'keyboard-layout' is in
                                         ;; scope.
-                                        '((set-xorg-configuration
+                                        `((set-xorg-configuration
                                            (xorg-configuration
                                             (keyboard-layout keyboard-layout))))
                                         '()))
-                           ,base))))))
+
+                            ,(vertical-space 1)
+                            ,(comment (G_ "\
+;; This is the default list of services we
+;; are appending to.\n"))
+                            ,base))))))
diff --git a/gnu/installer/steps.scm b/gnu/installer/steps.scm
index f1d61a2bc5..8b25ae97c8 100644
--- a/gnu/installer/steps.scm
+++ b/gnu/installer/steps.scm
@@ -224,10 +224,14 @@ found in RESULTS."
                   (conf-formatter result-step)
                   '())))
           steps))
-        (modules '((use-modules (gnu))
+        (modules `(,(vertical-space 1)
+                   ,(comment (G_ "\
+;; Indicate which modules to import to access the variables
+;; used in this configuration.\n"))
+                   (use-modules (gnu))
                    (use-service-modules cups desktop networking ssh xorg))))
     `(,@modules
-      ()
+      ,(vertical-space 1)
       (operating-system ,@configuration))))
 
 (define* (configuration->file configuration
@@ -241,11 +245,21 @@ found in RESULTS."
       ;; length below 60 characters.
       (display (G_ "\
 ;; This is an operating system configuration generated
-;; by the graphical installer.\n")
+;; by the graphical installer.
+;;
+;; Once installation is complete, you can learn and modify
+;; this file to tweak the system configuration, and pass it
+;; to the 'guix system reconfigure' command to effect your
+;; changes.\n")
                port)
       (newline port)
       (pretty-print-with-comments/splice port configuration
-                                         #:max-width 75)
+                                         #:max-width 75
+                                         #:format-comment
+                                         (lambda (c indent)
+                                           ;; Localize C.
+                                           (comment (G_ (comment->string c))
+                                                    (comment-margin? c))))
 
       (flush-output-port port))))
 
diff --git a/gnu/installer/user.scm b/gnu/installer/user.scm
index c894a91dc8..224040530c 100644
--- a/gnu/installer/user.scm
+++ b/gnu/installer/user.scm
@@ -18,6 +18,7 @@
 
 (define-module (gnu installer user)
   #:use-module (guix records)
+  #:use-module (guix read-print)
   #:use-module (srfi srfi-1)
   #:use-module (srfi srfi-9)
   #:use-module (srfi srfi-9 gnu)
@@ -69,7 +70,11 @@
       (supplementary-groups '("wheel" "netdev"
                               "audio" "video"))))
 
-  `((users (cons*
+  (define-syntax-rule (G_ str) str)
+
+  `(,(vertical-space 1)
+    ,(comment (G_ ";; The list of user accounts ('root' is implicit).\n"))
+    (users (cons*
             ,@(filter-map (lambda (user)
                             ;; Do not emit a 'user-account' form for "root".
                             (and (not (string=? (user-name user) "root"))