Merge pull request #484 from mreed20/epub-acknowledgements-new

Populate acknowledgements.md with contributors for EPUB

.gitignore

@@ -26,3 +26,7 @@ Gemfile.lock
 
 ## Emacs files
 auto/
+
+## Misc build files
+out/
+src/plfa/acknowledgements_epub.md

.travis.yml

@@ -22,6 +22,7 @@ addons:
     packages:
       - libgmp-dev
       - libicu-dev
+      - luarocks
 
 # Ensure we run BASH and not SH
 env:

Makefile

@@ -13,7 +13,7 @@ endif
 
 
 # Build PLFA and test hyperlinks
-test: build epub
+test: build
 	ruby -S bundle exec htmlproofer '_site'
 
 
@@ -49,12 +49,10 @@ out/:
 #       sections are displayed to users. Some readers may be slow if the chapter
 #       files are too large, so for large documents with few level-1 headings, one
 #       might want to use a chapter level of 2 or 3."
-#
-#TODO: embedded fonts not working (path problem?)
 
 epub: out/plfa.epub
 
-out/plfa.epub: out/ $(AGDA) $(LUA) epub/main.css
+out/plfa.epub: out/ $(AGDA) $(LUA) epub/main.css src/plfa/acknowledgements_epub.md
 	pandoc --strip-comments \
 		--css=epub/main.css \
 		--epub-embed-font='assets/fonts/mononoki.woff' \
@@ -62,6 +60,7 @@ out/plfa.epub: out/ $(AGDA) $(LUA) epub/main.css
 		--epub-embed-font='assets/fonts/DejaVuSansMono.woff' \
 		--lua-filter epub/include-files.lua \
 		--lua-filter epub/rewrite-links.lua \
+		--lua-filter epub/rewrite-html-ul.lua \
 		--lua-filter epub/default-code-class.lua -M default-code-class=agda \
 		--standalone \
 		--fail-if-warnings \
@@ -70,7 +69,8 @@ out/plfa.epub: out/ $(AGDA) $(LUA) epub/main.css
 		-o "$@" \
 		epub/index.md
 
-
+src/plfa/acknowledgements_epub.md: src/plfa/acknowledgements.md _config.yml 
+	lua epub/run-liquid.lua _config.yml $< $@
 
 
 # Convert literal Agda to Markdown
@@ -119,7 +119,7 @@ build-incremental: $(MARKDOWN)
 
 # Remove all auxiliary files
 clean:
-	rm -f .agda-stdlib.sed .links-*.sed
+	rm -f .agda-stdlib.sed .links-*.sed src/plfa/acknowledgements_epub.md
 ifneq ($(strip $(AGDAI)),)
 	rm $(AGDAI)
 endif
@@ -158,6 +158,9 @@ travis-setup:\
 	$(HOME)/agda-stdlib-$(AGDA_STDLIB_VERSION)/src\
 	$(HOME)/.agda/defaults\
 	$(HOME)/.agda/libraries\
+	$(HOME)/.local/share/lua/5.1/tinyyaml.lua\
+	$(HOME)/.local/share/lua/5.1/liquid.lua\
+	$(HOME)/.local/share/lua/5.1/cjson\
 	/usr/bin/pandoc
 
 .phony: travis-setup
@@ -204,6 +207,17 @@ $(HOME)/.local/bin/agda:
 	cd $(HOME)/agda-$(AGDA_VERSION);\
 		stack install --stack-yaml=stack-8.0.2.yaml
 
+$(HOME)/.local/share/lua/5.1/tinyyaml.lua:
+	luarocks install lua-tinyyaml
+
+$(HOME)/.local/share/lua/5.1/liquid.lua:
+	luarocks install liquid
+
+$(HOME)/.local/share/lua/5.1/cjson:
+	# Only this particular version works:
+	# https://github.com/mpx/lua-cjson/issues/56:
+	luarocks install lua-cjson 2.1.0-1
+
 travis-uninstall-agda:
 	rm -rf $(HOME)/agda-$(AGDA_VERSION)/
 	rm -f $(HOME)/.local/bin/agda

