diff mbox series

[bug#56145,2/5] doc: Add menus to Services sub-sections (part 2/2).

Message ID 201f3aa5e409f45423ec30187f37ee56cc0f7716.1655908912.git.h.goebel@crazy-compilers.com
State New
Headers show
Series Add menus to Services sub-sections | expand

Checks

Context Check Description
cbaines/comparison success View comparision
cbaines/git branch success View Git branch
cbaines/applying patch success View Laminar job
cbaines/issue success View issue

Commit Message

Hartmut Goebel June 22, 2022, 3:55 p.m. UTC
* doc/guix.texi (Services)[Base Services, Networking Setup, Networking
  Services, X Window, Printing Services, Desktop Services, Sound Services,
  LDAP, Certificate Services]: Structure section by adding headings for each
  service (in a broader snse fo service), ensure @anchors exist for each
  heading and create a @menu at the top of the section.
---
 doc/guix.texi | 428 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 423 insertions(+), 5 deletions(-)

Comments

Ludovic Courtès July 3, 2022, 10:38 a.m. UTC | #1
Hartmut Goebel <h.goebel@crazy-compilers.com> skribis:

> * doc/guix.texi (Services)[Base Services, Networking Setup, Networking
>   Services, X Window, Printing Services, Desktop Services, Sound Services,
>   LDAP, Certificate Services]: Structure section by adding headings for each
>   service (in a broader snse fo service), ensure @anchors exist for each
>   heading and create a @menu at the top of the section.

I’m less convinced about this one.  I wonder if, instead of adding
anchors, we should add proper sectioning at the same level as the
existing sections (“Base Services”, etc.).

Also, I don’t think we need one section (or anchor) per service:
mingetty, agetty, and kmscon typically belong in the same section;
likewise for urandom and rngd; udev, syslog, and nscd are arguably good
fits under “Base Services”.

WDYT?

> +* Services related to files::
> +* Hostname::

Typographic note: titles should be capitalized, and “host name” is two
words.  :-)

IWBN to have synopses after double colons like you did in the first
patch.

Ludo’.
diff mbox series

Patch

diff --git a/doc/guix.texi b/doc/guix.texi
index 58eb47535d..4db012d651 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -17267,6 +17267,25 @@  declaration.
 The @code{(gnu services base)} module provides definitions for the basic
 services that one expects from the system.  The services exported by
 this module are listed below.
