If you want to build the latest version of the [RISC-V Instruction Set Manual](https://github.com/riscv/riscv-isa-manual) with included errata then you will need to install [ASCIIdoctor](https://asciidoctor.org/) and some of its extensions.
# Dependencies
In particular, [asciidoctor-mathematical](https://github.com/asciidoctor/asciidoctor-mathematical) has a lot of dependencies that need to be installed with the package manager.
```sh
# all but ruby are only required by asciidoctor-mathematical
sudo eopkg install ruby libcairo-devel pango-devel gdk-pixbuf-devel
gem install asciidoctor asciidoctor-pdf asciidoctor-bibtex asciidoctor-diagram asciidoctor-mathematical pygments.rb
```
Unfortunately [asciidoctor-diagram](https://github.com/asciidoctor/asciidoctor-diagram) also requires [bytefield-svg](https://github.com/Deep-Symmetry/bytefield-svg) and [WaveDrom CLI](https://github.com/wavedrom/cli) which are Node.js libraries.
```sh
sudo eopkg install nodejs
sudo npm install -g bytefield-svg wavedrom-cli
```
# Build
Then you need to set the appropriate environment variables so it can find everything it needs and you can build the documentation from within the `build` directory.
```sh
cd build
export JAVA_HOME=/usr/lib64/openjdk-17
make
```
# Troubleshooting
## Java
`ditaa` is a Java diagram utility which is used in only one diagram in `mm-formal.adoc`.
However, you may find that even if you have OpenJDK installed that you are getting an error about Java missing.
According to the Solus [documentation](https://help.getsol.us/docs/user/software/development/java/) this is is because:
> Solus does not add Java to the `PATH` environment variable by default.
Ensure that the `JAVA_HOME` environment variable is set correctly.
## WaveDrom
If you don't install WaveDrom, you will see an error which implies that you need the "editor" but ***this is not true***! You only need the `wavedrom-cli` available in your `PATH.`
If for some reason you do decide to download or build the editor you can use these *incomplete* code snippets as a starting point.
```sh
sudo npm install -g wavedrom-editor
cd "$(npm list -g -p | \grep wavedrom-editor)"
sudo npm install
sudo npm run build
...
find . -type f -executable -iname 'wavedrom-editor'
...
```
```sh
curl -L https://github.com/wavedrom/wavedrom.github.io/releases/download/v3.4.0/wavedrom-editor-v3.4.0-linux-x64.tar.gz \
| tar xzvf -
PATH="$PATH:$PWD/wavedrom-editor-v3.4.0-linux-x64" make
```
# References
- https://discuss.asciidoctor.org/Problems-getting-wavedrom-diagramming-to-work-for-asciidoctor-pdf-td8592.html