Toggle diff (509 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 245a18bc70..0fa4ec27a6 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -120,7 +120,15 @@ Project}.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
-* GNU Distribution:: Software for your friendly GNU system.
+* System Installation:: Installing the whole operating system.
+* System Configuration:: Configuring the operating system.
+* Documentation:: Browsing software user manuals.
+* Installing Debugging Files:: Feeding the debugger.
+* Security Updates:: Deploying security fixes quickly.
+* Package Modules:: Packages from the programmer's viewpoint.
+* Packaging Guidelines:: Growing the distribution.
+* Bootstrapping:: GNU/Linux built from scratch.
+* Porting:: Targeting another platform or kernel.
* Contributing:: Your help needed!
* Acknowledgments:: Thanks!
@@ -210,18 +218,6 @@ Invoking @command{guix build}
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
-GNU Distribution
-
-* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
-* Installing Debugging Files:: Feeding the debugger.
-* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
-* Bootstrapping:: GNU/Linux built from scratch.
-* Porting:: Targeting another platform or kernel.
-
System Installation
* Limitations:: What you can expect.
@@ -297,21 +293,6 @@ Packaging Guidelines
* Java Packages:: Coffee break.
* Fonts:: Fond of fonts.
-Contributing
-
-* Building from Git:: The latest and greatest.
-* Running Guix Before It Is Installed:: Hacker tricks.
-* The Perfect Setup:: The right tools.
-* Coding Style:: Hygiene of the contributor.
-* Submitting Patches:: Share your work.
-
-Coding Style
-
-* Programming Paradigm:: How to compose your elements.
-* Modules:: Where to store your code?
-* Data Types and Pattern Matching:: Implementing data structures.
-* Formatting Code:: Writing conventions.
-
@end detailmenu
@end menu
@@ -322,11 +303,22 @@ Coding Style
@cindex purpose
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``?i?ks''
using the international phonetic alphabet (IPA).} is a package
-management tool for the GNU system. Guix makes it easy for unprivileged
-users to install, upgrade, or remove packages, to roll back to a
+management tool for and distribution of the GNU system.
+Guix makes it easy for unprivileged
+users to install, upgrade, or remove software packages, to roll back to a
previous package set, to build packages from source, and generally
assists with the creation and maintenance of software environments.
+@cindex Guix System
+@cindex GuixSD
+You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
+complements the available tools without interference (@pxref{Installation}),
+or you can use it as a standalone operating system distribution,
+@dfn{Guix@tie{}System} (@pxref{GNU Distribution}).
+
+@node Managing Software the Guix Way
+@section Managing Software the Guix Way
+
@cindex user interfaces
Guix provides a command-line package management interface
(@pxref{Invoking guix package}), a set of command-line utilities
@@ -348,17 +340,6 @@ is also @emph{customizable}: users can @emph{derive} specialized package
definitions from existing ones, including from the command line
(@pxref{Package Transformation Options}).
-@cindex Guix System Distribution
-@cindex GuixSD
-You can install GNU@tie{}Guix on top of an existing GNU/Linux system
-where it complements the available tools without interference
-(@pxref{Installation}), or you can use it as part of the standalone
-@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
-With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
-system configuration and Guix takes care of instantiating the
-configuration in a transactional, reproducible, and stateless fashion
-(@pxref{System Configuration}).
-
@cindex functional package management
@cindex isolation
Under the hood, Guix implements the @dfn{functional package management}
@@ -389,6 +370,81 @@ for transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).
+@node GNU Distribution
+@section GNU Distribution
+
+@cindex Guix System
+@cindex GuixSD
+Guix comes with a distribution of the GNU system consisting entirely of
+free software@footnote{The term ``free'' here refers to the
+@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
+users of that software}.}. The
+distribution can be installed on its own (@pxref{System Installation}),
+but it is also possible to install Guix as a package manager on top of
+an installed GNU/Linux system (@pxref{Installation}). When we need to
+distinguish between the two, we refer to the standalone distribution as
+Guix@tie{}System.
+
+The distribution provides core GNU packages such as GNU libc, GCC, and
+Binutils, as well as many GNU and non-GNU applications. The complete
+list of available packages can be browsed
+@url{http://www.gnu.org/software/guix/packages,on-line} or by
+running @command{guix package} (@pxref{Invoking guix package}):
+
+@example
+guix package --list-available
+@end example
+
+Our goal is to provide a practical 100% free software distribution of
+Linux-based and other variants of GNU, with a focus on the promotion and
+tight integration of GNU components, and an emphasis on programs and
+tools that help users exert that freedom.
+
+Packages are currently available on the following platforms:
+
+@table @code
+
+@item x86_64-linux
+Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
+
+@item i686-linux
+Intel 32-bit architecture (IA32), Linux-Libre kernel;
+
+@item armhf-linux
+ARMv7-A architecture with hard float, Thumb-2 and NEON,
+using the EABI hard-float application binary interface (ABI),
+and Linux-Libre kernel.
+
+@item aarch64-linux
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
+currently in an experimental stage, with limited support.
+@xref{Contributing}, for how to help!
+
+@item mips64el-linux
+little-endian 64-bit MIPS processors, specifically the Loongson series,
+n32 ABI, and Linux-Libre kernel.
+
+@end table
+
+With Guix@tie{}System, you @emph{declare} all aspects of the operating system
+configuration and Guix takes care of instantiating the configuration in a
+transactional, reproducible, and stateless fashion (@pxref{System
+Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
+initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
+Manual}), the well-known GNU utilities and tool chain, as well as the
+graphical environment or system services of your choice.
+
+Guix System is available on all the above platforms except
+@code{mips64el-linux}.
+
+@noindent
+For information on porting to other architectures or kernels,
+@pxref{Porting}.
+
+Building this distribution is a cooperative effort, and you are invited
+to join! @xref{Contributing}, for information about how you can help.
+
+
@c *********************************************************************
@node Installation
@chapter Installation
@@ -9034,86 +9090,9 @@ ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
-@c *********************************************************************
-@node GNU Distribution
-@chapter GNU Distribution
-
-@cindex Guix System Distribution
-@cindex GuixSD
-Guix comes with a distribution of the GNU system consisting entirely of
-free software@footnote{The term ``free'' here refers to the
-@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
-users of that software}.}. The
-distribution can be installed on its own (@pxref{System Installation}),
-but it is also possible to install Guix as a package manager on top of
-an installed GNU/Linux system (@pxref{Installation}). To distinguish
-between the two, we refer to the standalone distribution as the Guix
-System Distribution, or GuixSD.
-
-The distribution provides core GNU packages such as GNU libc, GCC, and
-Binutils, as well as many GNU and non-GNU applications. The complete
-list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/packages,on-line} or by
-running @command{guix package} (@pxref{Invoking guix package}):
-
-@example
-guix package --list-available
-@end example
-
-Our goal is to provide a practical 100% free software distribution of
-Linux-based and other variants of GNU, with a focus on the promotion and
-tight integration of GNU components, and an emphasis on programs and
-tools that help users exert that freedom.
-
-Packages are currently available on the following platforms:
-
-@table @code
-
-@item x86_64-linux
-Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
-
-@item i686-linux
-Intel 32-bit architecture (IA32), Linux-Libre kernel;
-
-@item armhf-linux
-ARMv7-A architecture with hard float, Thumb-2 and NEON,
-using the EABI hard-float application binary interface (ABI),
-and Linux-Libre kernel.
-
-@item aarch64-linux
-little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
-currently in an experimental stage, with limited support.
-@xref{Contributing}, for how to help!
-
-@item mips64el-linux
-little-endian 64-bit MIPS processors, specifically the Loongson series,
-n32 ABI, and Linux-Libre kernel.
-
-@end table
-
-GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
-
-@noindent
-For information on porting to other architectures or kernels,
-@pxref{Porting}.
-
-@menu
-* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
-* Installing Debugging Files:: Feeding the debugger.
-* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
-* Bootstrapping:: GNU/Linux built from scratch.
-* Porting:: Targeting another platform or kernel.
-@end menu
-
-Building this distribution is a cooperative effort, and you are invited
-to join! @xref{Contributing}, for information about how you can help.
@node System Installation
-@section System Installation
+@chapter System Installation
@cindex installing GuixSD
@cindex Guix System Distribution
@@ -9147,7 +9126,7 @@ available.
@end menu
@node Limitations
-@subsection Limitations
+@section Limitations
As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
not production-ready. It may contain bugs and lack important
@@ -9191,7 +9170,7 @@ to report issues (and success stories!), and to join us in improving it.
@node Hardware Considerations
-@subsection Hardware Considerations
+@section Hardware Considerations
@cindex hardware support on GuixSD
GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It
@@ -9226,7 +9205,7 @@ about their support in GNU/Linux.
@node USB Stick and DVD Installation
-@subsection USB Stick and DVD Installation
+@section USB Stick and DVD Installation
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
@@ -9265,7 +9244,7 @@ and rerun the @code{gpg --verify} command.
This image contains the tools necessary for an installation.
It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
-@unnumberedsubsubsec Copying to a USB Stick
+@unnumberedsubsec Copying to a USB Stick
To copy the image to a USB stick, follow these steps:
@@ -9290,7 +9269,7 @@ sync
Access to @file{/dev/sdX} usually requires root privileges.
@end enumerate
-@unnumberedsubsubsec Burning on a DVD
+@unnumberedsubsec Burning on a DVD
To copy the image to a DVD, follow these steps:
@@ -9314,7 +9293,7 @@ growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.is
Access to @file{/dev/srX} usually requires root privileges.
@end enumerate
-@unnumberedsubsubsec Booting
+@unnumberedsubsec Booting
Once this is done, you should be able to reboot the system and boot from
the USB stick or DVD. The latter usually requires you to get in the
@@ -9325,7 +9304,7 @@ GuixSD in a virtual machine (VM).
@node Preparing for Installation
-@subsection Preparing for Installation
+@section Preparing for Installation
Once you have successfully booted your computer using the installation medium,
you should end up with the welcome page of the graphical installer. The
@@ -9354,7 +9333,7 @@ But it is also a full-blown GuixSD system, which means that you can
install additional packages, should you need it, using @command{guix
package} (@pxref{Invoking guix package}).
-@subsubsection Keyboard Layout
+@subsection Keyboard Layout
@cindex keyboard layout
The installation image uses the US qwerty keyboard layout. If you want
@@ -9369,7 +9348,7 @@ See the files under @file{/run/current-system/profile/share/keymaps} for
a list of available keyboard layouts. Run @command{man loadkeys} for
more information.
-@subsubsection Networking
+@subsection Networking
Run the following command to see what your network interfaces are called:
@@ -9462,7 +9441,7 @@ herd start ssh-daemon
Make sure to either set a password with @command{passwd}, or configure
OpenSSH public key authentication before logging in.
-@subsubsection Disk Partitioning
+@subsection Disk Partitioning
Unless this has already been done, the next step is to partition, and
then format the target partition(s).
@@ -9583,7 +9562,7 @@ file in its file system as described above, then the encryption also
protects the swap file, just like any other file in that file system.
@node Proceeding with the Installation
-@subsection Proceeding with the Installation
+@section Proceeding with the Installation
With the target partitions ready and the target root mounted on
@file{/mnt}, we're ready to go. First, run:
@@ -9680,7 +9659,7 @@ Join us on @code{#guix} on the Freenode IRC network or on
good.
@node Installing GuixSD in a VM
-@subsection Installing GuixSD in a Virtual Machine
+@section Installing GuixSD in a Virtual Machine
@cindex virtual machine, GuixSD installation
@cindex virtual private server (VPS)
@@ -9734,7 +9713,7 @@ Once installation is complete, you can boot the system that's on your
that.
@node Building the Installation Image
-@subsection Building the Installation Image
+@section Building the Installation Image
@cindex installation image
The installation image described above was built using the @command{guix
@@ -9748,7 +9727,7 @@ Have a look at @file{gnu/system/install.scm} in the source tree,
and see also @ref{Invoking guix system} for more information
about the installation image.
-@subsection Building the Installation Image for ARM Boards
+@section Building the Installation Image for ARM Boards
Many ARM boards require a specific variant of the
@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
@@ -9765,7 +9744,7 @@ guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-wit
board, a list of possible boards will be printed.
@node System Configuration
-@section System Configuration
+@chapter System Configuration
@cindex system configuration
The Guix System Distribution supports a consistent whole-system configuration
@@ -9808,7 +9787,7 @@ instance to support new system services.
@end menu
@node Using the Configuration System
-@subsection Using the Configuration System
+@section Using the Configuration System
The operating system is configured by providing an
@code{operating-system} declaration in a file that can then be passed to
@@ -9831,7 +9810,7 @@ Below we discuss the effect of some of the most important fields
fields), and how to @dfn{instantiate} the operating system using
@command{guix system}.
-@unnumberedsubsubsec Bootloader
+@unnumberedsubsec Bootloader
@cindex legacy boot, on Intel machines
@cindex BIOS boot, on Intel machines
@@ -9852,7 +9831,7 @@ the @code{bootloader} field should contain something along these lines:
@xref{Bootloader Configuration}, for more information on the available
configuration options.
-@unnumberedsubsubsec Globally-Visible Packages
+@unnumberedsubsec Globally-Visible Packages
@vindex %base-packages
The @code{packages} field lists packages that will be globally visible
@@ -9898,7 +9877,7 @@ version:
%base-packages)))
@end lisp
-@unnumberedsubsubsec System Services
+@unnumberedsubsec System Services
@cindex services
@vindex %base-services
@@ -9990,7 +9969,7 @@ following expression returns a list that contains all the services in
%desktop-services)
@end example
-@unnumberedsubsubsec Instantiating the System
+@unnumberedsubsec Instantiating the System
Assuming the @code{operating-system} declaration
is stored in the @file{my-system-config.scm}
@@ -10023,7 +10002,7 @@ the latest (e.g., after invoking @command{guix system roll-back}), since
the operation might overwrite a later generation (@pxref{Invoking guix
system}).
-@unnumberedsubsubsec The Programming Interface
+@unnumberedsubsec The Programming Interface
At the Scheme level, the bulk of an @code{operating-system} declaration
is instantiated with the following monadic procedure (@pxref{The Store
@@ -10044,7 +10023,7 @@ guts of GuixSD. Make sure to visit it!
@node operating-system Reference
-@subsection @code{operating-system} Reference
+@section @code{operating-system} Reference
This section summarizes all the options available in
@code{operating-system} declarations (@pxref{Using the Configuration
@@ -10198,7 +10177,7 @@ is that only @code{root} and members of the @code{wheel} group may use
@end deftp
@node File Systems
-@subsection File Systems
+@section File Systems
The list of file systems to be mounted is specified in the
@code{file-systems} field of the operating system declaration
@@ -10363,7 +10342,7 @@ and unmount user-space FUSE file systems. This requires the
@end defvr
@node Mapped Devices
-@subsection Mapped Devices
+@section Mapped Devices
@cindex device mapping
@cindex mapped devices
@@ -10484,7 +10463,7 @@ automatically later.
@node User Accounts
-@subsection User Accounts
+@section User Accounts
@cindex users
@cindex accounts
@@ -10619,7 +10598,7 @@ special-case and is automatically added whether or not it is specified.
@end defvr
@node Locales
-@subsection Locales
+@section Locales
@cindex locale
A @dfn{lo