+@menu
+* Services related to files::
+* Hostname::
+* Console::
+* Login::
+* mingetty::
+* agetty::
+* kmscon::
+* Name Service Cache Daemon::
+* Syslog::
+* Guix Build Daemon::
+* Guix Publish::
+* udev::
+* urandom::
+* gpm::
+* rngd::
+* PAM limits::
+* greetd::
+@end menu
 
 @defvr {Scheme Variable} %base-services
 This variable contains a list of basic services (@pxref{Service Types
@@ -17287,6 +17306,10 @@  this:
 @end lisp
 @end defvr
 
+
+@anchor{Services related to files}
+@subsubheading Services related to files
+
 @defvr {Scheme Variable} special-files-service-type
 This is the service that sets up ``special files'' such as
 @file{/bin/sh}; an instance of it is part of @code{%base-services}.
@@ -17331,10 +17354,18 @@  symlink:
 @end lisp
 @end deffn
 
+
+@anchor{Hostname}
+@subsubheading Hostname
+
 @deffn {Scheme Procedure} host-name-service @var{name}
 Return a service that sets the host name to @var{name}.
 @end deffn
 
+
+@anchor{Console}
+@subsubheading Console
+
 @defvr {Scheme Variable} console-font-service-type
 Install the given fonts on the specified ttys (fonts are per
 virtual console on the kernel Linux).  The value of this service is a list of
@@ -17352,6 +17383,10 @@  package or any valid argument to @command{setfont}, as in this example:
 @end lisp
 @end defvr
 
+
+@anchor{Login}
+@subsubheading Login
+
 @deffn {Scheme Procedure} login-service @var{config}
 Return a service to run login according to @var{config}, a
 @code{<login-configuration>} object, which specifies the message of the day,
@@ -17374,6 +17409,10 @@  the 'root' account has just been created.
 @end table
 @end deftp
 
+
+@anchor{mingetty}
+@subsubheading mingetty
+
 @deffn {Scheme Procedure} mingetty-service @var{config}
 Return a service to run mingetty according to @var{config}, a
 @code{<mingetty-configuration>} object, which specifies the tty to run, among
@@ -17412,6 +17451,10 @@  The Mingetty package to use.
 @end table
 @end deftp
 
+
+@anchor{agetty}
+@subsubheading agetty
+
 @deffn {Scheme Procedure} agetty-service @var{config}
 Return a service to run agetty according to @var{config}, an
 @code{<agetty-configuration>} object, which specifies the tty to run,
@@ -17595,6 +17638,10 @@  The option can be used to provides extra shepherd requirements (for example
 @end table
 @end deftp
 
+
+@anchor{kmscon}
+@subsubheading kmscon
+
 @deffn {Scheme Procedure} kmscon-service-type @var{config}
 Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
 according to @var{config}, a @code{<kmscon-configuration>} object, which
@@ -17644,6 +17691,9 @@  The Kmscon package to use.
 @end table
 @end deftp
 
+
+@anchor{Name Service Cache Daemon}
+@subsubheading Name Service Cache Daemon
 @cindex name service cache daemon
 @cindex nscd
 @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
@@ -17759,9 +17809,13 @@  privacy---often the result of host name lookups is in local cache, so
 external name servers do not even need to be queried.
 @end defvr
 
+
 @anchor{syslog-configuration-type}
+@anchor{Syslog}
+@subsubheading Syslog
 @cindex syslog
 @cindex logging
+
 @deftp {Data Type} syslog-configuration
 This data type represents the configuration of the syslog daemon.
 
@@ -17784,6 +17838,10 @@  Return a service that runs a syslog daemon according to @var{config}.
 information on the configuration file syntax.
 @end deffn
 
+
+@anchor{Guix Build Daemon}
+@subsubheading Guix Build Daemon
+
 @defvr {Scheme Variable} guix-service-type
 This is the type of the service that runs the build daemon,
 @command{guix-daemon} (@pxref{Invoking guix-daemon}).  Its value must be a
@@ -17939,6 +17997,10 @@  A list of file-like objects or strings pointing to additional directories the bu
 @end table
 @end deftp
 
+
+@anchor{udev}
+@subsubheading udev
+
 @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
 Run @var{udev}, which populates the @file{/dev} directory dynamically.
 udev rules can be provided as a list of files through the @var{rules}
@@ -18047,6 +18109,10 @@  well as in the @var{groups} of the @code{udev-rules-service} procedure.
           %desktop-services)))
 @end lisp
 
+
+@anchor{urandom}
+@subsubheading urandom
+
 @defvr {Scheme Variable} urandom-seed-service-type
 Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
 when rebooting.  It also tries to seed @file{/dev/urandom} from
@@ -18060,8 +18126,12 @@  This is the name of the file where some random bytes are saved by
 It defaults to @file{/var/lib/random-seed}.
 @end defvr
 
+
+@anchor{gpm}
+@subsubheading gpm
 @cindex mouse
 @cindex gpm
+
 @defvr {Scheme Variable} gpm-service-type
 This is the type of the service that runs GPM, the @dfn{general-purpose
 mouse daemon}, which provides mouse support to the Linux console.  GPM
@@ -18088,7 +18158,11 @@  The GPM package to use.
 @end table
 @end deftp
 
+
 @anchor{guix-publish-service-type}
+@anchor{Guix Publish}
+@subsubheading Guix Publish
+
 @deffn {Scheme Variable} guix-publish-service-type
 This is the service type for @command{guix publish} (@pxref{Invoking
 guix publish}).  Its value must be a @code{guix-publish-configuration}
