Added support for EPUB3

This pull requests adds support for building EPUB3 versions of the RISC-V ISA manuals. To achieve this, `asciidoctor-epub3` extension has been used. Known issues: some eBook readers are not capable of rendering embedded images. The solution to this problem is disabling embedded image altogether. The `README.md` file provides more details on how to achieve this. Signed-off-by: Ioan-Cristian CÎRSTEA <ioan-cristian.cirstea@tutanota.com>
Ioan-Cristian · May 12, 2024 · 530b428 · 530b428
1 parent acf7bbd
commit 530b428
Show file tree

Hide file tree

Showing 8 changed files with 78 additions and 7 deletions.
diff --git a/.github/workflows/isa-build.yml b/.github/workflows/isa-build.yml
@@ -52,7 +52,7 @@ jobs:
       if: steps.pull_container_image.outcome == 'success'
       run: |
         docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \
-        /bin/sh -c 'cd ./build && make'
+        /bin/sh -c 'export LANG=C.utf8; cd ./build && make'
 
     # Upload the priv-isa-asciidoc PDF file
     - name: Upload priv-isa-asciidoc.pdf
@@ -72,6 +72,15 @@ jobs:
         path: ${{ github.workspace }}/build/priv-isa-asciidoc.html
         retention-days: 7
 
+    # Upload the priv-isa-asciidoc EPUB file
+    - name: Upload priv-isa-asciidoc.epub
+      if: steps.build_files.outcome == 'success'
+      uses: actions/upload-artifact@v4
+      with:
+        name: priv-isa-asciidoc-${{ env.SHORT_SHA }}.epub
+        path: ${{ github.workspace }}/build/priv-isa-asciidoc.epub
+        retention-days: 7
+
     # Upload the unpriv-isa-asciidoc PDF file
     - name: Upload unpriv-isa-asciidoc.pdf
       if: steps.build_files.outcome == 'success'
@@ -90,6 +99,15 @@ jobs:
         path: ${{ github.workspace }}/build/unpriv-isa-asciidoc.html
         retention-days: 7
 
+    # Upload the unpriv-isa-asciidoc EPUB file
+    - name: Upload unpriv-isa-asciidoc.epub
+      if: steps.build_files.outcome == 'success'
+      uses: actions/upload-artifact@v4
+      with:
+        name: unpriv-isa-asciidoc-${{ env.SHORT_SHA }}.epub
+        path: ${{ github.workspace }}/build/unpriv-isa-asciidoc.epub
+        retention-days: 7
+
     - name: Create Release
       if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.create_release == 'true'
       uses: softprops/action-gh-release@v2
@@ -103,8 +121,10 @@ jobs:
         files: |
           ${{ github.workspace }}/build/priv-isa-asciidoc.pdf
           ${{ github.workspace }}/build/priv-isa-asciidoc.html
+          ${{ github.workspace }}/build/priv-isa-asciidoc.epub
           ${{ github.workspace }}/build/unpriv-isa-asciidoc.pdf
           ${{ github.workspace }}/build/unpriv-isa-asciidoc.html
+          ${{ github.workspace }}/build/unpriv-isa-asciidoc.epub
       env:
         GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
-
+
diff --git a/.github/workflows/merge-and-release.yml b/.github/workflows/merge-and-release.yml
@@ -33,7 +33,7 @@ jobs:
       if: steps.pull_container_image.outcome == 'success'
       run: |
           docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \
-          /bin/sh -c 'cd ./build && make'
+          /bin/sh -c 'export LANG=C.utf8; cd ./build && make'
 
     # Upload the priv-isa-asciidoc PDF file
     - name: Upload priv-isa-asciidoc.pdf
@@ -51,6 +51,14 @@ jobs:
         name: priv-isa-asciidoc-${{ env.SHORT_SHA }}.html
         path: ${{ github.workspace }}/build/priv-isa-asciidoc.html
 
+    # Upload the priv-isa-asciidoc EPUB file
+    - name: Upload priv-isa-asciidoc.epub
+      if: steps.build_files.outcome == 'success'
+      uses: actions/upload-artifact@v4
+      with:
+        name: priv-isa-asciidoc-${{ env.SHORT_SHA }}.epub
+        path: ${{ github.workspace }}/build/priv-isa-asciidoc.epub
+
     # Upload the unpriv-isa-asciidoc PDF file
     - name: Upload unpriv-isa-asciidoc.pdf
       if: steps.build_files.outcome == 'success'
@@ -67,6 +75,14 @@ jobs:
         name: unpriv-isa-asciidoc-${{ env.SHORT_SHA }}.html
         path: ${{ github.workspace }}/build/unpriv-isa-asciidoc.html
 
+    # Upload the unpriv-isa-asciidoc EPUB file
+    - name: Upload unpriv-isa-asciidoc.epub
+      if: steps.build_files.outcome == 'success'
+      uses: actions/upload-artifact@v4
+      with:
+        name: unpriv-isa-asciidoc-${{ env.SHORT_SHA }}.epub
+        path: ${{ github.workspace }}/build/unpriv-isa-asciidoc.epub
+
     - name: Create Release
       uses: softprops/action-gh-release@v2
       env:
@@ -84,5 +100,7 @@ jobs:
         files: |
           ${{ github.workspace }}/build/priv-isa-asciidoc.pdf
           ${{ github.workspace }}/build/priv-isa-asciidoc.html
+          ${{ github.workspace }}/build/priv-isa-asciidoc.epub
           ${{ github.workspace }}/build/unpriv-isa-asciidoc.pdf
           ${{ github.workspace }}/build/unpriv-isa-asciidoc.html