README.md

@@ -32,6 +32,12 @@ permalink: /GettingStarted/
 [ruby-html-proofer]: https://github.com/gjtorikian/html-proofer
 
 [kramdown]: https://kramdown.gettalong.org/syntax.html
+[pandoc]: https://pandoc.org/installing.html
+
+[lua]: https://www.lua.org/download.html
+[luarocks]: https://luarocks.org/
+[liquid-lua]: https://luarocks.org/modules/3scale/liquid
+[lua-cjson-broken]: https://github.com/mpx/lua-cjson/issues/56
 
 
 <!-- Status & Version Badges -->
@@ -172,9 +178,13 @@ You'll see the key sequence of the character in mini buffer.
 
 ## Dependencies for developers
 
-Building PLFA is currently supported on Linux and macOS.
+PLFA is available as both a website and an EPUB e-book,
+both of which can be built on Linux and macOS.
 PLFA is written in literate Agda with [Kramdown Markdown][kramdown].
-The book is built in three stages:
+
+### Building the website
+
+The website version of the book is built in three stages:
 
  1. The `.lagda.md` files are compiled to Markdown using Agda’s highlighter.
     (This requires several POSIX tools, such as `bash`, `sed`, and `grep`.)
@@ -216,3 +226,36 @@ If you simply wish to have a local copy of the book, e.g. for offline reading, b
 bundle install
 bundle exec jekyll serve
 ```
+
+### Building the EPUB
+
+The EPUB version of the book is built using Pandoc,
+with Lua filters,
+and the script `run-liquid.lua`,
+which wraps the library [`liquid.lua`][liquid-lua].
+Here's how to build the EPUB:
+
+1. Install a recent version of Pandoc, [available here][pandoc].
+   We recommend their official installer (on the linked page),
+   which is much faster than compiling Pandoc from source with Haskell Stack.
+
+1. Install Lua version 5.3, [available here][lua].
+   Other versions have not been tested.
+
+1. Install luarocks, [available here][luarocks],
+   which we will use to install the dependencies of `run-liquid.lua`.
+
+1. Install the dependencies of `run-liquid.lua` by running:
+   ```bash
+   luarocks install lua-cjson 2.1.0-1
+   luarocks install lua-tinyyaml
+   luarocks install liquid
+   ```
+   Be sure to install `lua-cjson` version `2.1.0-1` as specified above:
+   [newer version are broken][lua-cjson-broken].
+
+1. Finally build the EPUB by running:
+   ```bash
+   make epub
+   ```
+   Pandoc will write the EPUB to `out/plfa.epub`.

epub/index.md

@@ -65,7 +65,7 @@ src/plfa/part2/Substitution.lagda.md
 # Backmatter
 
 ``` {.include shift-heading-level-by=1}