@@ -18173,6 +18247,9 @@  seconds for the negative lookups.  @xref{Invoking guix publish,
 @end deftp
 
 @anchor{rngd-service}
+@anchor{rngd}
+@subsubheading rngd
+
 @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
             [#:device "/dev/hwrng"]
 Return a service that runs the @command{rngd} program from @var{rng-tools}
@@ -18180,7 +18257,10 @@  to add @var{device} to the kernel's entropy pool.  The service will fail if
 @var{device} does not exist.
 @end deffn
 
+
 @anchor{pam-limits-service}
+@anchor{PAM limits}
+@subsubheading PAM limits
 @cindex session limits
 @cindex ulimit
 @cindex priority
@@ -18228,6 +18308,10 @@  about the Pluggable Authentication Module (PAM) limits, refer to the
 @samp{pam_limits} man page from the @code{linux-pam} package.
 @end deffn
 
+
+@anchor{greetd}
+@subsubheading greetd
+
 @defvr {Scheme Variable} greetd-service-type
 @uref{https://git.sr.ht/~kennylevinsen/greetd, @code{greetd}} is a minimal and
 flexible login manager daemon, that makes no assumptions about what you
@@ -18686,6 +18770,20 @@  configuration or a simple DHCP client are often more appropriate.
 This section describes the various network setup services available,
 starting with static network configuration.
 
+@menu
+* Static Networking::
+* DHCP Client::
+* NetworkManager::
+* Connman::
+* WiFi / WPA::
+* ModemManager::
+* USB Modeswitch::
+@end menu
+
+
+@anchor{Static Networking}
+@subsubheading Static Networking
+
 @defvr {Scheme Variable} static-networking-service-type
 This is the type for statically-configured network interfaces.  Its
 value must be a list of @code{static-networking} records.  Each of them
@@ -18862,13 +18960,20 @@  when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using
 the user mode network stack,,, QEMU, QEMU Documentation}).
 @end defvr
 
+
+@anchor{DHCP Client}
+@subsubheading DHCP Client
 @cindex DHCP, networking service
+
 @defvr {Scheme Variable} dhcp-client-service-type
 This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
 Protocol (DHCP) client, on all the non-loopback network interfaces.  Its value
 is the DHCP client package to use, @code{isc-dhcp} by default.
 @end defvr
 
+
+@anchor{NetworkManager}
+@subsubheading NetworkManager
 @cindex NetworkManager
 
 @defvr {Scheme Variable} network-manager-service-type
@@ -18939,7 +19044,11 @@  package, which allows NetworkManager to manage VPNs @i{via} OpenVPN.
 @end table
 @end deftp
 
+
+@anchor{Connman}
+@subsubheading Connman
 @cindex Connman
+
 @deffn {Scheme Variable} connman-service-type
 This is the service type to run @url{https://01.org/connman,Connman},
 a network connection manager.
@@ -18968,7 +19077,11 @@  When true, disable connman's vpn plugin.
 @end table
 @end deftp
 
+
+@anchor{WiFi / WPA}
+@subsubheading WiFi / WPA
 @cindex WPA Supplicant
+
 @defvr {Scheme Variable} wpa-supplicant-service-type
 This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
 supplicant}, an authentication daemon required to authenticate against
@@ -19005,7 +19118,11 @@  List of additional command-line arguments to pass to the daemon.
 @end table
 @end deftp
 
+
+@anchor{ModemManager}
+@subsubheading ModemManager
 @cindex ModemManager
+
 Some networking devices such as modems require special care, and this is
 what the services below focus on.
 
@@ -19029,6 +19146,9 @@  The ModemManager package to use.
 @end table
 @end deftp
 
+
+@anchor{USB Modeswitch}
+@subsubheading USB Modeswitch
 @cindex USB_ModeSwitch
 @cindex Modeswitching
 
@@ -19079,6 +19199,38 @@  running a WiFi access point with @command{hostapd}, running the
 @command{inetd} ``superdaemon'', and more.  This section describes
 those.
 
+@menu
+* DHCP Server::
+* hostapd::
+* Simulate WiFi Networking::
+* iptables::
+* nftables::
+* ntpd::
+* OpenNTPD::
+* inetd::
+* OpenDHT::
+* Tor Anonymous Networking Daemon::
+* rsync Server::
+* syncthing::
+* SSH::
+* lsh::
+* OpenSSH::
+* Dropbear SSH Daemon::
+* AutoSSH::
+* WebSSH::
+* Facebook Host Aliases::
+* avahi::
+* Open vSwitch::
+* PageKite::
+* Yggdrasil::
+* IPFS network::
+* keepalived::
+@end menu
+
+@anchor{DHCP Server}
+@subsubheading DHCP Server
+@cindex DHCP
+
 @deffn {Scheme Procedure} dhcpd-service-type
 This type defines a service that runs a DHCP daemon.  To create a
 service of this type, you must supply a @code{<dhcpd-configuration>}.
@@ -19124,8 +19276,12 @@  interfaces here; see @code{man dhcpd} for details.
 @end table
 @end deftp
 
+
+@anchor{hostapd}
+@subsubheading hostapd
 @cindex hostapd service, for Wi-Fi access points
 @cindex Wi-Fi access points, hostapd service
+
 @defvr {Scheme Variable} hostapd-service-type
 This is the service type to run the @uref{https://w1.fi/hostapd/,
 hostapd} daemon to set up WiFi (IEEE 802.11) access points and
@@ -19175,6 +19331,11 @@  configuration file reference.
 @end table
 @end deftp
 
+
+@anchor{Simulate WiFi Networking}
+@subsubheading Simulate WiFi Networking
+@cindex WiFi
+
 @defvr {Scheme Variable} simulated-wifi-service-type
 This is the type of a service to simulate WiFi networking, which can be
 useful in virtual machines for testing purposes.  The service loads the
@@ -19187,7 +19348,10 @@  The service's value is a @code{hostapd-configuration} record.
 @end defvr
 
 
+@anchor{iptables}
+@subsubheading iptables
 @cindex iptables
+
 @defvr {Scheme Variable} iptables-service-type
 This is the service type to set up an iptables configuration.  iptables is a
 packet filtering framework supported by the Linux kernel.  This service
@@ -19237,7 +19401,11 @@  objects}).
 @end table
 @end deftp
 
