doc/stdenv: document meson variables

3 files changed, 237 insertions, 114 deletions

diff --git a/doc/languages-frameworks/gnome.xml b/doc/languages-frameworks/gnome.xml
index 9e0f21a6c74fc..42b4ae04322ff 100644
--- a/doc/languages-frameworks/gnome.xml
+++ b/doc/languages-frameworks/gnome.xml
@@ -5,26 +5,53 @@
   <title>Packaging GNOME applications</title>
 
   <para>
-   Programs in the GNOME universe are written in various languages but they all use GObject-based libraries like GLib, GTK or GStreamer. These libraries are often modular, relying on looking into certain directories to find their modules. However, due to Nix’s specific file system organization, this will fail without our intervention. Fortunately, the libraries usually allow overriding the directories through environment variables, either natively or thanks to a patch in nixpkgs. <link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to ensure correct paths are available to the application constitutes a significant part of packaging a modern desktop application. In this section, we will describe various modules needed by such applications, environment variables needed to make the modules load, and finally a script that will do the work for us.
+   Programs in the GNOME universe are written in various languages but they all
+   use GObject-based libraries like GLib, GTK or GStreamer. These libraries are
+   often modular, relying on looking into certain directories to find their
+   modules. However, due to Nix’s specific file system organization, this
+   will fail without our intervention. Fortunately, the libraries usually allow
+   overriding the directories through environment variables, either natively or
+   thanks to a patch in nixpkgs.
+   <link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to
+   ensure correct paths are available to the application constitutes a
+   significant part of packaging a modern desktop application. In this section,
+   we will describe various modules needed by such applications, environment
+   variables needed to make the modules load, and finally a script that will do
+   the work for us.
   </para>
 
   <section xml:id="ssec-gnome-settings">
    <title>Settings</title>
 
    <para>
-    <link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link> API is often used for storing settings. GSettings schemas are required, to know the type and other metadata of the stored values. GLib looks for <filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the directories of <envar>XDG_DATA_DIRS</envar>.
+    <link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>
+    API is often used for storing settings. GSettings schemas are required, to
+    know the type and other metadata of the stored values. GLib looks for
+    <filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the
+    directories of <envar>XDG_DATA_DIRS</envar>.
    </para>
 
    <para>
-    On Linux, GSettings API is implemented using <link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link> backend. You will need to add <literal>dconf</literal> GIO module to <envar>GIO_EXTRA_MODULES</envar> variable, otherwise the <literal>memory</literal> backend will be used and the saved settings will not be persistent.
+    On Linux, GSettings API is implemented using
+    <link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link>
+    backend. You will need to add <literal>dconf</literal> GIO module to
+    <envar>GIO_EXTRA_MODULES</envar> variable, otherwise the
+    <literal>memory</literal> backend will be used and the saved settings will
+    not be persistent.
    </para>
 
    <para>
-    Last you will need the dconf database D-Bus service itself. You can enable it using <option>programs.dconf.enable</option>.
+    Last you will need the dconf database D-Bus service itself. You can enable
+    it using <option>programs.dconf.enable</option>.
    </para>
 
    <para>
-    Some applications will also require <package>gsettings-desktop-schemas</package> for things like reading proxy configuration or user interface customization. This dependency is often not mentioned by upstream, you should grep for <literal>org.gnome.desktop</literal> and <literal>org.gnome.system</literal> to see if the schemas are needed.
+    Some applications will also require
+    <package>gsettings-desktop-schemas</package> for things like reading proxy
+    configuration or user interface customization. This dependency is often not
+    mentioned by upstream, you should grep for
+    <literal>org.gnome.desktop</literal> and
+    <literal>org.gnome.system</literal> to see if the schemas are needed.
    </para>
   </section>
 
@@ -32,7 +59,16 @@
    <title>Icons</title>
 
    <para>
-    When an application uses icons, an icon theme should be available in <envar>XDG_DATA_DIRS</envar>. The package for the default, icon-less <link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link> contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup hook</link> that will pick up icon themes from <literal>buildInputs</literal> and pass it to our wrapper. Unfortunately, relying on that would mean every user has to download the theme included in the package expression no matter their preference. For that reason, we leave the installation of icon theme on the user. If you use one of the desktop environments, you probably already have an icon theme installed.
+    When an application uses icons, an icon theme should be available in
+    <envar>XDG_DATA_DIRS</envar>. The package for the default, icon-less
+    <link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link>
+    contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup
+    hook</link> that will pick up icon themes from
+    <literal>buildInputs</literal> and pass it to our wrapper. Unfortunately,
+    relying on that would mean every user has to download the theme included in
+    the package expression no matter their preference. For that reason, we
+    leave the installation of icon theme on the user. If you use one of the
+    desktop environments, you probably already have an icon theme installed.
    </para>
   </section>
 
