Merge branch 'master' into master

NixOS · Feb 9, 2024 · 12be60d · 12be60d
2 parents 4bc6ba5 + 778512e
commit 12be60d
Show file tree

Hide file tree

Showing 35 changed files with 287 additions and 195 deletions.
diff --git a/README.md b/README.md
@@ -1,22 +1,20 @@
 # Nix Pills
 
-https://nixos.org/nixos/nix-pills/
+Available online as a [multi-page HTML](https://nixos.org/guides/nix-pills/) or an [e-book in EPUB format](https://nixos.org/guides/nix-pills/nix-pills.epub).
 
-## Development
+You can also build them locally:
+
+    nix-build release.nix -A html-split && firefox result/share/doc/nix-pills/index.html
 
- - List of Elements: http://tdg.docbook.org/tdg/5.2/chunk-part-d6252e15351.html
- - Tracking Issue: https://github.com/NixOS/nixpkgs/issues/27908
+Similarly, for an [EPUB](https://www.w3.org/publishing/epub32/) version, run:
 
-When starting a new Pill, comment on the tracking issue which one
-you're doing. If you need help, ask there. If you make progress but
-don't finish in one go, make a PR anyway! I'm trying to not edit
-things as I go, in order to not get bogged down.
+    nix-build release.nix -A epub && foliate result/share/doc/nix-pills/nix-pills.epub
 
-How I've built and tested:
+## Development
 
-`nix-build release.nix && firefox result/share/doc/nix-pills/index.html`
+ - [List of DocBook Elements](https://tdg.docbook.org/tdg/5.2/part2.html)
 
-Emacs config for a nice docbook experience:
+Emacs config for a nice DocBook experience:
 
  ```nix
  let

diff --git a/book.xml b/book.xml
@@ -28,6 +28,9 @@
       contributors in 2017.
     </para>
 
+    <para>
+      For an up-to-date version, please visit <link xlink:href="https://nixos.org/guides/nix-pills/" />. An <link xlink:href="https://nixos.org/guides/nix-pills/nix-pills.epub">EPUB version</link> is also available.
+    </para>
 
     <para>If you encounter problems, please report them on the
     <link xlink:href="https://github.com/NixOS/nix-pills/issues">nixos/nix-pills</link>

diff --git a/default.nix b/default.nix
@@ -29,7 +29,7 @@ let
       cd sources
 
       printf "%s-%s" "$revCount" "$shortRev" > version
-      xmllint --xinclude --output $out ./book.xml
+      xmllint --xinclude --output "$out" ./book.xml
     '';
 
   toc = builtins.toFile "toc.xml"
@@ -53,34 +53,97 @@ let
     "--param chunk.first.sections 1"
     "--param use.id.as.filename 1"
     "--stringparam generate.toc 'book toc appendix toc'"
-    "--stringparam chunk.toc ${toc}"
+    "--stringparam chunk.toc '${toc}'"
   ];
 
-in pkgs.stdenv.mkDerivation {
-  name = "nix-pills";
+in {
+  html-split = pkgs.stdenv.mkDerivation {
+    name = "nix-pills";
 
-  src = sources;
-  buildInputs = with pkgs; [ jing libxslt ];
+    src = sources;
 
-  installPhase = ''
-    jing ${pkgs.docbook5}/xml/rng/docbook/docbook.rng $combined
+    buildInputs = with pkgs; [
+      libxslt
+    ];
 
-    # Generate the HTML manual.
-    dst=$out/share/doc/nix-pills
-    mkdir -p $dst
-    xsltproc \
-      ${manualXsltprocOptions} \
-      --nonet --output $dst/ \
-      ${pkgs.docbook-xsl-ns}/xml/xsl/docbook/xhtml/chunk.xsl \
-      ${combined}
+    installPhase = ''
+      runHook preInstall
 
-    mkdir -p $dst/images
-    cp -r ${pkgs.docbook-xsl-ns}/xml/xsl/docbook/images/callouts $dst/images/callouts
+      # Generate the HTML manual.
+      dst=$out/share/doc/nix-pills
+      mkdir -p "$dst"
+      xsltproc \
+        ${manualXsltprocOptions} \
+        --nonet --output "$dst/" \
+        "${pkgs.docbook-xsl-ns}/xml/xsl/docbook/xhtml/chunk.xsl" \
+        "${combined}"
 
-    cp ${./style.css} $dst/style.css
+      mkdir -p "$dst/images/callouts"
+      cp -r "${pkgs.docbook-xsl-ns}/xml/xsl/docbook/images/callouts"/*.svg "$dst/images/callouts"
 
-    mkdir -p $out/nix-support
-    echo "nix-build out $out" >> $out/nix-support/hydra-build-products
-    echo "doc nix-pills $dst" >> $out/nix-support/hydra-build-products
-  '';
+      cp "${./style.css}" "$dst/style.css"
+
+      mkdir -p "$out/nix-support"
+      echo "nix-build out $out" >> "$out/nix-support/hydra-build-products"
+      echo "doc nix-pills $dst" >> "$out/nix-support/hydra-build-products"
+
+      runHook postInstall
+    '';
+  };
+
+  epub = pkgs.stdenv.mkDerivation {
+    name = "nix-pills-epub";
+
+    src = sources;
+
+    buildInputs = with pkgs; [
+      libxslt
+      zip
+    ];
+
+    installCheckInputs = with pkgs; [
+      epubcheck
+    ];
+
+    doInstallCheck = true;
+
+    installPhase = ''
+      runHook preInstall
+
+      # Generate the EPUB manual.
+      dst=$out/share/doc/nix-pills
+      mkdir -p "$dst"
+      xsltproc \
+        ${manualXsltprocOptions} \
+        --nonet --output "$dst/epub/" \
+        "${pkgs.docbook-xsl-ns}/xml/xsl/docbook/epub3/chunk.xsl" \
+        "${combined}"
+
+      mkdir -p "$dst/epub/OEBPS/images/callouts"
+      cp -r "${pkgs.docbook-xsl-ns}/xml/xsl/docbook/images/callouts"/*.svg "$dst/epub/OEBPS/images/callouts"
+      cp "${./style.css}" "$dst/epub/OEBPS/style.css"
+
+      echo "application/epub+zip" > mimetype
+      manual="$dst/nix-pills.epub"
+      zip -0Xq "$manual" mimetype
+      pushd "$dst/epub" && zip -Xr9D "$manual" *
+      popd
+
+      rm -rf "$dst/epub"
+
+      mkdir -p "$out/nix-support"
+      echo "nix-build out $out" >> "$out/nix-support/hydra-build-products"
+      echo "doc-epub nix-pills $manual" >> "$out/nix-support/hydra-build-products"
+
+      runHook postInstall
+    '';
+
+    installCheckPhase = ''
+      runHook preInstallCheck
+
+      epubcheck "$manual"
+
+      runHook postInstallCheck
+    '';
+  };
 }
diff --git a/pills/02-install-on-your-running.xml b/pills/02-install-on-your-running.xml
@@ -21,22 +21,14 @@
   </para>
 
   <para>
-     <link xlink:href="https://nixos.org/manual/nix/stable/installation/installation.html">Installing
-     Nix</link> is as easy as installing any other package.
-     It will not drastically change our system, it will stay out of our way.
+     For installation instructions, please refer to the Nix Reference Manual on
+     <link xlink:href="https://nixos.org/manual/nix/stable/installation/installation.html">
+     Installing Nix</link>.
   </para>
 
   <section>
     <title>Installation</title>
 
-    <para>
-      To install Nix, run <command>curl -L https://nixos.org/nix/install | sh</command>
-      as a non-root user and follow the instructions. Alternatively, you may
-      prefer to download the installation script and verify its integrity using
-      GPG signatures. Instructions for doing so can be found here: <link
-      xlink:href="https://nixos.org/nix/download.html">https://nixos.org/nix/download.html</link>.
-    </para>
-
     <para>
       These articles are not a tutorial on <emphasis>using</emphasis> Nix.
       Instead, we're going to walk through the Nix system to understand the fundamentals.
@@ -200,10 +192,9 @@
     parse="text" /></screen>
 
     <para>
-      <link
-          xlink:href="https://nixos.org/manual/nix/stable/expressions/writing-nix-expressions.html">Nix
-      expressions</link> are used to describe packages and how to
-      build them. <link
+      Nix expressions are written in the <link 
+      xlink:href="https://nix.dev/tutorials/nix-language">Nix language</link> and used to 
+      describe packages and how to build them. <link 
       xlink:href="https://nixos.org/nixpkgs/">Nixpkgs</link> is the
       repository containing all of the expressions: <link
       xlink:href="https://github.com/NixOS/nixpkgs">https://github.com/NixOS/nixpkgs</link>.

diff --git a/pills/06-our-first-derivation.xml b/pills/06-our-first-derivation.xml
@@ -42,7 +42,7 @@
   </para>
 
   <para>
-    The <code>derivation</code> function receives a set as first argument. This
+    The <code>derivation</code> function receives a set as its first argument. This
     set requires at least the following three attributes:
   </para>
 
@@ -61,7 +61,7 @@
     </listitem>
     <listitem>
       <para>
-        builder: it is the binary program that builds the derivation.
+        builder: is the binary program that builds the derivation.
       </para>
     </listitem>
   </itemizedlist>
@@ -101,19 +101,19 @@
   <itemizedlist mark='bullet'>
     <listitem>
       <para>
-        <filename>.nix</filename> files are like <filename>.c</filename> files
+        <filename>.nix</filename> files are like <filename>.c</filename> files.
       </para>
     </listitem>
     <listitem>
       <para>
         <filename>.drv</filename> files are intermediate files like
         <filename>.o</filename> files. The <filename>.drv</filename> describes
-        how to build a derivation, it's the bare minimum information.
+        how to build a derivation; it's the bare minimum information.
       </para>
     </listitem>
     <listitem>
       <para>
-        out paths are then the product of the build
+        out paths are then the product of the build.
       </para>
     </listitem>
   </itemizedlist>
@@ -127,18 +127,21 @@
     better to pretty print it:
   </para>
 
-  <xi:include href="./06/show-derivation.xml" />
+  <note><para>
+      If your version of nix doesn't have <literal>nix derivation show</literal>, use <literal>nix show-derivation</literal> instead.
+  </para></note>
 
+  <xi:include href="./06/show-derivation.xml" />
 
   <para>
-    Ok we can see there's an out path, but it does not exist yet. We never told
+    Ok, we can see there's an out path, but it does not exist yet. We never told
     Nix to build it, but we know beforehand where the build output will be. Why?
   </para>
 
   <para>
     Think, if Nix ever built the derivation just because we accessed it in Nix,
     we would have to wait a long time if it was, say, Firefox. That's why Nix
-    let us know the path beforehand and keep evaluating the Nix expressions, but
+    let us know the path beforehand and kept evaluating the Nix expressions, but
     it's still empty because no build was ever made.
   </para>
 
@@ -252,7 +255,7 @@
   <screen><xi:include href="./06/inspect-values.txt" parse="text" /></screen>
 
   <para>
-    You can guess what <code>builtins.isAttrs</code> does, it returns true if
+    You can guess what <code>builtins.isAttrs</code> does; it returns true if
     the argument is a set. While <code>builtins.attrNames</code> returns a list
     of keys of the given set. Some kind of reflection, you might say.
   </para>
@@ -264,9 +267,9 @@
   <screen><xi:include href="./06/drvattrs.txt" parse="text" /></screen>
 
   <para>
-    That's basically the input we gave to the derivation function. Also
+    That's basically the input we gave to the derivation function. Also the
     <code>d.name</code>, <code>d.system</code> and <code>d.builder</code>
-    attributes are straight the ones we gave as input.
+    attributes are exactly the ones we gave as input.
   </para>
 
   <screen><xi:include href="./06/check-drvattrs.txt" parse="text" /></screen>
@@ -286,7 +289,7 @@
   <para>
     Something interesting is the <code>type</code> attribute. It's
     <code>"derivation"</code>. Nix does add a little of magic to sets with type
-    derivation, but not that much. To let you understand, you can create
+    derivation, but not that much. To help you understand, you can create
     yourself a set with that type, it's a simple set:
   </para>
 
@@ -304,7 +307,7 @@
   </para>
 
   <para>
-    The outPath attribute is the build path in the nix store:
+    The <code>outPath</code> attribute is the build path in the nix store:
     <filename>/nix/store/40s0qmrfb45vlh6610rk29ym318dswdr-<emphasis
     role="strong">myname</emphasis></filename>.
   </para>
@@ -317,9 +320,9 @@
   <para>
     Just like dependencies in other package managers, how do we refer to other
     packages? How do we refer to other derivations in terms of files on the
-    disk? We use the outPath. The outPath tells where the files are of that
-    derivation. To make it more convenient, Nix is able to do a conversion from
-    a derivation set to a string.
+    disk? We use the <code>outPath</code>. The <code>outPath</code> describes 
+    the location of the files of that derivation. To make it more convenient, 
+    Nix is able to do a conversion from a derivation set to a string.
   </para>
 
   <screen><xi:include href="./06/outpath.txt" parse="text" /></screen>
@@ -457,7 +460,7 @@
   <title>Conclusion</title>
 
   <para>
-    Is it that complicated to create a package for Nix? No it's not.
+    Is it that complicated to create a package for Nix? No, it's not.
   </para>
 
   <para>
@@ -469,8 +472,8 @@
   <para>
     With the derivation function we provide a set of information on how to build
     a package, and we get back the information about where the package was
-    built. Nix converts a set to a string when there's an outPath, that's very
-    convenient. With that, it's easy to refer to other derivations.
+    built. Nix converts a set to a string when there's an <code>outPath</code>; 
+    that's very convenient. With that, it's easy to refer to other derivations.
   </para>
 
   <para>

diff --git a/pills/06/examine-build.xml b/pills/06/examine-build.xml
@@ -1,4 +1,4 @@
-<screen xmlns="http://docbook.org/ns/docbook"><prompt>$ </prompt><userinput>nix show-derivation /nix/store/qyfrcd53wmc0v22ymhhd5r6sz5xmdc8a-<emphasis>myname.drv</emphasis></userinput>
+<screen xmlns="http://docbook.org/ns/docbook"><prompt>$ </prompt><userinput>nix derivation show /nix/store/qyfrcd53wmc0v22ymhhd5r6sz5xmdc8a-<emphasis>myname.drv</emphasis></userinput>
 <computeroutput>{
   "/nix/store/qyfrcd53wmc0v22ymhhd5r6sz5xmdc8a-myname.drv": {
     "outputs": {

diff --git a/pills/06/show-derivation.xml b/pills/06/show-derivation.xml
@@ -1,4 +1,4 @@
-<screen xmlns="http://docbook.org/ns/docbook"><prompt>$ </prompt><userinput>nix show-derivation /nix/store/z3hhlxbckx4g3n9sw91nnvlkjvyw754p-<emphasis>myname.drv</emphasis></userinput>
+<screen xmlns="http://docbook.org/ns/docbook"><prompt>$ </prompt><userinput>nix derivation show /nix/store/z3hhlxbckx4g3n9sw91nnvlkjvyw754p-<emphasis>myname.drv</emphasis></userinput>
 <computeroutput>{
   "/nix/store/z3hhlxbckx4g3n9sw91nnvlkjvyw754p-myname.drv": {
     "outputs": {