+
+@anchor{nftables}
+@subsubheading nftables
 @cindex nftables
+
 @defvr {Scheme Variable} nftables-service-type
 This is the service type to set up a nftables configuration.  nftables is a
 netfilter project that aims to replace the existing iptables, ip6tables,
@@ -19264,9 +19432,13 @@  The nftables ruleset to use.  This may be any ``file-like'' object
 @end table
 @end deftp
 
+
+@anchor{ntpd}
+@subsubheading ntpd
 @cindex NTP (Network Time Protocol), service
 @cindex ntpd, service for the Network Time Protocol daemon
 @cindex real time clock
+
 @defvr {Scheme Variable} ntp-service-type
 This is the type of the service running the @uref{https://www.ntp.org,
 Network Time Protocol (NTP)} daemon, @command{ntpd}.  The daemon will keep the
@@ -19325,7 +19497,11 @@  to use with the options @option{iburst} and @option{prefer}, as well as
 @end table
 @end deftp
 
+
+@anchor{OpenNTPD}
+@subsubheading OpenNTPD
 @cindex OpenNTPD
+
 @deffn {Scheme Procedure} openntpd-service-type
 Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
 by @uref{http://www.openntpd.org, OpenNTPD}.  The daemon will keep the system
@@ -19379,7 +19555,11 @@  IP addresses, @code{ntpd} will calculate a median constraint from all of them.
 @end table
 @end deftp
 
+
+@anchor{inetd}
+@subsubheading inetd
 @cindex inetd
+
 @deffn {Scheme variable} inetd-service-type
 This service runs the @command{inetd} (@pxref{inetd invocation,,,
 inetutils, GNU Inetutils}) daemon.  @command{inetd} listens for
@@ -19472,8 +19652,12 @@  must be @code{'()} or @code{'("internal")}.
 detailed discussion of each configuration field.
 @end deftp
 
-@cindex opendht, distributed hash table network service
+
+@anchor{OpenDHT}
+@subsubheading OpenDHT
+@cindex OpenDHT, distributed hash table network service
 @cindex dhtproxy, for use with jami
+
 @defvr {Scheme Variable} opendht-service-type
 This is the type of the service running a @uref{https://opendht.net,
 OpenDHT} node, @command{dhtnode}.  The daemon can be used to host your
@@ -19566,7 +19750,11 @@  Defaults to @samp{disabled}.
 @end deftypevr
 @end deftp
 
+
+@anchor{Tor Anonymous Networking Daemon}
+@subsubheading Tor Anonymous Networking Daemon
 @cindex Tor
+
 @defvr {Scheme Variable} tor-service-type
 This is the type for a service that runs the @uref{https://torproject.org,
 Tor} anonymous networking daemon.  The service is configured using a
@@ -19641,6 +19829,10 @@  See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
 project's documentation} for more information.
 @end deffn
 
+@anchor{rsync Server}
+@subsubheading rsync Server
+@cindex rsync
+
 The @code{(gnu services rsync)} module provides the following services:
 
 You might want an rsync daemon if you have files that you want available
@@ -19746,6 +19938,11 @@  client.
 @end table
 @end deftp
 
+
+@anchor{syncthing}
+@subsubheading syncthing
+@cindex syncthing
+
 The @code{(gnu services syncthing)} module provides the following services:
 @cindex syncthing
 
@@ -19795,7 +19992,17 @@  directory is @file{$HOME} of the specified Syncthing @code{user}.
 @end deftp
 @end deffn
 
+
+@anchor{SSH}
+@subsubheading SSH
+@cindex SSH
+@cindex SSH server
+
 Furthermore, @code{(gnu services ssh)} provides the following services.
+
+
+@anchor{lsh}
+@subsubheading lsh
 @cindex SSH
 @cindex SSH server
 
@@ -19835,8 +20042,11 @@  root.
 The other options should be self-descriptive.
 @end deffn
 
+@anchor{OpenSSH}
+@subsubheading OpenSSH
 @cindex SSH
 @cindex SSH server
+
 @deffn {Scheme Variable} openssh-service-type
 This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
 shell daemon, @command{sshd}.  Its value must be an
@@ -20027,6 +20237,12 @@  Match Address 192.168.0.1
 @end table
 @end deftp
 
+
+@anchor{Dropbear SSH Daemon}
+@subsubheading Dropbear SSH Daemon
+@cindex SSH
+@cindex SSH server
+
 @deffn {Scheme Procedure} dropbear-service [@var{config}]
 Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
 daemon} with the given @var{config}, a @code{<dropbear-configuration>}
