system: Build system-wide locale definitions.
[jackhill/guix/guix.git] / doc / guix.texi
index c7f72d7..d4bc74f 100644 (file)
@@ -76,6 +76,93 @@ package management tool written for the GNU system.
 * GNU Free Documentation License::  The license of this manual.
 * Concept Index::               Concepts.
 * Programming Index::           Data types, functions, and variables.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Installation
+
+* Requirements::                Software needed to build and run Guix.
+* Setting Up the Daemon::       Preparing the build daemon's environment.
+* Invoking guix-daemon::        Running the build daemon.
+
+Setting Up the Daemon
+
+* Build Environment Setup::     Preparing the isolated build environment.
+* Daemon Offload Setup::        Offloading builds to remote machines.
+
+Package Management
+
+* Features::                    How Guix will make your life brighter.
+* Invoking guix package::       Package installation, removal, etc.
+* Emacs Interface::             Package management from Emacs.
+* Substitutes::                 Downloading pre-built binaries.
+* Packages with Multiple Outputs::  Single source package, multiple outputs.
+* Invoking guix gc::            Running the garbage collector.
+* Invoking guix pull::          Fetching the latest Guix and distribution.
+* Invoking guix archive::       Exporting and importing store files.
+
+Programming Interface
+
+* Defining Packages::           Defining new packages.
+* Build Systems::               Specifying how packages are built.
+* The Store::                   Manipulating the package store.
+* Derivations::                 Low-level interface to package derivations.
+* The Store Monad::             Purely functional interface to the store.
+* G-Expressions::               Manipulating build expressions.
+
+Utilities
+
+* Invoking guix build::         Building packages from the command line.
+* Invoking guix download::      Downloading a file and printing its hash.
+* Invoking guix hash::          Computing the cryptographic hash of a file.
+* Invoking guix import::        Importing package definitions.
+* Invoking guix refresh::       Updating package definitions.
+* Invoking guix lint::          Finding errors in package definitions.
+* Invoking guix environment::   Setting up development environments.
+
+GNU Distribution
+
+* System Installation::         Installing the whole operating system.
+* System Configuration::        Configuring a GNU system.
+* 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 Configuration
+
+* Using the Configuration System::  Customizing your GNU system.
+* operating-system Reference::  Detail of operating-system declarations.
+* File Systems::                Configuring file system mounts.
+* Mapped Devices::              Block device extra processing.
+* User Accounts::               Specifying user accounts.
+* Locales::                     Language and cultural convention settings.
+* Services::                    Specifying system services.
+* Setuid Programs::             Programs running with root privileges.
+* Initial RAM Disk::            Linux-Libre bootstrapping.
+* GRUB Configuration::          Configuring the boot loader.
+* Invoking guix system::        Instantiating a system configuration.
+* Defining Services::           Adding new service definitions.
+
+Services
+
+* Base Services::               Essential system services.
+* Networking Services::         Network setup, SSH daemon, etc.
+* X Window::                    Graphical display.
+
+Packaging Guidelines
+
+* Software Freedom::     What may go into the distribution.
+* Package Naming::       What's in a name?
+* Version Numbers::      When the name is not enough.
+* Python Modules::       Taming the snake.
+* Perl Modules::         Little pearls.
+* Fonts::                Fond of fonts.
+
+@end detailmenu
 @end menu
 
 @c *********************************************************************
@@ -165,7 +252,8 @@ The following dependencies are optional:
 @item
 Installing
 @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
-allow you to use the @command{guix import pypi} command; it is of
+allow you to use the @command{guix import pypi} command (@pxref{Invoking
+guix import}).  It is of
 interest primarily for developers and not for casual users.
 @item
 Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
@@ -435,7 +523,7 @@ is normally run as @code{root} like this:
 @end example
 
 @noindent
-For details on how to set it up, @ref{Setting Up the Daemon}.
+For details on how to set it up, @pxref{Setting Up the Daemon}.
 
 @cindex chroot
 @cindex container, build environment
