Convert from docbook to mdbook

.gitignore

@@ -1,2 +1,3 @@
 result
 result-*
+/book*

README.md

@@ -9,44 +9,3 @@ You can also build them locally:
 Similarly, for an [EPUB](https://www.w3.org/publishing/epub32/) version, run:
 
     nix-build release.nix -A epub && foliate result/share/doc/nix-pills/nix-pills.epub
-
-## Development
-
- - [List of DocBook Elements](https://tdg.docbook.org/tdg/5.2/part2.html)
-
-Emacs config for a nice DocBook experience:
-
- ```nix
- let
-  pkgs = import <nixpkgs> {};
-  inherit (pkgs) emacsPackagesNg docbook5 writeText;
-
-  schemas = writeText "schemas.xml" ''
-    <locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
-      <documentElement localName="section" typeId="DocBook"/>
-      <documentElement localName="chapter" typeId="DocBook"/>
-      <documentElement localName="article" typeId="DocBook"/>
-      <documentElement localName="book" typeId="DocBook"/>
-      <typeId id="DocBook" uri="${docbook5}/xml/rng/docbook/docbookxi.rnc" />
-    </locatingRules>
-  '';
-
-in emacsPackagesNg.emacsWithPackages (epkgs: [
-  (emacsPackagesNg.trivialBuild {
-    pname = "nix-docbook-mode";
-    version = "1970-01-01";
-    src = writeText "default.el" ''
-      (eval-after-load 'rng-loc
-        '(add-to-list 'rng-schema-locating-files "${schemas}"))
-      (global-set-key (kbd "<C-return>") 'nxml-complete)
-    '';
-  })
-])
-```
-
-Then you can use the keys:
-
-
- - `C-c C-b` to finish & close a tag
- - `C-c C-f` to close a tag
- - `C-return` to auto-complete a tag or attribute.

book.toml

@@ -0,0 +1,40 @@
+[book]
+title = "Nix Pills"
+authors = ["Luca Bruno"]
+language = "en"
+multilingual = false
+src = "pills"
+
+[output.html]
+additional-css = ["custom.css"]
+edit-url-template = "https://github.com/NixOS/nix-pills/tree/master/{path}"
+git-repository-url = "https://github.com/NixOS/nix-pills"
+
+[output.html.redirect]
+"pr01.html" = "00-preface.html"
+"why-you-should-give-it-a-try.html" = "01-why-you-should-give-it-a-try.html"
+"install-on-your-running-system.html" = "02-install-on-your-running-system.html"
+"enter-environment.html" = "03-enter-environment.html"
+"basics-of-language.html" = "04-basics-of-language.html"
+"functions-and-imports.html" = "05-functions-and-imports.html"
+"our-first-derivation.html" = "06-our-first-derivation.html"
+"working-derivation.html" = "07-working-derivation.html"
+"generic-builders.html" = "08-generic-builders.html"
+"automatic-runtime-dependencies.html" = "09-automatic-runtime-dependencies.html"
+"developing-with-nix-shell.html" = "10-developing-with-nix-shell.html"
+"garbage-collector.html" = "11-garbage-collector.html"
+"inputs-design-pattern.html" = "12-inputs-design-pattern.html"
+"callpackage-design-pattern.html" = "13-callpackage-design-pattern.html"
+"override-design-pattern.html" = "14-override-design-pattern.html"
+"nix-search-paths.html" = "15-nix-search-paths.html"
+"nixpkgs-parameters.html" = "16-nixpkgs-parameters.html"
+"nixpkgs-overriding-packages.html" = "17-nixpkgs-overriding-packages.html"
+"nix-store-paths.html" = "18-nix-store-paths.html"
+"fundamentals-of-stdenv.html" = "19-fundamentals-of-stdenv.html"
+"basic-dependencies-and-hooks.html" = "20-basic-dependencies-and-hooks.html"
+
+[output.linkcheck]
+follow-web-links = true
+
+# To build the epub version, run:
+# mdbook-epub --standalone true

custom.css

@@ -0,0 +1,28 @@
+.info {
+    margin: 20px;
+    padding: 0 20px;
+    border-inline-start: 2px solid var(--links);
+}
+
+.info:before {
+    position: absolute;
+    width: 3rem;
+    height: 3rem;
+    margin-inline-start: calc(-1.5rem - 21px);
+    content: "ⓘ";
+    text-align: center;
+    background-color: var(--bg);
+    color: var(--links);
+    font-weight: bold;
+    font-size: 2rem;
+}
+
+/*
+  Make prompts unselectable in console sections.
+  This relies on highlight.js applying certain classes on the prompts.
+  For more details, see https://highlightjs.readthedocs.io/en/latest/css-classes-reference.html#stylable-scopes
+*/
+.hljs-meta.prompt_ {
+    user-select: none;
+    -webkit-user-select: none;
+}

default.nix

@@ -1,87 +1,32 @@
-{ pkgs ? import <nixpkgs> {}, revCount, shortRev }:
-let
-  lib = pkgs.lib;
-
-  sources = let
-
-      # We want nix examples, but not the top level nix to build things
-      noTopLevelNix = path: type: let
-          relPath = lib.removePrefix (toString ./. + "/") (toString path);
-        in builtins.match "[^/]*\.nix" relPath == null;
-
-      extensions = [ ".xml" ".txt" ".nix" ".bash" ];
-
-    in lib.cleanSourceWith {
-      filter = noTopLevelNix;
-      src = lib.sourceFilesBySuffices ./. extensions;
-    };
-
-  combined = pkgs.runCommand "nix-pills-combined"
-    {
-      buildInputs = [ pkgs.libxml2 ];
-      meta.description = "Nix Pills with as a single docbook file";
-      inherit revCount shortRev;
-    }
-    ''
-      cp -r ${sources} ./sources
-      chmod -R u+w ./sources
-
-      cd sources
-
-      printf "%s-%s" "$revCount" "$shortRev" > version
-      xmllint --xinclude --output "$out" ./book.xml
-    '';
-
-  toc = builtins.toFile "toc.xml"
-    ''
-      <toc role="chunk-toc">
-        <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-nix-pills"><?dbhtml filename="index.html"?>
-        </d:tocentry>
-      </toc>
-    '';
+{ pkgs ? import <nixpkgs> {} }:
 
-  manualXsltprocOptions = toString [
-    "--param section.autolabel 1"
-    "--param section.label.includes.component.label 1"
-    "--stringparam html.stylesheet style.css"
-    "--param xref.with.number.and.title 1"
-    "--param toc.section.depth 3"
-    "--stringparam admon.style ''"
-    "--stringparam callout.graphics.extension .svg"
-    "--stringparam current.docid nix-pills"
-    "--param chunk.section.depth 0"
-    "--param chunk.first.sections 1"
-    "--param use.id.as.filename 1"
-    "--stringparam generate.toc 'book toc appendix toc'"
-    "--stringparam chunk.toc '${toc}'"
-  ];
-
-in {
-  html-split = pkgs.stdenv.mkDerivation {
+{
+  html-split = pkgs.stdenvNoCC.mkDerivation {
     name = "nix-pills";
+    src = ./.;
 
-    src = sources;
-
-    buildInputs = with pkgs; [
-      libxslt
+    nativeBuildInputs = with pkgs; [
+      mdbook
+      mdbook-linkcheck
     ];
 
+    buildPhase = ''
+      runHook preBuild
+
+      # We can't check external links inside the sandbox, but it's good to check them outside the sandbox.
+      substituteInPlace book.toml --replace-fail 'follow-web-links = true' 'follow-web-links = false'
+      mdbook build
+
+      runHook postBuild
+    '';
+
     installPhase = ''
       runHook preInstall
 
-      # Generate the HTML manual.
+      # The nix pills were originally built into this directory, and consumers of the nix pills expect to find it there. Do not change unless you also change other code that depends on this directory structure.
       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}"
-
-      mkdir -p "$dst/images/callouts"
-      cp -r "${pkgs.docbook-xsl-ns}/xml/xsl/docbook/images/callouts"/*.svg "$dst/images/callouts"
-
-      cp "${./style.css}" "$dst/style.css"
+      mv book/html/* "$dst"/
 
       mkdir -p "$out/nix-support"
       echo "nix-build out $out" >> "$out/nix-support/hydra-build-products"
@@ -91,13 +36,13 @@ in {
     '';
   };
 
-  epub = pkgs.stdenv.mkDerivation {
+  epub = pkgs.stdenvNoCC.mkDerivation {
     name = "nix-pills-epub";
+    src = ./.;
 
-    src = sources;
-
-    buildInputs = with pkgs; [
-      libxslt
+    nativeBuildInputs = with pkgs; [
+      mdbook-epub
+      unzip
       zip
     ];
 
@@ -107,29 +52,39 @@ in {
 
     doInstallCheck = true;
 
+    buildPhase = ''
+      runHook preBuild
+
+      mdbook-epub --standalone${pkgs.lib.optionalString (pkgs.mdbook-epub.version != "unstable-2022-12-25") " true"}
+
+      # Work around bugs in mdbook-epub.
+      mkdir nix-pills.epub-fix
+      ( cd nix-pills.epub-fix
+        unzip -q "../book/epub/Nix Pills.epub"
+        # Fix invalid ids.
+        sed -Ei 's/(id(ref)?=")([0-9])/\1p\3/g' OEBPS/content.opf
+        sed -Ei 's/(id="|href="#)([0-9])/\1fn\2/g' OEBPS/20-basic-dependencies-and-hooks.html
+        # Fix anchors.
+        sed -Ei 's~(<h[1-6])(>.+) \{#([^\}]+)\}(</h[1-6]>)~\1 id="\3"\2\4~g' OEBPS/*.html
+        # Fix broken links in body.
+        sed -Ei 's/("[0-9a-z-]+\.)md(["#])/\1html\2/g' OEBPS/*.html
+        # Remove unnecessary page breaks, the sections are short.
+        substituteInPlace OEBPS/stylesheet.css --replace-fail "page-break-before: always;" ""
+        zip -q "../book/epub/Nix Pills.epub" **/*
+      )
+
+      runHook postBuild
+    '';
+
     installPhase = ''
       runHook preInstall
 
-      # Generate the EPUB manual.
+      # The nix pills were originally built into this directory, and consumers of the nix pills expect to find it there. Do not change unless you also change other code that depends on this directory structure.
       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"
+      mv "book/epub/Nix Pills.epub" "$manual"
 
       mkdir -p "$out/nix-support"
       echo "nix-build out $out" >> "$out/nix-support/hydra-build-products"

pills/00-preface.md

@@ -0,0 +1,15 @@
+# Preface
+
+This is a ported version of the **Nix Pills**, a series of blog posts written by **Luca Bruno** (aka Lethalman) and originally published in 2014 and 2015. It provides a tutorial introduction into the Nix package manager and Nixpkgs package collection, in the form of short chapters called 'pills'.
+
+Since the Nix Pills are considered a classic introduction to Nix, an effort to port them to the current format was led by Graham Christensen (aka grahamc / gchristensen) and other contributors in 2017.
+
+For an up-to-date version, please visit <https://nixos.org/guides/nix-pills/>. An [EPUB version](https://nixos.org/guides/nix-pills/nix-pills.epub) is also available.
+
+If you encounter problems, please report them on the [nixos/nix-pills](https://github.com/NixOS/nix-pills/issues) issue tracker.
+
+<div class="info">
+
+Note: Commands prefixed with `#` have to be run as root, either requiring to login as root user or temporarily switching to it using `sudo` for example.
+
+</div>