Added support for EPUB3

[Ioan-Cristian]

Description

This pull requests adds support for building EPUB3 versions of the RISC-V ISA manuals. To achieve this, asciidoctor-epub3 extension has been used.

Motivation

eBook readers are convenient devices for reading. They are based on e-Ink screens, reducing fatigue while reading. EPUB3 is an open standard eBook format supported by a wide range of hardware readers. It is also well supported by asciidoctor through the aforementioned extension, making it an ideal file format for RISC-V ISA manuals.

Testing

Manually built using Ubuntu 24.04 and viewed files on PocketBook InkPad 3.

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.

Related pull requests

riscv-docs-base-container-image: #12

[aswaterman]

@wmat I think we need to partially revert this. Trying to build this within the usual docker container, the build fails because of a lack of asciidoctor-epub3.

[aswaterman]

Nevermind. I see the docker container has been updated accordingly and I just needed to download a newer version. In case anyone else stumbles across this, don't forget to docker pull docker.io/riscvintl/riscv-docs-base-container-image:latest

[aswaterman]

Nevermind once again. The epub build is still broken inside the docker container, but for a different reason:

asciidoctor: WARNING: riscv-privileged.adoc: invalid reference to unknown anchor: LP_INST
(sass):384: Invalid US-ASCII character "\\xE2" (Sass::SyntaxError)

I'll disable building epubs within the docker container for now.

[Ioan-Cristian]

Probably you've run cd build && make. You need to run export LANG=C.utf8; cd build && make as suggested by the README.md and workflow files.

[aswaterman]

The command “make docker” is supposed to just work, regardless of environment. So you have not fixed up the Makefile properly. When you have, let us know.