@@ -509,7 +597,9 @@ parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
 @item --max-jobs=@var{n}
 @itemx -M @var{n}
 Allow at most @var{n} build jobs in parallel.  The default value is
-@code{1}.
+@code{1}.  Setting it to @code{0} means that no builds will be performed
+locally; instead, the daemon will offload builds (@pxref{Daemon Offload
+Setup}), or simply fail.
 
 @item --debug
 Produce debugging output.
@@ -633,7 +723,7 @@ When using Guix, each package ends up in the @dfn{package store}, in its
 own directory---something that resembles
 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
 (note that Guix comes with an Emacs extension to shorten those file
-names, @ref{Emacs Prettify}.)
+names, @pxref{Emacs Prettify}.)
 
 Instead of referring to these directories, users have their own
 @dfn{profile}, which points to the packages that they actually want to
@@ -1463,6 +1553,10 @@ This package object can be inspected using procedures found in the
 @code{(guix packages)} module; for instance, @code{(package-name hello)}
 returns---surprise!---@code{"hello"}.
 
+With luck, you may be able to import part or all of the definition of
+the package you are interested in from another repository, using the
+@code{guix import} command (@pxref{Invoking guix import}).
+
 In the example above, @var{hello} is defined into a module of its own,
 @code{(gnu packages hello)}.  Technically, this is not strictly
 necessary, but it is convenient to do so: all the packages defined in
@@ -1521,16 +1615,13 @@ However, any other dependencies need to be specified in the
 unavailable to the build process, possibly leading to a build failure.
 @end itemize
 
-Once a package definition is in place@footnote{Simple package
-definitions like the one above may be automatically converted from the
-Nixpkgs distribution using the @command{guix import} command.}, the
+Once a package definition is in place, the
 package may actually be built using the @code{guix build} command-line
 tool (@pxref{Invoking guix build}).  @xref{Packaging Guidelines}, for
 more information on how to test package definitions, and
 @ref{Invoking guix lint}, for information on how to check a definition
 for style conformance.
 
-
 Eventually, updating the package definition to a new upstream version
 can be partly automated by the @command{guix refresh} command
 (@pxref{Invoking guix refresh}).
@@ -2475,6 +2566,7 @@ programming interface of Guix in a convenient way.
 * Invoking guix build::         Building packages from the command line.
 * Invoking guix download::      Downloading a file and printing its hash.
 * Invoking guix hash::          Computing the cryptographic hash of a file.
+* Invoking guix import::        Importing package definitions.
 * Invoking guix refresh::       Updating package definitions.
 * Invoking guix lint::          Finding errors in package definitions.
 * Invoking guix environment::   Setting up development environments.
@@ -2676,6 +2768,12 @@ may be helpful when debugging setup issues with the build daemon.
 Allow the use of up to @var{n} CPU cores for the build.  The special
 value @code{0} means to use as many CPU cores as available.
 
+@item --max-jobs=@var{n}
+@itemx -M @var{n}
+Allow at most @var{n} build jobs in parallel.  @xref{Invoking
+guix-daemon, @code{--max-jobs}}, for details about this option and the
+equivalent @command{guix-daemon} option.
+
 @end table
 
 Behind the scenes, @command{guix build} is essentially an interface to
@@ -2714,7 +2812,7 @@ The following option is available:
 @item --format=@var{fmt}
 @itemx -f @var{fmt}
 Write the hash in the format specified by @var{fmt}.  For more
-information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
+information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
 @end table
 
 @node Invoking guix hash
@@ -2761,6 +2859,96 @@ hash (@pxref{Invoking guix archive}).
 
 @end table
 