+          ${{ github.workspace }}/build/unpriv-isa-asciidoc.epub
diff --git a/README.md b/README.md
@@ -27,6 +27,14 @@ The recommended method for building the PDF files is to use the Docker Image, as
 
 Alternative build methods, such as local builds and GitHub Action builds, are also available and described in the Documentation Developer's Guide.
 
+## Images not rendered for EPUB files
+
+If the eBook reader does not support embedded images, uncomment `:data-uri:` lines in `src/riscv-privileged.adoc` and `src/riscv-unprivileged.adoc`.
+
+### Known devices that cannot handle embedded images
+
+- PocketBook InkPad 3
+
 ## Repo Activity
 
 ![Alt](https://repobeats.axiom.co/api/embed/ccec87dc4502f2ed7c216b670b5ed8efc33a1d4c.svg "Repobeats analytics image")
diff --git a/build/.gitignore b/build/.gitignore
@@ -1,6 +1,7 @@
 *.aux
 *.bbl
 *.blg
+*.epub
 *.html
 *.log
 *.out

diff --git a/build/Makefile b/build/Makefile
@@ -14,7 +14,7 @@
 # for generating documentation in various formats (PDF, HTML).
 
 # Build Targets
-TARGETS := priv unpriv priv-html unpriv-html
+TARGETS := priv-pdf unpriv-pdf priv-html unpriv-html priv-epub unpriv-epub
 
 # Declare phony targets
 .PHONY: all $(TARGETS) clean
@@ -43,7 +43,7 @@ SRCDIR := ../src
 JUNK := *.pdf *.aux *.log *.bbl *.blg *.toc *.out *.fdb_latexmk *.fls *.synctex.gz
 
 # Privileged ISA build
-priv: priv-isa-asciidoc.pdf
+priv-pdf: priv-isa-asciidoc.pdf
 
 priv-isa-asciidoc.pdf: $(SRCDIR)/riscv-privileged.adoc $(SRCDIR)/*.adoc
 	@echo "Building Privileged ISA"
@@ -52,7 +52,7 @@ priv-isa-asciidoc.pdf: $(SRCDIR)/riscv-privileged.adoc $(SRCDIR)/*.adoc
 	mv $@.tmp $@
 
 # Unprivileged ISA build
-unpriv: unpriv-isa-asciidoc.pdf
+unpriv-pdf: unpriv-isa-asciidoc.pdf
 
 unpriv-isa-asciidoc.pdf: $(SRCDIR)/riscv-unprivileged.adoc $(SRCDIR)/*.adoc
 	@echo "Building Unprivileged ISA"
@@ -74,6 +74,18 @@ unpriv-isa-asciidoc.html: $(SRCDIR)/riscv-unprivileged.adoc
 	@echo "Building Unprivileged ISA HTML"
 	asciidoctor $(ASCIIDOCTOR_OPTS) --out-file=$@ $<
 
+priv-epub: priv-isa-asciidoc.epub
+
+priv-isa-asciidoc.epub: $(SRCDIR)/riscv-privileged.adoc
+	@echo "Building Privileged ISA EPUB"
+	asciidoctor-epub3 $(ASCIIDOCTOR_OPTS) --out-file=$@ $<
+
+unpriv-epub: unpriv-isa-asciidoc.epub
+
+unpriv-isa-asciidoc.epub: $(SRCDIR)/riscv-unprivileged.adoc
+	@echo "Building Unprivileged ISA EPUB"
+	asciidoctor-epub3 $(ASCIIDOCTOR_OPTS) --out-file=$@ $<
+
 clean:
 	@if [ -f priv-isa-asciidoc.pdf ]; then \
 		echo "Removing priv-isa-asciidoc.pdf"; \
@@ -91,4 +103,11 @@ clean:
 		echo "Removing unpriv-isa-asciidoc.html"; \
 		rm -f unpriv-isa-asciidoc.html; \
 	fi
-
+	@if [ -f priv-isa-asciidoc.epub ]; then \
+		echo "Removing priv-isa-asciidoc.epub"; \
+		rm -f priv-isa-asciidoc.epub; \
+	fi
+	@if [ -f unpriv-isa-asciidoc.epub ]; then \
+		echo "Removing unpriv-isa-asciidoc.epub"; \
+		rm -f unpriv-isa-asciidoc.epub; \
+	fi
diff --git a/dependencies/Gemfile b/dependencies/Gemfile
@@ -5,6 +5,7 @@ gem 'asciidoctor-diagram'
 gem 'mathematical'
 gem 'asciidoctor-mathematical'
 gem 'asciidoctor-pdf'
+gem 'asciidoctor-epub3'
 gem 'citeproc-ruby'
 gem 'coderay'
 gem 'csl-styles'

diff --git a/src/riscv-privileged.adoc b/src/riscv-privileged.adoc
@@ -46,6 +46,8 @@ endif::[]
 :chapter-refsig: Chapter
 :section-refsig: Section
 :appendix-refsig: Appendix
+// Uncomment :data-uri: if your eBook reader is not capable of rendering
+// embedded images. One known affected device is PocketBook InkPad 3.
 :data-uri:
 :hide-uri-scheme:
 :stem: latexmath

diff --git a/src/riscv-unprivileged.adoc b/src/riscv-unprivileged.adoc
@@ -42,6 +42,8 @@ endif::[]
 :chapter-refsig: Chapter
 :section-refsig: Section
 :appendix-refsig: Appendix
+// Uncomment :data-uri: if your eBook reader is not capable of rendering
+// embedded images. One known affected device is PocketBook InkPad 3.
 :data-uri:
 :hide-uri-scheme:
 :stem: latexmath
-Original file line number
+Diff line change
@@ -1,6 +1,7 @@
     *.aux
     *.bbl
     *.blg
+    *.epub
     *.html
     *.log
     *.out
@@ Expand Down @@