@@ -40,7 +76,12 @@
    <title>GTK Themes</title>
 
    <para>
-    Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for <link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary HIG</link>) might require a special theme like <package>pantheon.elementary-gtk-theme</package>.
+    Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This
+    is no longer necessary for most programs since GTK incorporated Adwaita
+    theme. Some programs (for example, those designed for
+    <link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary
+    HIG</link>) might require a special theme like
+    <package>pantheon.elementary-gtk-theme</package>.
    </para>
   </section>
 
@@ -48,7 +89,10 @@
    <title>GObject introspection typelibs</title>
 
    <para>
-    <link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject introspection</link> allows applications to use C libraries in other languages easily. It does this through <literal>typelib</literal> files searched in <envar>GI_TYPELIB_PATH</envar>.
+    <link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject
+    introspection</link> allows applications to use C libraries in other
+    languages easily. It does this through <literal>typelib</literal> files
+    searched in <envar>GI_TYPELIB_PATH</envar>.
    </para>
   </section>
 
@@ -56,7 +100,11 @@
    <title>Various plug-ins</title>
 
    <para>
-    If your application uses <link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or <link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar>, respectively.
+    If your application uses
+    <link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or
+    <link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you
+    should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and
+    <envar>GRL_PLUGIN_PATH</envar>, respectively.
    </para>
   </section>
  </section>
@@ -65,7 +113,8 @@
   <title>Onto <package>wrapGAppsHook</package></title>
 
   <para>
-   Given the requirements above, the package expression would become messy quickly:
+   Given the requirements above, the package expression would become messy
+   quickly:
 <programlisting>
 preFixup = ''
   for f in $(find $out/bin/ $out/libexec/ -type f -executable); do
@@ -79,48 +128,76 @@ preFixup = ''
   done
 '';
 </programlisting>
-   Fortunately, there is <package>wrapGAppsHook</package>, that does the wrapping for us. In particular, it works in conjunction with other setup hooks that will populate the variable:
+   Fortunately, there is <package>wrapGAppsHook</package>, that does the
+   wrapping for us. In particular, it works in conjunction with other setup
+   hooks that will populate the variable:
    <itemizedlist>
     <listitem xml:id="ssec-gnome-hooks-wrapgappshook">
      <para>
-      <package>wrapGAppsHook</package> itself will add the package’s <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>.
+      <package>wrapGAppsHook</package> itself will add the package’s
+      <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-glib">
      <para>
-      <package>glib</package> setup hook will populate <envar>GSETTINGS_SCHEMAS_PATH</envar> and then <package>wrapGAppsHook</package> will prepend it to <envar>XDG_DATA_DIRS</envar>.
+      <package>glib</package> setup hook will populate
+      <envar>GSETTINGS_SCHEMAS_PATH</envar> and then
+      <package>wrapGAppsHook</package> will prepend it to
+      <envar>XDG_DATA_DIRS</envar>.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-dconf">
      <para>
-      <package>gnome3.dconf.lib</package> is a dependency of <package>wrapGAppsHook</package>, which then also adds it to the <envar>GIO_EXTRA_MODULES</envar> variable.
+      <package>gnome3.dconf.lib</package> is a dependency of
+      <package>wrapGAppsHook</package>, which then also adds it to the
+      <envar>GIO_EXTRA_MODULES</envar> variable.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-hicolor-icon-theme">
      <para>
-      <package>hicolor-icon-theme</package>’s setup hook will add icon themes to <envar>XDG_ICON_DIRS</envar> which is prepended to <envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>.
+      <package>hicolor-icon-theme</package>’s setup hook will add icon themes
+      to <envar>XDG_ICON_DIRS</envar> which is prepended to
+      <envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>.
      </para>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-gobject-introspection">
      <para>