+@node Invoking guix import
+@section Invoking @command{guix import}
+
+@cindex importing packages
+@cindex package import
+@cindex package conversion
+The @command{guix import} command is useful for people willing to add a
+package to the distribution but who'd rather do as little work as
+possible to get there---a legitimate demand.  The command knows of a few
+repositories from which it can ``import'' package meta-data.  The result
+is a package definition, or a template thereof, in the format we know
+(@pxref{Defining Packages}).
+
+The general syntax is:
+
+@example
+guix import @var{importer} @var{options}@dots{}
+@end example
+
+@var{importer} specifies the source from which to import package
+meta-data, and @var{options} specifies a package identifier and other
+options specific to @var{importer}.  Currently, the available
+``importers'' are:
+
+@table @code
+@item gnu
+Import meta-data for the given GNU package.  This provides a template
+for the latest version of that GNU package, including the hash of its
+source tarball, and its canonical synopsis and description.
+
+Additional information such as the package's dependencies and its
+license needs to be figured out manually.
+
+For example, the following command returns a package definition for
+GNU@tie{}Hello:
+
+@example
+guix import gnu hello
+@end example
+
+Specific command-line options are:
+
+@table @code
+@item --key-download=@var{policy}
+As for @code{guix refresh}, specify the policy to handle missing OpenPGP
+keys when verifying the package's signature.  @xref{Invoking guix
+refresh, @code{--key-download}}.
+@end table
+
+@item pypi
+@cindex pypi
+Import meta-data from the @uref{https://pypi.python.org/, Python Package
+Index}@footnote{This functionality requires Guile-JSON to be installed.
+@xref{Requirements}.}.  Information is taken from the JSON-formatted
+description available at @code{pypi.python.org} and usually includes all
+the relevant information, including package dependencies.
+
+The command below imports meta-data for the @code{itsdangerous} Python
+package:
+
+@example
+guix import pypi itsdangerous
+@end example
+
+@item nix
+Import meta-data from a local copy of the source of the
+@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+relies on the @command{nix-instantiate} command of
+@uref{http://nixos.org/nix/, Nix}.}.  Package definitions in Nixpkgs are
+typically written in a mixture of Nix-language and Bash code.  This
+command only imports the high-level package structure that is written in
+the Nix language.  It normally includes all the basic fields of a
+package definition.
+
+When importing a GNU package, the synopsis and descriptions are replaced
+by their canonical upstream variant.
+
+As an example, the command below imports the package definition of
+LibreOffice (more precisely, it imports the definition of the package
+bound to the @code{libreoffice} top-level attribute):
+
+@example
+guix import nix ~/path/to/nixpkgs libreoffice
+@end example
+@end table
+
+The structure of the @command{guix import} code is modular.  It would be
+useful to have more importers for other package formats, and your help
+is welcome here (@pxref{Contributing}).
+
 @node Invoking guix refresh
 @section Invoking @command{guix refresh}
 
@@ -2797,7 +2985,7 @@ The following options are supported:
 @item --update
 @itemx -u
 Update distribution source files (package recipes) in place.
-@ref{Defining Packages}, for more information on package definitions.
+@xref{Defining Packages}, for more information on package definitions.
 
 @item --select=[@var{subset}]
 @itemx -s @var{subset}
@@ -2860,13 +3048,30 @@ The following options can be used to customize GnuPG operation:
 
 @table @code
 
-@item --key-server=@var{host}
-Use @var{host} as the OpenPGP key server when importing a public key.
-
 @item --gpg=@var{command}
 Use @var{command} as the GnuPG 2.x command.  @var{command} is searched
 for in @code{$PATH}.
 
+@item --key-download=@var{policy}
+Handle missing OpenPGP keys according to @var{policy}, which may be one
+of:
+
+@table @code
+@item always
+Always download missing OpenPGP keys from the key server, and add them
+to the user's GnuPG keyring.
+
+@item never
+Never try to download missing OpenPGP keys.  Instead just bail out.
+
+@item interactive
+When a package signed with an unknown OpenPGP key is encountered, ask
+the user whether to download it or not.  This is the default behavior.
+@end table
+
+@item --key-server=@var{host}
+Use @var{host} as the OpenPGP key server when importing a public key.
+
 @end table
 
 @node Invoking guix lint
@@ -3029,7 +3234,7 @@ For information on porting to other architectures or kernels,
 @end menu
 
 Building this distribution is a cooperative effort, and you are invited
-to join!  @ref{Contributing}, for information about how you can help.
+to join!  @xref{Contributing}, for information about how you can help.
 
 @node System Installation
 @section System Installation
@@ -3165,8 +3370,9 @@ Systems}).  This is typically done using the @code{-L} option of
 @command{mkfs.ext4} and related commands.
 
 The installation image includes Parted (@pxref{Overview,,, parted, GNU
-Parted User Manual}), @command{fdisk}, and e2fsprogs, the suite of tools
-to manipulate ext2/ext3/ext4 file systems.
+Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
+encryption, and e2fsprogs, the suite of tools to manipulate
+ext2/ext3/ext4 file systems.
 
 @item
 Once that is done, mount the target root partition under @file{/mnt}.