-src/plfa/acknowledgements.md
+src/plfa/acknowledgements_epub.md
 src/plfa/Fonts.lagda.md
 src/plfa/statistics.md
 ```

epub/rewrite-html-ul.lua

@@ -0,0 +1,5 @@
+-- Transforms '<ul class={something}>' into '<ul>'.
+function RawBlock (el)
+    el.text = el.text:gsub('%s*<%s*ul%s*class=%s*"?[%w-]+"?%s*>%s*', '<ul>')
+    return el
+end

epub/run-liquid.lua

@@ -0,0 +1,52 @@
+local yaml = require 'tinyyaml'
+local liquid = require 'liquid'
+
+-- Given a file name, return its file descriptor.
+-- Throws an error on failure.
+local function errOpen (fname, mode)
+    local fd = io.open(fname, mode)
+    if fd == nil then
+        error('could not open file: ' .. fname)
+    end
+    return fd
+end
+
+-- Given a file name and some data, overwrite the file with the data.
+-- Throws an error on failure.
+local function errWrite (fname, data)
+    local fd = errOpen(fname, 'w')
+    local status, errstr = fd:write(data)
+    if status == nil then
+        error(fname .. ': ' .. errstr)
+    end
+end
+
+-- Given a file name, return that file's entire contents.
+-- Throws an error on failure.
+local function errReadAll (fname)
+    local data = errOpen(fname, 'r'):read('a')
+    if data == nil then
+        error('could not read from open file: ' .. fname)
+    end
+    return data
+end
+
+
+-- We must have exactly three arguments.
+if #arg ~= 3 then
+    print('usage: ' .. arg[0] .. ' [yaml_file] [markdown_in_file] [markdown_out_file]')
+    os.exit(1)
+end
+
+-- 1. Read YAML metadata from file, which we nest under the key 'site'.
+local metadata = { ['site'] = yaml.parse(errReadAll(arg[1])) }
+
+-- 2. Read markdown document from file.
+local document = errReadAll(arg[2])
+
+-- 3. Render the markdown document with the YAML metadata as context.
+local template = liquid.Template:parse(document)
+local result = template:render(liquid.InterpreterContext:new(metadata))
+
+-- 4. Write rendered document to output file.
+errWrite(arg[3], result)

src/plfa/acknowledgements.md

@@ -7,12 +7,14 @@ next      : /Fonts/
 ---
 
 Thank you to:
-  * The inventors of Agda, for a new playground.
-  * The authors of Software Foundations, for inspiration.
+
+* The inventors of Agda, for a new playground.
+* The authors of Software Foundations, for inspiration.
 
 
 A special thank you, for inventing ideas on which
 this book is based, and for hand-holding:
+
 <ul class="list-of-contributors">
 <li>Andreas Abel</li>
 <li>Catarina Coquand</li>
@@ -25,32 +27,34 @@ this book is based, and for hand-holding:
 <li>Ulf Norell</li>
 </ul>
 
-{%- if site.contributors or site.extra_contributors -%}
+{% if site.contributors or site.extra_contributors %}
 For pull requests big and small, and for answering questions on the Agda mailing list:
+
 <ul class="list-of-contributors">
-{%- for contributor in site.contributors -%}
+{% for contributor in site.contributors %}
   <li><a href="https://github.com/{{ contributor.github_username }}">{{ contributor.name }}</a></li>
-{%- endfor -%}
-{%- for contributor in site.extra_contributors -%}
-  {%- if contributor.name and contributor.github_username -%}
+{% endfor %}
+{% for contributor in site.extra_contributors %}
+  {% if contributor.name and contributor.github_username %}
   <li><a href="https://github.com/{{ contributor.github_username }}">{{ contributor.name }}</a></li>
-  {%- else -%}
-  {%- if contributor.name -%}
+  {% else %}
+  {% if contributor.name %}
   <li>{{ contributor.name }}</li>
-  {%- endif -%}
-  {%- if contributor.github_username -%}
+  {% endif %}
+  {% if contributor.github_username %}
   <li><a href="https://github.com/{{ contributor.github_username }}">{{ contributor.github_username }}</a></li>
-  {%- endif -%}
-  {%- endif -%}
-{%- endfor -%}
+  {% endif %}
+  {% endif %}
+{% endfor %}
 <li>[Your name goes here]</li>
 </ul>
-{%- else -%}
-{%- endif -%}
+{% else %}
+{% endif %}
 
 
 For support:
-  * EPSRC Programme Grant EP/K034413/1
-  * NSF Grant No. 1814460
-  * Foundation Sciences Mathematiques de Paris (FSMP)
-    Distinguised Professor Fellowship
+
+* EPSRC Programme Grant EP/K034413/1
+* NSF Grant No. 1814460
+* Foundation Sciences Mathematiques de Paris (FSMP)
+  Distinguised Professor Fellowship