Unnecessary build dependencies

[go-sc]

Current build procedure has dependencies that are not described in Readme file. It requires installation of Node.js package manager npm. Ubuntu repositories provide outdated nodejs package which is incompatible with the build instructions provided in Readme. One can still install the latest version of nodejs though following these instructions.

Running npm i creates a directory node_modules containing 253 MB of dependencies. Running npm run build takes 1 minute and 17 seconds on my laptop (closing Firefox helps to speed up the process, I don't have clear understanding why) which is quite long for building such a simple file. As I can see, it also implicitly creates datasheet.pdf file which is a copy of public/v-spec.pdf.

From a pull request https://github.com/riscv/riscv-v-spec/pull/112, I suppose that all those JavaScript dependencies were incorporated just for nifty pictures of instruction formats. We can still create illustrations using any tool of your choice and include them in v-spec.adoc as pictures using standard Asciidoctor syntax and extensions.

P. S. Do I understand correctly that V-ext description will be converted to LaTeX after all when it's finished?

[drom]

Current build procedure has dependencies that are not described in Readme file. It requires installation of Node.js package manager npm. Ubuntu repositories provide outdated nodejs package which is incompatible with the build instructions provided in Readme. One can still install the latest version of nodejs though following these instructions.

Yes, tools require node v6+. I have added requirements into the description https://github.com/riscv/riscv-v-spec/commit/cdc07ce5f4cf8c9316f42f35f13120aeeb0ada30

Running npm i creates a directory node_modules containing 253 MB of dependencies. Running npm run build takes 1 minute and 17 seconds on my laptop (closing Firefox helps to speed up the process, I don't have clear understanding why) which is quite long for building such a simple file.

We are trying to make the spec generation process as portable as possible. The tool has to work on Mac, Linux, Windows. The tool has to be installed into the user space (in this case local to the project). I can take a look at what can be done to reduce its size.

As I can see, it also implicitly creates datasheet.pdf file which is a copy of public/v-spec.pdf. Yes, datasheet.pdf is just a temporary copy of the resulted PDF file. I will clean it up.

From a pull request #112, I suppose that all those JavaScript dependencies were incorporated just for nifty pictures of instruction formats. We can still create illustrations using any tool of your choice and include them in v-spec.adoc as pictures using standard Asciidoctor syntax and extensions.

Here are some reasons why JavaScript dependencies where introduced.

We looking for production of high-quality PDF with features comparable to the HTML version of the spec (Fonts, CSS, SVG, ...JavaScript to generate "nifty pictures" :)

PDF generation flow has to be free and opensource. So we use https://nwjs.io (rendering controlled by JavaScript)

P. S. Do I understand correctly that V-ext description will be converted to LaTeX after all when it's finished?

I would think about the other way around ;)

[go-sc]

I just want to point out that maybe it is too much to require everyone working on a draft using such a bulky build procedure. Pure Asciidoctor is just fine at this stage.

LaTeX is also capable of publishable quality documents with fonts, SVG (TikZ). But of course it is also interesting to see what other tools can offer, preferably in a separate branch of the repository.

[drom]

I have moved documentation generation flow into separate repo here https://github.com/riscv/documents We are using this flow to generate documents for the website. Authors working on the draft is NOT required to use this flow.

[aswaterman]

@go-sc No, we are trying to abandon LaTeX. The quality of the final product is OK, but not great, and the effort is enormous. We want to replace it with @drom's work, which is both more productive to use and produces a higher-quality product.

[aka-sps]

We want to replace it with @drom's work, which is both more productive to use and produces a higher-quality product.

IMHO: Semantic markup of DocBook is more suitable for technical documentation. At the very least, DocBook is more documented and debugged. See https://docbook.org/, https://en.wikipedia.org/wiki/DocBook, http://www.xmlmind.com/xmleditor/download.shtml#download_xbe_perso

[aswaterman]

Indeed, there is more than one way to skin a cat. However, the people who are doing the bulk of the work on the documentation get more say in this matter :)