@@ -3265,6 +3471,7 @@ instance to support new system services.
 * File Systems::                Configuring file system mounts.
 * Mapped Devices::              Block device extra processing.
 * User Accounts::               Specifying user accounts.
+* Locales::                     Language and cultural convention settings.
 * Services::                    Specifying system services.
 * Setuid Programs::             Programs running with root privileges.
 * Initial RAM Disk::            Linux-Libre bootstrapping.
@@ -3291,7 +3498,7 @@ kernel, initial RAM disk, and boot loader looks like this:
 (operating-system
   (host-name "komputilo")
   (timezone "Europe/Paris")
-  (locale "fr_FR.UTF-8")
+  (locale "fr_FR.utf8")
   (bootloader (grub-configuration
                 (device "/dev/sda")))
   (file-systems (cons (file-system
@@ -3301,12 +3508,11 @@ kernel, initial RAM disk, and boot loader looks like this:
                       %base-file-systems))
   (users (list (user-account
                 (name "alice")
-                (password "")
                 (uid 1000) (group 100)
                 (comment "Bob's sister")
                 (home-directory "/home/alice"))))
   (packages (cons emacs %base-packages))
-  (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
+  (services (cons (lsh-service #:port 2222 #:root-login? #t)
                   %base-services)))
 @end lisp
 
@@ -3385,6 +3591,13 @@ The system bootloader configuration object.  @xref{GRUB Configuration}.
 A two-argument monadic procedure that returns an initial RAM disk for
 the Linux kernel.  @xref{Initial RAM Disk}.
 
+@item @code{firmware} (default: @var{%base-firmware})
+@cindex firmware
+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}.)
+
 @item @code{host-name}
 The host name.
 
@@ -3438,9 +3651,13 @@ package}).
 @item @code{timezone}
 A timezone identifying string---e.g., @code{"Europe/Paris"}.
 
-@item @code{locale} (default: @code{"en_US.UTF-8"})
-The name of the default locale (@pxref{Locales,,, libc, The GNU C
-Library Reference Manual}).
+@item @code{locale} (default: @code{"en_US.utf8"})
+The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
+Library Reference Manual}).  @xref{Locales}, for more information.
+
+@item @code{locale-definitions} (default: @var{%default-locale-definitions})
+The list of locale definitions to be compiled and that may be used at
+run time.  @xref{Locales}.
 
 @item @code{services} (default: @var{%base-services})
 A list of monadic values denoting system services.  @xref{Services}.