@@ -20068,7 +20284,11 @@  Whether to enable password-based authentication.
 @end table
 @end deftp
 
+
+@anchor{AutoSSH}
+@subsubheading AutoSSH
 @cindex AutoSSH
+
 @deffn {Scheme Variable} autossh-service-type
 This is the type for the @uref{https://www.harding.motd.ca/autossh,
 AutoSSH} program that runs a copy of @command{ssh} and monitors it,
@@ -20148,7 +20368,11 @@  may cause undefined behaviour.
 @end table
 @end deftp
 
+
+@anchor{WebSSH}
+@subsubheading WebSSH
 @cindex WebSSH
+
 @deffn {Scheme Variable} webssh-service-type
 This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
 program that runs a web SSH client.  WebSSH can be run manually from the
@@ -20223,6 +20447,10 @@  Logging level.
 @end table
 @end deftp
 
+
+@anchor{Facebook Host Aliases}
+@subsubheading Facebook Host Aliases
+
 @defvr {Scheme Variable} %facebook-host-aliases
 This variable contains a string for use in @file{/etc/hosts}
 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}).  Each
@@ -20252,6 +20480,10 @@  This mechanism can prevent programs running locally, such as Web
 browsers, from accessing Facebook.
 @end defvr
 
+
+@anchor{avahi}
+@subsubheading avahi
+
 The @code{(gnu services avahi)} provides the following definition.
 
 @defvr {Scheme Variable} avahi-service-type
@@ -20303,6 +20535,11 @@  This is a list of domains to browse.
 @end table
 @end deftp
 
+
+@anchor{Open vSwitch}
+@subsubheading Open vSwitch
+@cindex Open vSwitch
+
 @deffn {Scheme Variable} openvswitch-service-type
 This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
 service, whose value should be an @code{openvswitch-configuration}
@@ -20321,6 +20558,11 @@  Package object of the Open vSwitch.
 @end table
 @end deftp
 
