plutus-book: skeleton

This adds a skeleton for the Plutus Book, with a spine file and
a demo chapter, as well as the Nix build and some instructions.

The Nix build creates the HTML, PDF, and EPUB version. We can
also do Kindle, but `kindlegen` has an unfree license, and I should
check that's okay.

default.nix

@@ -163,6 +163,7 @@ let
 
     docs = {
       plutus-tutorial = pkgs.callPackage ./plutus-tutorial/doc {};
+      plutus-book = pkgs.callPackage ./plutus-book {};
 
       plutus-core-spec = pkgs.callPackage ./plutus-core-spec { inherit latex; };
       multi-currency = pkgs.callPackage ./docs/multi-currency { inherit latex; };

plutus-book/.gitignore

@@ -0,0 +1,3 @@
+*.html
+asciidoctor.css
+pygments-tango.css

plutus-book/01-intro.adoc

@@ -0,0 +1,3 @@
+= Introduction 
+
+I'm an introduction, put text here.

plutus-book/README.md

@@ -0,0 +1,42 @@
+# The Plutus Book
+
+This is the Plutus Book. It is written using [asciidoctor](https://asciidoctor.org/),
+make sure to consult its excellent documentation.
+
+## Building the book
+
+### Using `nix`
+
+The book can be built in all its formats using `nix` (which is 
+what the CI uses). 
+
+- Run `nix build -f default.nix docs.plutus-book` in the root of
+  the repository.
+    - Make sure you've followed [the main README](../README.md#binary-caches).
+- Look inside the `result` directory.
+
+### Using `asciidoctor` directly
+
+This will just get you the html output, which is probably what
+you want during development.
+
+- Ensure you have the following installed:
+  - `asciidoctor`
+  - `python`
+- Run `asciidoctor plutus.adoc`.
+- Open the resulting `plutus.html` in a browser.
+
+## Book structure
+
+The entry point to the book is `plutus.adoc`. This defines the main document
+attributes and includes all the chapters in sequence.
+
+Chapters should be written in separate files (beginning the files with their
+sequence number is not essential but helpful), and included into `plutus.adoc`.
+
+## Miscellaneous
+
+Unfortunately due to a quirk of how `asciidoctor` parses double colons, it's
+tricky to write Haskell type signatures in the main text without them
+rendering wrong. To get around that, use an attribute reference `{2c}` 
+instead of the colons.

plutus-book/default.nix

@@ -0,0 +1,27 @@
+{ stdenv, lib, asciidoctor, python2, pandoc }:
+
+stdenv.mkDerivation {
+  name = "plutus-book";
+  src = lib.sourceFilesBySuffices ./. [ ".adoc" ".png" ".PNG" ".gif" ".ico" ".css" ];
+  buildInputs = [ asciidoctor python2 pandoc ];
+  buildPhase = ''
+    asciidoctor plutus.adoc -b html5 -o plutus.html
+
+    asciidoctor-pdf plutus.adoc -o plutus.pdf
+
+    # TODO: run epubcheck on the epub (it's not in our nixpkgs yet)
+    asciidoctor plutus.adoc -b docbook5 -o plutus.docbook
+    pandoc -f docbook -t epub plutus.docbook -o plutus.epub
+  '';
+  installPhase = ''
+    install -D -t $out/html plutus.html 
+    cp -aR images $out/html
+    cp -aR css $out/html
+
+    install -D -t $out/pdf plutus.pdf
+
+    install -D -t $out/epub plutus.epub
+
+    install -D -t $out/mobi plutus.mobi
+  '';
+}

plutus-book/plutus.adoc

@@ -0,0 +1,28 @@
+= Plutus 
+:authors: Some IOHK folk
+:email: plutus@iohk.io
+:orgname: IOHK
+:doctype: book
+:toc: left
+:sectnums:
+:source-highlighter: pygments
+// Considerations:
+// - Shouldn't mess up alignment (weirdly some of them do, including the default)
+// - Shouldn't have a dark background, otherwise callouts don't show up (otherwise I'd pick monokai)
+// - Should have a non-white background, to distinguish code blocks
+:pygments-style: tango
+:imagesdir: images
+// uses fontawesome, seems okay for now, could use real icons later
+:icons: font
+:favicon: {imagesdir}/favicon.ico
+:stylesdir: css
+:linkcss:
+// prevents setting the last-updated-label etc.
+:reproducible:
+
+// unfortunately, asciidoctor likes to parse these as definition lists :(
+// https://github.com/asciidoctor/asciidoctor/issues/1066
+:2c: ::
+
+// Include each chapter here
+include::01-intro.adoc[leveloffset=+ 1]