doc: Add "Hardware Considerations" node.

Suggested by Nils Gillmann <niasterisk@grrlz.net>.

* doc/guix.texi (Hardware Considerations): New node.
(operating-system Reference): Mention it.

1 files changed, 57 insertions, 6 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index c016eaf3c9..b3ba5ce4fb 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -154,6 +154,12 @@ Utilities
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix container::     Process isolation.
 
+Invoking @command{guix build}
+
+* Common Build Options::        Build options for most commands.
+* Package Transformation Options::    Creating variants of packages.
+* Additional Build Options::    Options specific to 'guix build'.
+
 GNU Distribution
 
 * System Installation::         Installing the whole operating system.
@@ -165,6 +171,15 @@ GNU Distribution
 * Bootstrapping::               GNU/Linux built from scratch.
 * Porting::                     Targeting another platform or kernel.
 
+System Installation
+
+* Limitations::                 What you can expect.
+* Hardware Considerations::     Supported hardware.
+* USB Stick Installation::      Preparing the installation medium.
+* Preparing for Installation::  Networking, partitioning, etc.
+* Proceeding with the Installation::  The real thing.
+* Building the Installation Image::  How this comes to be.
+
 System Configuration
 
 * Using the Configuration System::  Customizing your GNU system.
@@ -5657,11 +5672,12 @@ link that follows: @pxref{Help,,, info, Info: An Introduction}.  Hit
 @end ifinfo
 
 @menu
-* Limitations::                         What you can expect.
-* USB Stick Installation::              Preparing the installation medium.
-* Preparing for Installation::          Networking, partitioning, etc.
-* Proceeding with the Installation::    The real thing.
-* Building the Installation Image::     How this comes to be.
+* Limitations::                 What you can expect.
+* Hardware Considerations::     Supported hardware.
+* USB Stick Installation::      Preparing the installation medium.
+* Preparing for Installation::  Networking, partitioning, etc.
+* Proceeding with the Installation::  The real thing.
+* Building the Installation Image::  How this comes to be.
 @end menu
 
 @node Limitations
@@ -5707,6 +5723,40 @@ You have been warned!  But more than a disclaimer, this is an invitation
 to report issues (and success stories!), and to join us in improving it.
 @xref{Contributing}, for more info.
 
+
+@node Hardware Considerations
+@subsection Hardware Considerations
+
+@cindex hardware support on GuixSD
+GNU@tie{}GuixSD focuses on respecting the user's computing freedom.  It
+builds around the kernel Linux-libre, which means that only hardware for
+which free software drivers and firmware exists is supported.  Nowadays,
+a wide range of off-the-shelf hardware is supported on
+GNU/Linux-libre---from keyboards to graphics cards to scanners and
+Ethernet controllers.  Unfortunately, there are still areas where
+hardware vendors deny users control over their own computing, and such
+hardware is not supported on GuixSD.
+
+@cindex WiFi, hardware support
+One of the main areas where free drivers or firmware is lacking is WiFi
+devices.  WiFi devices known to work include those using Atheros chips
+(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
+driver, and for which free firmware exists and is available
+out-of-the-box on GuixSD, as part of @var{%base-firmware}
+(@pxref{operating-system Reference, @code{firmware}}).
+
+@cindex RYF, Respects Your Freedom
+The @uref{https://www.fsf.org/, Free Software Foundation} runs
+@uref{https://www.fsf.org/ryf, @dfn{Respect Your Freedom}} (RYF), a
+certification program for hardware products that respect your freedom
+and your privacy and ensure that you have control over your device.  We
+encourage you to check the list of RYF-certified hardware.
+
+Another useful resource is the @uref{https://www.h-node.org/, H-Node}
+web site.  It contains a catalog of hardware devices with information
+about their support in GNU/Linux.
+
+
 @node USB Stick Installation
 @subsection USB Stick Installation
 
@@ -6235,7 +6285,8 @@ the Linux kernel.  @xref{Initial RAM Disk}.
 List of firmware packages loadable by the operating system kernel.
 
 The default includes firmware needed for Atheros-based WiFi devices
-(Linux-libre module @code{ath9k}.)
+(Linux-libre module @code{ath9k}).  @xref{Hardware Considerations}, for
+more info on supported hardware.
 
 @item @code{host-name}
 The host name.