+
+@anchor{PageKite}
+@subsubheading PageKite
+@cindex PageKite
+
 @defvr {Scheme Variable} pagekite-service-type
 This is the service type for the @uref{https://pagekite.net, PageKite} service,
 a tunneling solution for making localhost servers publicly visible, even from
@@ -20367,6 +20609,11 @@  Use this to add additional options and manage shared secrets out-of-band.
 @end table
 @end deftp
 
+
+@anchor{Yggdrasil}
+@subsubheading Yggdrasil
+@cindex Yggdrasil
+
 @defvr {Scheme Variable} yggdrasil-service-type
 The service type for connecting to the @uref{https://yggdrasil-network.github.io/,
 Yggdrasil network}, an early-stage implementation of a fully end-to-end
@@ -20455,7 +20702,11 @@  address, delete everything except these options:
 @end table
 @end deftp
 
+
+@anchor{IPFS network}
+@subsubheading IPFS network
 @cindex IPFS
+
 @defvr {Scheme Variable} ipfs-service-type
 The service type for connecting to the @uref{https://ipfs.io,IPFS network},
 a global, versioned, peer-to-peer file system. Pass it a
@@ -20486,7 +20737,11 @@  Address of the API endpoint, in ‘multiaddress’ format.
 @end table
 @end deftp
 
+
+@anchor{keepalived}
+@subsubheading keepalived
 @cindex keepalived
+
 @deffn {Scheme Variable} keepalived-service-type
 This is the type for the @uref{https://www.keepalived.org/, Keepalived}
 routing software, @command{keepalived}.  Its value must be an
@@ -20676,16 +20931,25 @@  File where unattended upgrades are logged.
 @end table
 @end deftp
 
+
 @node X Window
 @subsection X Window
 
 @cindex X11
 @cindex X Window System
+
 @cindex login manager
 Support for the X Window graphical display system---specifically
 Xorg---is provided by the @code{(gnu services xorg)} module.  Note that
 there is no @code{xorg-service} procedure.  Instead, the X server is
 started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
+@menu
+* GNOME Desktop Manager (GDM)::
+* SLiM graphical login manager::
+* SDDM login manager::
+* Xorg configuration::
+* Screen Locker::
+@end menu
 
 @cindex GDM
 @cindex GNOME, login manager
@@ -20705,6 +20969,10 @@  its user interface, and it can also start Wayland sessions.  The former is
 required for the latter, to enable, set @code{wayland?} to @code{#t} in
 @code{gdm-configuration}.
 
+
+@anchor{GNOME Desktop Manager (GDM)}
+@subsubheading GNOME Desktop Manager (GDM)
+
 @defvr {Scheme Variable} gdm-service-type
 This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
 Desktop Manager} (GDM), a program that manages graphical display servers and
@@ -20761,6 +21029,10 @@  environment.
 @end table
 @end deftp
 
+
+@anchor{SLiM graphical login manager}
+@subsubheading SLiM graphical login manager
+
 @defvr {Scheme Variable} slim-service-type
 This is the type for the SLiM graphical login manager for X11.
 
@@ -20864,8 +21136,11 @@  The default SLiM theme and its name.
 @end defvr
 
 
+@anchor{SDDM login manager}
+@subsubheading SDDM login manager
 @cindex login manager
 @cindex X11 login
+
 @defvr {Scheme Variable} sddm-service-type
 This is the type of the service to run the
 @uref{https://github.com/sddm/sddm,SDDM display manager}.  Its value
@@ -20977,7 +21252,10 @@  Relogin after logout.
 @end deftp
 
 
+@anchor{Xorg configuration}
+@subsubheading Xorg configuration
 @cindex Xorg, configuration
+
 @deftp {Data Type} xorg-configuration
 This data type represents the configuration of the Xorg graphical display
 server.  Note that there is no Xorg service; instead, the X server is started
@@ -21044,6 +21322,9 @@  Usually the X server is started by a login manager.
 @end deffn
 
 
+@anchor{Screen Locker}
+@subsubheading Screen Locker
+
 @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
 Add @var{package}, a package for a screen locker or screen saver whose
 command is @var{program}, to the set of setuid programs and add a PAM entry
@@ -21059,11 +21340,18 @@  makes the good ol' XlockMore usable.
 
 @node Printing Services
 @subsection Printing Services
-
+@cindex CUPS, printer support
 @cindex printer support with CUPS
+
 The @code{(gnu services cups)} module provides a Guix service definition
 for the CUPS printing service.  To add printer support to a Guix
 system, add a @code{cups-service} to the operating system definition:
+@menu
+* CUPS::
+@end menu
+
+@anchor{CUPS}
+@subsubheading CUPS
 
 @deffn {Scheme Variable} cups-service-type
 The service type for the CUPS print server.  Its value should be a valid
@@ -21919,6 +22207,29 @@  machine running a graphical display server, possibly with graphical user
 interfaces, etc.  It also defines services that provide specific desktop
 environments like GNOME, Xfce or MATE.
 
+@menu
+* GNOME Desktop Environment::
+* Xfce Desktop Environment::
+* Mate Desktop Environment::
+* LXQt Desktop Environment::
+* Enlightenment Window Manager::
+* Selecting Your Desktop Environment::
+
+Service Definitions included in @code{%desktop-services}
+* D-Bus::
+* Elogind::
+* AccountsService::
+* Polkit::
+* upowerd::
+* UDisks::
+* colord::
+* SANE::
+* GeoClue::
+* Bluetooth::
+* GNOME Keyring::
+* seatd::
+@end menu
+
 To simplify things, the module defines a variable containing the set of
 services that users typically expect on a machine with a graphical
 environment and networking:
@@ -21976,6 +22287,10 @@  Alternatively you can also try starting GNOME on Wayland manually from a
 TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
 gnome-session``.  Currently only GNOME has support for Wayland.
 
+
+@anchor{GNOME Desktop Environment}
+@subsubheading GNOME Desktop Environment
+
 @defvr {Scheme Variable} gnome-desktop-service-type
 This is the type of the service that adds the @uref{https://www.gnome.org,
 GNOME} desktop environment.  Its value is a @code{gnome-desktop-configuration}
@@ -21994,6 +22309,9 @@  The GNOME package to use.
 @end table
 @end deftp
 
+@anchor{Xfce Desktop Environment}
+@subsubheading Xfce Desktop Environment
+
 @defvr {Scheme Variable} xfce-desktop-service-type
 This is the type of a service to run the @uref{Xfce, https://xfce.org/}
 desktop environment.  Its value is an @code{xfce-desktop-configuration} object
@@ -22020,6 +22338,10 @@  The Xfce package to use.
 @end table
 @end deftp
 
+
+@anchor{Mate Desktop Environment}
+@subsubheading Mate Desktop Environment
+
 @deffn {Scheme Variable} mate-desktop-service-type
 This is the type of the service that runs the @uref{https://mate-desktop.org/,
 MATE desktop environment}.  Its value is a @code{mate-desktop-configuration}
@@ -22039,6 +22361,10 @@  The MATE package to use.
 @end table
 @end deftp
 
+
+@anchor{LXQt Desktop Environment}
+@subsubheading LXQt Desktop Environment
+
 @deffn {Scheme Variable} lxqt-desktop-service-type
 This is the type of the service that runs the @uref{https://lxqt-project.org,
 LXQt desktop environment}.  Its value is a @code{lxqt-desktop-configuration}
@@ -22057,6 +22383,10 @@  The LXQT package to use.
 @end table
 @end deftp
 
+
+@anchor{Enlightenment Window Manager}
+@subsubheading Enlightenment Window Manager
+
 @deffn {Scheme Variable} enlightenment-desktop-service-type
 Return a service that adds the @code{enlightenment} package to the system
 profile, and extends dbus with actions from @code{efl}.
@@ -22069,6 +22399,10 @@  The enlightenment package to use.
 @end table
 @end deftp
 
+
+@anchor{Selecting Your Desktop Environment}
+@subsubheading Selecting Your Desktop Environment
+
 Because the GNOME, Xfce and MATE desktop services pull in so many packages,
 the default @code{%desktop-services} variable doesn't include any of
 them by default.  To add GNOME, Xfce or MATE, just @code{cons} them onto
@@ -22090,10 +22424,18 @@  them by default.  To add GNOME, Xfce or MATE, just @code{cons} them onto
 These desktop environments will then be available as options in the
 graphical login window.
 
+
+@anchor{Service Definitions included in @code{%desktop-services}}
+@subsubheading Service Definitions included in @code{%desktop-services}
+
 The actual service definitions included in @code{%desktop-services} and
 provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
 are described below.
 
+
+@anchor{D-Bus}
+@subsubheading D-Bus
+
 @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] @
                                        [#:verbose?]
 Return a service that runs the ``system bus'', using @var{dbus}, with
@@ -22113,6 +22455,10 @@  and policy files.  For example, to allow avahi-daemon to use the system bus,
 @var{services} must be equal to @code{(list avahi)}.
 @end deffn
 
+
+@anchor{Elogind}
+@subsubheading Elogind
+
 @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
 Return a service that runs the @code{elogind} login and
 seat management daemon.  @uref{https://github.com/elogind/elogind,
@@ -22185,6 +22531,10 @@  their default values are:
 @end table
 @end deffn
 
+
+@anchor{AccountsService}
+@subsubheading AccountsService
+
 @deffn {Scheme Procedure} accountsservice-service @
        [#:accountsservice @var{accountsservice}]
 Return a service that runs AccountsService, a system service that can
@@ -22198,6 +22548,10 @@  The @var{accountsservice} keyword argument is the @code{accountsservice}
 package to expose as a service.
 @end deffn
 
+
+@anchor{Polkit}
+@subsubheading Polkit
+
 @deffn {Scheme Procedure} polkit-service @
                          [#:polkit @var{polkit}]
 Return a service that runs the
@@ -22216,6 +22570,10 @@  for their own passwords when performing administrative actions instead of
 @code{root}'s, similar to the behaviour used by @code{sudo}.
 @end defvr
 
+
+@anchor{upowerd}
+@subsubheading upowerd
+
 @defvr {Scheme Variable} upower-service-type
 Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
 system-wide monitor for power consumption and battery levels, with the given
@@ -22290,6 +22648,10 @@  Possible values are:
 @end table
 @end deftp
 
+
+@anchor{UDisks}
+@subsubheading UDisks
+
 @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
 Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
 UDisks}, a @dfn{disk management} daemon that provides user interfaces
@@ -22302,6 +22664,10 @@  file-systems in read and write fashion, you'll need to have
 @code{ntfs-3g} installed system-wide.
 @end deffn
 
+
+@anchor{colord}
+@subsubheading colord
+
 @deffn {Scheme Variable} colord-service-type
 This is the type of the service that runs @command{colord}, a system
 service with a D-Bus
@@ -22311,7 +22677,11 @@  tool.  See @uref{https://www.freedesktop.org/software/colord/, the colord web
 site} for more information.
 @end deffn
 
+
+@anchor{SANE}
+@subsubheading SANE
 @cindex scanner access
+
 @defvr {Scheme Variable} sane-service-type
 This service provides access to scanners @i{via}
 @uref{http://www.sane-project.org, SANE} by installing the necessary
@@ -22353,6 +22723,10 @@  a system which relies on @code{%desktop-services}, you may use
 @end lisp
 @end defvr
 
+
+@anchor{GeoClue}
+@subsubheading GeoClue
+
 @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
 Return a configuration allowing an application to access GeoClue
 location data.  @var{name} is the Desktop ID of the application, without
@@ -22388,6 +22762,10 @@  location databases.  See
 web site} for more information.
 @end deffn
 
+
+@anchor{Bluetooth}
+@subsubheading Bluetooth
+
 @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
        [@w{#:auto-enable? #f}]
 Return a service that runs the @command{bluetoothd} daemon, which
@@ -22841,6 +23219,10 @@  Possible values are:
 @end table
 @end deftp
 
+
+@anchor{GNOME Keyring}
+@subsubheading GNOME Keyring
+
 @defvr {Scheme Variable} gnome-keyring-service-type
 This is the type of the service that adds the
 @uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}.  Its
@@ -22875,6 +23257,10 @@  and ``passwd'' is with the value @code{passwd}.
 @end table
 @end deftp
 
+
+@anchor{seatd}
+@subsubheading seatd
+
 @defvr {Scheme Variable} seatd-service-type
 @uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat
 management daemon.
@@ -22923,15 +23309,23 @@  Log level to output logs. Possible values: @samp{"silent"}, @samp{"error"},
 
 @node Sound Services
 @subsection Sound Services
-
 @cindex sound support
-@cindex ALSA
-@cindex PulseAudio, sound support
 
 The @code{(gnu services sound)} module provides a service to configure the
 Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
 preferred ALSA output driver.
 
+@menu
+* ALSA::
+* PulseAudio::
+* LADSPA plugins path::
+@end menu
+
+
+@anchor{ALSA}
+@subsubheading ALSA
+@cindex ALSA
+
 @deffn {Scheme Variable} alsa-service-type
 This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
 Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
@@ -23001,6 +23395,11 @@  pcm.!default @{
 See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
 details.
 
+
+@anchor{PulseAudio}
+@subsubheading PulseAudio
+@cindex PulseAudio, sound support
+
 @deffn {Scheme Variable} pulseaudio-service-type
 This is the type for the  @uref{https://www.pulseaudio.org/, PulseAudio}
 sound server.  It exists to allow system overrides of the default settings
@@ -23077,6 +23476,10 @@  above example to modify the existing @code{pulseaudio-service-type} via
 
 @end deftp
 
+
+@anchor{LADSPA plugins path}
+@subsubheading LADSPA plugins path
+
 @deffn {Scheme Variable} ladspa-service-type
 This service sets the @var{LADSPA_PATH} variable, so that programs, which
 respect it, e.g. PulseAudio, can load LADSPA plugins.
@@ -27655,6 +28058,10 @@  server.  In addition to configuring the service itself, you may want to add
 @code{ldap} as a name service to the Name Service Switch. @xref{Name Service
 Switch} for detailed information.
 
+@menu
+* nslcd::
+@end menu
+
 Here is a simple operating system declaration with a default configuration of
 the @code{nslcd-service-type} and a Name Service Switch configuration that
 consults the @code{ldap} name service last:
@@ -27683,6 +28090,10 @@  consults the @code{ldap} name service last:
       (gshadow  services)))))
 @end lisp
 
+
+@anchor{nslcd}
+@subsubheading nslcd
+
 @c %start of generated documentation for nslcd-configuration
 
 Available @code{nslcd-configuration} fields are:
@@ -29368,6 +29779,13 @@  content securely over HTTPS or other TLS-based protocols, with the
 knowledge that the client will be able to verify the server's
 authenticity.
 
+@menu
+* certbot::
+@end menu
+
+@anchor{certbot}
+@subsubheading certbot
+
 @url{https://letsencrypt.org/, Let's Encrypt} provides the
 @code{certbot} tool to automate the certification process.  This tool
 first securely generates a key on the server.  It then makes a request