-      <package>gobject-introspection</package> setup hook populates <envar>GI_TYPELIB_PATH</envar> variable with <filename>lib/girepository-1.0</filename> directories of dependencies, which is then added to wrapper by <package>wrapGAppsHook</package>. It also adds <filename>share</filename> directories of dependencies to <envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but it also <link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes the closures</link> of packages using <package>wrapGAppsHook</package>.
+      <package>gobject-introspection</package> setup hook populates
+      <envar>GI_TYPELIB_PATH</envar> variable with
+      <filename>lib/girepository-1.0</filename> directories of dependencies,
+      which is then added to wrapper by <package>wrapGAppsHook</package>. It
+      also adds <filename>share</filename> directories of dependencies to
+      <envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but
+      it also
+      <link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes
+      the closures</link> of packages using <package>wrapGAppsHook</package>.
      </para>
      <warning>
       <para>
-       The setup hook <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link> does not work in expressions with <literal>strictDeps</literal> enabled, like Python packages. In those cases, you will need to disable it with <code>strictDeps = false;</code>.
+       The setup hook
+       <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link>
+       does not work in expressions with <literal>strictDeps</literal> enabled,
+       like Python packages. In those cases, you will need to disable it with
+       <code>strictDeps = false;</code>.
       </para>
      </warning>
     </listitem>
     <listitem xml:id="ssec-gnome-hooks-gst-grl-plugins">
      <para>
-      Setup hooks of <package>gst_all_1.gstreamer</package> and <package>gnome3.grilo</package> will populate the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then be added to the wrapper by <literal>wrapGAppsHook</literal>.
+      Setup hooks of <package>gst_all_1.gstreamer</package> and
+      <package>gnome3.grilo</package> will populate the
+      <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and
+      <envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then
+      be added to the wrapper by <literal>wrapGAppsHook</literal>.
      </para>
     </listitem>
    </itemizedlist>
   </para>
 
   <para>
