bug#59746: [DOCUMENTATION] [PATCH] doc: Introduce using Swap Space for hibernation, with an example.

[Ludovic Courtès]

Hi,

Ivan Vilata i Balaguer <ivan@selidor.net> skribis:

> This patch replaces the previous one and enhances it with several minor fixes
> and the missing information related to computing the swap file offset, as
> discussed [in the guix-devel thread][1].
>
> [1]: https://lists.gnu.org/archive/html/guix-devel/2022-12/msg00028.html
>
> Thanks and cheers!
>
> -- 
> Ivan Vilata i Balaguer -- https://elvil.net/
>
> From e95d79ef8c466e495c730f722b7aefc4d2d5969f Mon Sep 17 00:00:00 2001
> From: Ivan Vilata-i-Balaguer <ivan@selidor.net>
> Date: Wed, 21 Dec 2022 13:08:48 +0100
> Subject: [PATCH] doc: Introduce using swap space for hibernation, with
>  examples.
>
> * doc/guix.texi (Swap Space): Add a concise introduction to hibernation and
> specifying a swap space to the kernel to make resume work.  Mention space
> requirements and the need of an offset for swap files.  Include a trivial
> example on how to set up a mapped swap volume for hibernation and another one
> for a swap file, including how to compute the file offset.

Very nice!  Applied with the tweaks below.

Thanks,
Ludo’.

diff --git a/doc/guix.texi b/doc/guix.texi
index 9a74ae64d6..293c3016aa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -17109,14 +17109,18 @@ should consider ease of use when deciding between 
them.  Partitions are
 allocated at disk formatting time (logical volumes notwithstanding),
 whereas files can be allocated and deallocated at any time.
 
-A swap space is also required in order to hibernate a system using the
-Linux kernel.  Hibernation (also called suspend to disk) uses at most
-half the size of the RAM in the configured swap space.  The kernel needs
-to know about the swap space to be used to resume from hibernation on
-boot (via a kernel argument).  When using a swap file, its offset in the
-device holding it also needs to be given to the kernel, but that value
-has to be updated if the file is initialized again as swap (e.g. because
-its size was changed).
+@cindex hibernation
+@cindex suspend to disk
+Swap space is also required to put the system into @dfn{hibernation}
+(also called @dfn{suspend to disk}), whereby memory is dumped to swap
+before shutdown so it can be restored when the machine is eventually
+restarted.  Hibernation uses at most half the size of the RAM in the
+configured swap space.  The Linux kernel needs to know about the swap
+space to be used to resume from hibernation on boot (@i{via} a kernel
+argument).  When using a swap file, its offset in the device holding it
+also needs to be given to the kernel; that value has to be updated if
+the file is initialized again as swap---e.g., because its size was
+changed.
 
 Note that swap space is not zeroed on shutdown, so sensitive data (such
 as passwords) may linger on it if it was paged out.  As such, you should
@@ -17215,7 +17219,7 @@ select the file system in an elegant fashion!
          %default-kernel-arguments))
 @end lisp
 
-The previous snippet of an @code{operating-system} declaration enables
+The above snippet of an @code{operating-system} declaration enables
 the mapped device @file{/dev/mapper/my-swap} (which may be part of an
 encrypted device) as swap space, and tells the kernel to use it for
 hibernation via the @code{resume} kernel argument