@@ -3696,7 +3913,15 @@ account.  System accounts are sometimes treated specially; for instance,
 graphical login managers do not list them.
 
 @item @code{password} (default: @code{#f})
-Unless @code{#f}, this is the password to be used for the account.
+You would normally leave this field to @code{#f}, initialize user
+passwords as @code{root} with the @command{passwd} command, and then let
+users change it with @command{passwd}.
+
+If you @emph{do} want to have a preset password for an account, then
+this field must contain the encrypted password, as a string.
+@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
+on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
+Manual}, for information on Guile's @code{crypt} procedure.
 
 @end table
 @end deftp
@@ -3739,6 +3964,78 @@ to be present on the system.  This includes groups such as ``root'',
 specific devices such as ``audio'', ``disk'', and ``cdrom''.
 @end defvr
 
+@node Locales
+@subsection Locales
+
+@cindex locale
+A @dfn{locale} defines cultural conventions for a particular language
+and region of the world (@pxref{Locales,,, libc, The GNU C Library
+Reference Manual}).  Each locale has a name that typically has the form
+@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
+@code{fr_LU.utf8} designates the locale for the French language, with
+cultural conventions from Luxembourg, and using the UTF-8 encoding.
+
+@cindex locale definition
+Usually, you will want to specify the default locale for the machine
+using the @code{locale} field of the @code{operating-system} declaration
+(@pxref{operating-system Reference, @code{locale}}).
+
+That locale must be among the @dfn{locale definitions} that are known to
+the system---and these are specified in the @code{locale-definitions}
+slot of @code{operating-system}.  The default value includes locale
+definition for some widely used locales, but not for all the available
+locales, in order to save space.
+
+If the locale specified in the @code{locale} field is not among the
+definitions listed in @code{locale-definitions}, @command{guix system}
+raises an error.  In that case, you should add the locale definition to
+the @code{locale-definitions} field.  For instance, to add the North
+Frisian locale for Germany, the value of that field may be:
+
+@example
+(cons (locale-definition
+        (name "fy_DE.utf8") (source "fy_DE"))
+      %default-locale-definitions)
+@end example
+
+Likewise, to save space, one might want @code{locale-definitions} to
+list only the locales that are actually used, as in:
+
+@example
+(list (locale-definition
+        (name "ja_JP.eucjp") (source "ja_JP")
+        (charset "EUC-JP")))
+@end example
+
+The @code{locale-definition} form is provided by the @code{(gnu system
+locale)} module.  Details are given below.
+
+@deftp {Data Type} locale-definition
+This is the data type of a locale definition.
+
+@table @asis
+
+@item @code{name}
+The name of the locale.  @xref{Locale Names,,, libc, The GNU C Library
+Reference Manual}, for more information on locale names.
+
+@item @code{source}
+The name of the source for that locale.  This is typically the
+@code{@var{language}_@var{territory}} part of the locale name.
+
+@item @code{charset} (default: @code{"UTF-8"})
+The ``character set'' or ``code set'' for that locale,
+@uref{http://www.iana.org/assignments/character-sets, as defined by
+IANA}.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %default-locale-definitions
+An arbitrary list of commonly used locales, used as the default value of
+the @code{locale-definitions} field of @code{operating-system}
+declarations.
+@end defvr
 
 @node Services
 @subsection Services
@@ -3780,7 +4077,7 @@ system, you will want to append services to @var{%base-services}, like
 this:
 
 @example
-(cons* (avahi-service) (lshd-service) %base-services)
+(cons* (avahi-service) (lsh-service) %base-services)
 @end example
 @end defvr
 
@@ -3843,7 +4140,7 @@ Run @var{udev}, which populates the @file{/dev} directory dynamically.
 @node Networking Services
 @subsubsection Networking Services
 
-The @code{(gnu system networking)} module provides services to configure
+The @code{(gnu services networking)} module provides services to configure
 the network interface.
 
 @cindex DHCP, networking service
@@ -3892,7 +4189,7 @@ In addition, @var{extra-settings} specifies a string to append to the
 configuration file.
 @end deffn
 
-Furthermore, @code{(gnu system ssh)} provides the following service.
+Furthermore, @code{(gnu services ssh)} provides the following service.
 
 @deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
        [#:interfaces '()] [#:port-number 22] @
@@ -3908,12 +4205,17 @@ When @var{initialize?} is true, automatically create the seed and host key
 upon service activation if they do not exist yet.  This may take long and
 require interaction.
 
+When @var{initialize?} is false, it is up to the user to initialize the
+randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
+a key pair with the private key stored in file @var{host-key} (@pxref{lshd
+basics,,, lsh, LSH Manual}).
+
 When @var{interfaces} is empty, lshd listens for connections on all the
 network interfaces; otherwise, @var{interfaces} must be a list of host names
 or addresses.
 
-@var{allow-empty-passwords?} specifies whether to accepts log-ins with empty
-passwords, and @var{root-login?} specifies whether to accepts log-ins as
+@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
+passwords, and @var{root-login?} specifies whether to accept log-ins as
 root.
 
 The other options should be self-descriptive.
@@ -3957,7 +4259,9 @@ there is no @code{xorg-service} procedure.  Instead, the X server is
 started by the @dfn{login manager}, currently SLiM.
 
 @deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
-  [#:auto-login? #f] [#:default-user ""] [#:startx]
+  [#:auto-login? #f] [#:default-user ""] [#:startx] @
+  [#:theme @var{%default-slim-theme}] @
+  [#:theme-name @var{%default-slim-theme-name}]
 Return a service that spawns the SLiM graphical login manager, which in
 turn starts the X display server with @var{startx}, a command as returned by
 @code{xorg-start-command}.
@@ -3965,8 +4269,18 @@ turn starts the X display server with @var{startx}, a command as returned by
 When @var{allow-empty-passwords?} is true, allow logins with an empty
 password.  When @var{auto-login?} is true, log in automatically as
 @var{default-user}.
+
+If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
+@var{theme} must be a gexp denoting the name of a directory containing the
+theme to use.  In that case, @var{theme-name} specifies the name of the
+theme.
 @end deffn
 
+@defvr {Scheme Variable} %default-theme
+@defvrx {Scheme Variable} %default-theme-name
+The G-Expression denoting the default SLiM theme and its name.
+@end defvr
+
 @deffn {Monadic Procedure} xorg-start-command [#:guile] @
   [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
 Return a derivation that builds a @var{guile} script to start the X server
@@ -4207,6 +4521,13 @@ It also adds a GRUB menu entry for the new OS configuration, and moves
 entries for older configurations to a submenu---unless
 @option{--no-grub} is passed.
 
+@c The paragraph below refers to the problem discussed at
+@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
+It is highly recommended to run @command{guix pull} once before you run
+@command{guix system reconfigure} for the first time (@pxref{Invoking
+guix pull}).  Failing to do that you would see an older version of Guix
+once @command{reconfigure} has completed.
+
 @item build
 Build the operating system's derivation, which includes all the
 configuration files and programs needed to boot and run the system.
@@ -4232,12 +4553,27 @@ This command also installs GRUB on the device specified in
 
 @item vm
 @cindex virtual machine
+@cindex VM
 Build a virtual machine that contain the operating system declared in
 @var{file}, and return a script to run that virtual machine (VM).
 Arguments given to the script are passed as is to QEMU.
 
 The VM shares its store with the host system.
 
+Additional file systems can be shared between the host and the VM using
+the @code{--share} and @code{--expose} command-line options: the former
+specifies a directory to be shared with write access, while the latter
+provides read-only access to the shared directory.
+
+The example below creates a VM in which the user's home directory is
+accessible read-only, and where the @file{/exchange} directory is a
+read-write mapping of the host's @file{$HOME/tmp}:
+
+@example
+guix system vm my-config.scm \
+   --expose=$HOME --share=$HOME/tmp=/exchange
+@end example
+
 On GNU/Linux, the default is to boot directly to the kernel; this has
 the advantage of requiring only a very tiny root disk image since the
 host's store can then be mounted.
@@ -4515,7 +4851,7 @@ each package is built based solely on other packages in the
 distribution.  The root of this dependency graph is a small set of
 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
 bootstrap)} module.  For more information on bootstrapping,
-@ref{Bootstrapping}.
+@pxref{Bootstrapping}.
 
 @node Packaging Guidelines
 @section Packaging Guidelines
@@ -4540,7 +4876,7 @@ for each package we define a variable bound to the package definition,
 and export that variable from a module (@pxref{Package Modules}).
 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
 creating packages.  For more information on package definitions,
-@ref{Defining Packages}.
+@pxref{Defining Packages}.
 
 Once a package definition is in place, stored in a file in the Guix
 source tree, it can be tested using the @command{guix build} command
@@ -4569,7 +4905,7 @@ Once your package builds correctly, please send us a patch
 (@pxref{Contributing}).  Well, if you need help, we will be happy to
 help you too.  Once the patch is committed in the Guix repository, the
 new package automatically gets built on the supported platforms by
-@url{http://hydra.gnu.org/gnu/master, our continuous integration
+@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
 system}.
 
 @cindex substituter
@@ -4587,6 +4923,7 @@ needed is to review and apply the patch.
 * Version Numbers::      When the name is not enough.
 * Python Modules::       Taming the snake.
 * Perl Modules::         Little pearls.
+* Fonts::                Fond of fonts.
 @end menu
 
 @node Software Freedom
@@ -4634,10 +4971,12 @@ hyphens.  For instance, GNUnet is available as @code{gnunet}, and
 SDL_net as @code{sdl-net}.
 
 We do not add @code{lib} prefixes for library packages, unless these are
-already part of the official project name.  But see @pxref{Python
+already part of the official project name.  But @pxref{Python
 Modules} and @ref{Perl Modules} for special rules concerning modules for
 the Python and Perl languages.
 
+Font package names are handled differently, @pxref{Fonts}.
+
 
 @node Version Numbers
 @subsection Version Numbers
@@ -4713,6 +5052,43 @@ are also prepended by @code{perl-}.  Such modules tend to have the word
 prefix.  For instance, @code{libwww-perl} becomes @code{perl-libwww}.
 
 
+@node Fonts
+@subsection Fonts
+
+For fonts that are in general not installed by a user for typesetting
+purposes, or that are distributed as part of a larger software package,
+we rely on the general packaging rules for software; for instance, this
+applies to the fonts delivered as part of the X.Org system or fonts that
+are part of TeX Live.
+
+To make it easier for a user to search for fonts, names for other packages
+containing only fonts are constructed as follows, independently of the
+upstream package name.
+
+The name of a package containing only one font family starts with
+@code{font-}; it is followed by the foundry name and a dash @code{-}
+if the foundry is known, and the font family name, in which spaces are
+replaced by dashes (and as usual, all upper case letters are transformed
+to lower case).
+For example, the Gentium font family by SIL is packaged under the name
+@code{font-sil-gentium}.
+
+For a package containing several font families, the name of the collection
+is used in the place of the font family name.
+For instance, the Liberation fonts consist of three families,
+Liberation Sans, Liberation Serif and Liberation Mono.
+These could be packaged separately under the names
+@code{font-liberation-sans} and so on; but as they are distributed together
+under a common name, we prefer to package them together as
+@code{font-liberation}.
+
+In the case where several formats of the same font family or font collection
+are packaged separately, a short form of the format, prepended by a dash,
+is added to the package name.  We use @code{-ttf} for TrueType fonts,
+@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
+fonts.
+
+
 
 @node Bootstrapping
 @section Bootstrapping
@@ -4904,7 +5280,8 @@ details about contributions.
 @chapter Acknowledgments
 
 Guix is based on the Nix package manager, which was designed and
-implemented by Eelco Dolstra.  Nix pioneered functional package
+implemented by Eelco Dolstra, with contributions from other people (see
+the @file{nix/AUTHORS} file in Guix.)  Nix pioneered functional package
 management, and promoted unprecedented features, such as transactional
 package upgrades and rollbacks, per-user profiles, and referentially
 transparent build processes.  Without this work, Guix would not exist.
@@ -4912,6 +5289,13 @@ transparent build processes.  Without this work, Guix would not exist.
 The Nix-based software distributions, Nixpkgs and NixOS, have also been
 an inspiration for Guix.
 
+GNU@tie{}Guix itself is a collective work with contributions from a
+number of people.  See the @file{AUTHORS} file in Guix for more
+information on these fine people.  The @file{THANKS} file lists people
+who have helped by reporting bugs, taking care of the infrastructure,
+providing artwork and themes, making suggestions, and more---thank you!
+
+
 @c *********************************************************************
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License