-   You can also pass additional arguments to <literal>makeWrapper</literal> using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal> hook:
+   You can also pass additional arguments to <literal>makeWrapper</literal>
+   using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal>
+   hook:
 <programlisting>
 preFixup = ''
   gappsWrapperArgs+=(
@@ -138,7 +215,13 @@ preFixup = ''
   <title>Updating GNOME packages</title>
 
   <para>
-   Most GNOME package offer <link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>, it is therefore possible to update to latest source tarball by running <command>nix-shell maintainers/scripts/update.nix --argstr package gnome3.nautilus</command> or even en masse with <command>nix-shell maintainers/scripts/update.nix --argstr path gnome3</command>. Read the package’s <filename>NEWS</filename> file to see what changed.
+   Most GNOME package offer
+   <link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>,
+   it is therefore possible to update to latest source tarball by running
+   <command>nix-shell maintainers/scripts/update.nix --argstr package
+   gnome3.nautilus</command> or even en masse with <command>nix-shell
+   maintainers/scripts/update.nix --argstr path gnome3</command>. Read the
+   package’s <filename>NEWS</filename> file to see what changed.
   </para>
  </section>
 
@@ -152,7 +235,17 @@ preFixup = ''
     </term>
     <listitem>
      <para>
-      There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>. Temporarily add a random package containing schemas like <package>gsettings-desktop-schemas</package> to <literal>buildInputs</literal>. <link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and <link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link> setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the <link linkend="ssec-gnome-common-issues-missing-schema">next error</link>. Or you can try looking through the source code for the actual schemas used.
+      There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>.
+      Temporarily add a random package containing schemas like
+      <package>gsettings-desktop-schemas</package> to
+      <literal>buildInputs</literal>.
+      <link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and
+      <link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link>
+      setup hooks will take care of making the schemas available to application
+      and you will see the actual missing schemas with the
+      <link linkend="ssec-gnome-common-issues-missing-schema">next
+      error</link>. Or you can try looking through the source code for the
+      actual schemas used.
      </para>
     </listitem>
    </varlistentry>
@@ -162,7 +255,11 @@ preFixup = ''
     </term>
     <listitem>
      <para>
-      Package is missing some GSettings schemas. You can find out the package containing the schema with <command>nix-locate <replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let the hooks handle the wrapping as <link linkend="ssec-gnome-common-issues-no-schemas">above</link>.
+      Package is missing some GSettings schemas. You can find out the package
+      containing the schema with <command>nix-locate
+      <replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let
+      the hooks handle the wrapping as
+      <link linkend="ssec-gnome-common-issues-no-schemas">above</link>.
      </para>
     </listitem>
    </varlistentry>
@@ -172,7 +269,14 @@ preFixup = ''
     </term>
     <listitem>
      <para>
-      This is because derivers like <function>python.pkgs.buildPythonApplication</function> or <function>qt5.mkDerivation</function> have setup-hooks automatically added that produce wrappers with <package>makeWrapper</package>. The simplest way to workaround that is to disable the <package>wrapGAppsHook</package> automatic wrapping with <code>dontWrapGApps = true;</code> and pass the arguments it intended to pass to <package>makeWrapper</package> to another.
+      This is because derivers like
+      <function>python.pkgs.buildPythonApplication</function> or
+      <function>qt5.mkDerivation</function> have setup-hooks automatically
+      added that produce wrappers with <package>makeWrapper</package>. The
+      simplest way to workaround that is to disable the
+      <package>wrapGAppsHook</package> automatic wrapping with
+      <code>dontWrapGApps = true;</code> and pass the arguments it intended to
+      pass to <package>makeWrapper</package> to another.
      </para>
      <para>
       In the case of a Python application it could look like:
@@ -224,34 +328,55 @@ mkDerivation {
     </term>
     <listitem>
      <para>
-      You can rely on applications depending on the library set the necessary environment variables but that it often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
+      You can rely on applications depending on the library set the necessary
+      environment variables but that it often easy to miss. Instead we
+      recommend to patch the paths in the source code whenever possible. Here
+      are some examples:
       <itemizedlist>
        <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext">
         <para>
-         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> – we are using <function>substituteAll</function> to include the path to a typelib into a patch.
+         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing
+         a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> –
+         we are using <function>substituteAll</function> to include the path to
+         a typelib into a patch.
         </para>
        </listitem>
        <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings">
         <para>
-         The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions
+         The following examples are hardcoding GSettings schema paths. To get
+         the schema paths we use the functions
          <itemizedlist>
           <listitem>
            <para>
-            <function>glib.getSchemaPath</function> Takes a nix package attribute as an argument.
+            <function>glib.getSchemaPath</function> Takes a nix package
+            attribute as an argument.
            </para>
           </listitem>
           <listitem>
            <para>
-            <function>glib.makeSchemaPath</function> Takes a package output like <literal>$out</literal> and a derivation name. You should use this if the schemas you need to hardcode are in the same derivation.
+            <function>glib.makeSchemaPath</function> Takes a package output
+            like <literal>$out</literal> and a derivation name. You should use
+            this if the schemas you need to hardcode are in the same
+            derivation.
            </para>
           </listitem>
          </itemizedlist>
         </para>
         <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-vala">
-         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library)</link> – here, <function>substituteAll</function> cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a <link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix bug</link>.
+         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding
+         GSettings schema path in Vala plug-in (dynamically loaded
+         library)</link> – here, <function>substituteAll</function> cannot be
+         used since the schema comes from the same package preventing us from
+         pass its path to the function, probably due to a
+         <link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix
+         bug</link>.
         </para>
         <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-c">
-         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding GSettings schema path in C library</link> – nothing special other than using <link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle patch</link> to generate the patch itself.
+         <link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding
+         GSettings schema path in C library</link> – nothing special other
+         than using
+         <link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle
+         patch</link> to generate the patch itself.
         </para>
        </listitem>
       </itemizedlist>
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
index 065212a0e1807..d5911cf67fd7b 100644
--- a/doc/languages-frameworks/perl.xml
+++ b/doc/languages-frameworks/perl.xml
@@ -141,8 +141,8 @@ ClassC3Componentised = buildPerlPackage rec {
  <para>
   On Darwin, if a script has too many
   <literal>-I<replaceable>dir</replaceable></literal> flags in its first line
-  (its “shebang line”), it will not run. This can be worked around by calling
-  the <literal>shortenPerlShebang</literal> function from the
+  (its “shebang line”), it will not run. This can be worked around by
+  calling the <literal>shortenPerlShebang</literal> function from the
   <literal>postInstall</literal> phase:
 <programlisting>
 { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
@@ -162,10 +162,10 @@ ImageExifTool = buildPerlPackage {
   '';
 };
 </programlisting>
- This will remove the <literal>-I</literal> flags from the shebang line,
- rewrite them in the <literal>use lib</literal> form, and put them on the next
- line instead. This function can be given any number of Perl scripts as
- arguments; it will modify them in-place.
+  This will remove the <literal>-I</literal> flags from the shebang line,
+  rewrite them in the <literal>use lib</literal> form, and put them on the next
+  line instead. This function can be given any number of Perl scripts as
+  arguments; it will modify them in-place.
  </para>
 
  <section xml:id="ssec-generation-from-CPAN">
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
index 3332ce8c06e42..d6f3314ab08db 100644
--- a/doc/languages-frameworks/qt.xml
+++ b/doc/languages-frameworks/qt.xml
@@ -4,16 +4,16 @@
  <title>Qt</title>
 
  <para>
-   This section describes the differences between Nix expressions for Qt
-   libraries and applications and Nix expressions for other C++ software. Some
-   knowledge of the latter is assumed. There are primarily two problems which
-   the Qt infrastructure is designed to address: ensuring consistent versioning
-   of all dependencies and finding dependencies at runtime.
+  This section describes the differences between Nix expressions for Qt
+  libraries and applications and Nix expressions for other C++ software. Some
+  knowledge of the latter is assumed. There are primarily two problems which
+  the Qt infrastructure is designed to address: ensuring consistent versioning
+  of all dependencies and finding dependencies at runtime.
  </para>
 
  <example xml:id='qt-default-nix'>
-   <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title>
-   <programlisting>
+  <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title>
+<programlisting>
 { mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
 
 mkDerivation { <co xml:id='qt-default-nix-co-2' />
@@ -26,53 +26,51 @@ mkDerivation { <co xml:id='qt-default-nix-co-2' />
  </example>
 
  <calloutlist>
-   <callout arearefs='qt-default-nix-co-1'>
-     <para>
-       Import <literal>mkDerivation</literal> and Qt (such as
-       <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis>
-       import Qt package sets; the Qt versions of dependencies may not be
-       coherent, causing build and runtime failures.
-     </para>
-   </callout>
-   <callout arearefs='qt-default-nix-co-2'>
-     <para>
-       Use <literal>mkDerivation</literal> instead of
-       <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal>
-       is a wrapper around <literal>stdenv.mkDerivation</literal> which
-       applies some Qt-specific settings.
-       This deriver accepts the same arguments as
-       <literal>stdenv.mkDerivation</literal>; refer to
-       <xref linkend='chap-stdenv' /> for details.
-     </para>
-     <para>
-       To use another deriver instead of
-       <literal>stdenv.mkDerivation</literal>, use
-       <literal>mkDerivationWith</literal>:
+  <callout arearefs='qt-default-nix-co-1'>
+   <para>
+    Import <literal>mkDerivation</literal> and Qt (such as
+    <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis>
+    import Qt package sets; the Qt versions of dependencies may not be
+    coherent, causing build and runtime failures.
+   </para>
+  </callout>
+  <callout arearefs='qt-default-nix-co-2'>
+   <para>
+    Use <literal>mkDerivation</literal> instead of
+    <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is
+    a wrapper around <literal>stdenv.mkDerivation</literal> which applies some
+    Qt-specific settings. This deriver accepts the same arguments as
+    <literal>stdenv.mkDerivation</literal>; refer to
+    <xref linkend='chap-stdenv' /> for details.
+   </para>
+   <para>
+    To use another deriver instead of <literal>stdenv.mkDerivation</literal>,
+    use <literal>mkDerivationWith</literal>:
 <programlisting>
 mkDerivationWith myDeriver {
   # ...
 }
 </programlisting>
-       If you cannot use <literal>mkDerivationWith</literal>, please refer to
-       <xref linkend='qt-runtime-dependencies' />.
-     </para>
-   </callout>
-   <callout arearefs='qt-default-nix-co-3'>
-     <para>
-       <literal>mkDerivation</literal> accepts the same arguments as
-       <literal>stdenv.mkDerivation</literal>, such as
-       <literal>buildInputs</literal>.
-     </para>
-   </callout>
+    If you cannot use <literal>mkDerivationWith</literal>, please refer to
+    <xref linkend='qt-runtime-dependencies' />.
+   </para>
+  </callout>
+  <callout arearefs='qt-default-nix-co-3'>
+   <para>
+    <literal>mkDerivation</literal> accepts the same arguments as
+    <literal>stdenv.mkDerivation</literal>, such as
+    <literal>buildInputs</literal>.
+   </para>
+  </callout>
  </calloutlist>
 
  <formalpara xml:id='qt-runtime-dependencies'>
-   <title>Locating runtime dependencies</title>
-   <para>
-     Qt applications need to be wrapped to find runtime dependencies.  If you
-     cannot use <literal>mkDerivation</literal> or
-     <literal>mkDerivationWith</literal> above, include
-     <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
+  <title>Locating runtime dependencies</title>
+  <para>
+   Qt applications need to be wrapped to find runtime dependencies. If you
+   cannot use <literal>mkDerivation</literal> or
+   <literal>mkDerivationWith</literal> above, include
+   <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
 <programlisting>
 stdenv.mkDerivation {
   # ...
@@ -80,13 +78,13 @@ stdenv.mkDerivation {
   nativeBuildInputs = [ wrapQtAppsHook ];
 }
 </programlisting>
-   </para>
+  </para>
  </formalpara>
 
  <para>
-   Entries added to <literal>qtWrapperArgs</literal> are used to modify the
-   wrappers created by <literal>wrapQtAppsHook</literal>. The entries are
-   passed as arguments to <xref linkend='fun-wrapProgram' />.
+  Entries added to <literal>qtWrapperArgs</literal> are used to modify the
+  wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed
+  as arguments to <xref linkend='fun-wrapProgram' />.
 <programlisting>
 mkDerivation {
   # ...
@@ -97,8 +95,8 @@ mkDerivation {
  </para>
 
  <para>
-  Set <literal>dontWrapQtApps</literal> to stop applications from being
-  wrapped automatically. It is required to wrap applications manually with
+  Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped
+  automatically. It is required to wrap applications manually with
   <literal>wrapQtApp</literal>, using the syntax of
   <xref linkend='fun-wrapProgram' />:
 <programlisting>
@@ -115,16 +113,17 @@ mkDerivation {
 
  <note>
   <para>
-    <literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables.
-    This means that scripts won't be automatically wrapped so you'll need to manually
-    wrap them as previously mentioned. An example of when you'd always need to do this
-    is with Python applications that use PyQT.
+   <literal>wrapQtAppsHook</literal> ignores files that are non-ELF
+   executables. This means that scripts won't be automatically wrapped so
+   you'll need to manually wrap them as previously mentioned. An example of
+   when you'd always need to do this is with Python applications that use PyQT.
   </para>
  </note>
 
  <para>
-  Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal>
-  attribute to disable the package for unsupported Qt versions:
+  Libraries are built with every available version of Qt. Use the
+  <literal>meta.broken</literal> attribute to disable the package for
+  unsupported Qt versions:
 <programlisting>
 mkDerivation {
   # ...
@@ -136,13 +135,13 @@ mkDerivation {
  </para>
 
  <formalpara>
-   <title>Adding a library to Nixpkgs</title>
-   <para>
-     Add a Qt library to <filename>all-packages.nix</filename> by adding it to the
-     collection inside <literal>mkLibsForQt5</literal>. This ensures that the
-     library is built with every available version of Qt as needed.
-     <example xml:id='qt-library-all-packages-nix'>
-       <title>Adding a Qt library to <filename>all-packages.nix</filename></title>
+  <title>Adding a library to Nixpkgs</title>
+  <para>
+   Add a Qt library to <filename>all-packages.nix</filename> by adding it to
+   the collection inside <literal>mkLibsForQt5</literal>. This ensures that the
+   library is built with every available version of Qt as needed.
+   <example xml:id='qt-library-all-packages-nix'>
+    <title>Adding a Qt library to <filename>all-packages.nix</filename></title>
 <programlisting>
 {
   # ...
@@ -156,19 +155,19 @@ mkDerivation {
   # ...
 }
 </programlisting>
-     </example>
-   </para>
+   </example>
+  </para>
  </formalpara>
 
  <formalpara>
-   <title>Adding an application to Nixpkgs</title>
-   <para>
-     Add a Qt application to <filename>all-packages.nix</filename> using
-     <literal>libsForQt5.callPackage</literal> instead of the usual
-     <literal>callPackage</literal>. The former ensures that all dependencies
-     are built with the same version of Qt.
-     <example xml:id='qt-application-all-packages-nix'>
-       <title>Adding a Qt application to <filename>all-packages.nix</filename></title>
+  <title>Adding an application to Nixpkgs</title>
+  <para>
+   Add a Qt application to <filename>all-packages.nix</filename> using
+   <literal>libsForQt5.callPackage</literal> instead of the usual
+   <literal>callPackage</literal>. The former ensures that all dependencies are
+   built with the same version of Qt.
+   <example xml:id='qt-application-all-packages-nix'>
+    <title>Adding a Qt application to <filename>all-packages.nix</filename></title>
 <programlisting>
 {
   # ...
@@ -178,8 +177,7 @@ mkDerivation {
   # ...
 }
 </programlisting>
-     </example>
-   </para>
+   </example>
+  </para>
  </formalpara>
-
 </section>