Specification document - LaTeX to Asciidoc conversion

[ben-marshall]

The specification needs to be converted from LaTeX to asciidoc, specifically the asciidoctor tool. This issue tries to capture what needs to happen.

What needs converting?

All of the LaTeX files under doc/spec/tex. Starting with the scalar and files shared between specifications, but moving onto the vector spec.

How will it be converted:

We can use Pandoc to bulk convert the files automatically, but there are several important gottchas while will need manual or semi-automatic fixing:

• We have an extensive bibliography, particularly for the Entropy Source which should be preserved. Asciidoc does not have such a powerful bibliography system as LaTeX, but there is a standard way to do it described here. There is also a WiP script (bin/bibtex-to-asciidoc.py) to automatically convert the bibtex citations to the asciidoc format.

• Pandoc does not convert the latex \cite{X} macro into an asciidoc reference. The entire citation simply disappears from the output. This will either need to be fixed manually, or semi-scripted to be fixed.

• We currently inline the Sail code describing the functionality of our instructions into the specification, by sourcing from the Sail files directly. Pandoc is smart enough to extract the right parts of the source code in its automatically converted output. However, this will need to be manually maintained whenever the Sail code is updated, unless an automated solution exists / can be found.

• Pandoc mangles anything in the verbatim-esq cryptoise environment. This can be manually fixed. It's just for showing assembly syntax.

• Edited to add: It looks like there's a great set of templates/examples here

Open Questions:

• It's not clear how to represent the encodings? We can generate these tables if need be, as is currently done for the LaTeX, though it would be good if there was a standard way to do this.

• We currently have one monolithic specification document, which works really well as a "single source" for people to look at. It's likely that this will be split into separate components:

  • The ZKb section, which is just a list of instructions from the Bitmanip extension which are useful for Scalar Cryptography, along with some rationale.
  • The dedicated scalar cryptography instructions, which exist only in this extension.
  • The entropy source.
  • The ZKt proposal, which is orthogonal to the rest of the spec, and adds constant time guarantees to listed instructions. It is already in asciidoc, and is maintained here. It will eventually be moved into this repository.

• It's not entirely clear whether these should be distributed as a single document, or maintained as separate files but combined into one monolithic document, as is currently done with the LaTeX sources. In any case, all of them will need to be versioned.

  • For the purposes of making progress and minimising the amount of change as we go, it might be sensible to first create a monolithic document with asciidoc as the source, and then break it into components for the purpose of ratification.

• It's not clear how our specification will be integrated into the main specification. We want to do our conversion to asciidoc so as to minimise the effort it takes to integrate into the final specification.

Progress

Shared files:

File	Automated Conversion	Manual Fixes	Notes
appx-benchmarking.tex			Doesn't need converting. Not maintained.
appx-materials.tex	[ ]	[ ]
changelog.tex			Doesn't need converting. Not maintained.
contributors.tex	[x]	[x]	Done
sec-audience.tex	[x]	[x]	Done
sec-policies.tex	[x]	[x]	Done
sec-sail.tex	[x]	[x]	Done
sec-scalar-profiles.tex	[x]	[x]	Done

Scalar Crypto:

File	Automated Conversion	Manual Fixes	Notes
sec-scalar-intro.tex	[x]	[x]
sec-scalar-aes.tex	[x]	[x]
sec-scalar-sha2.tex	[x]	[x]
sec-scalar-sm3.tex	[x]	[x]
sec-scalar-sm4.tex	[x]	[x]
sec-scalar-timing.tex	[x]	[x]
appx-scalar-encodings.tex	[ ]	[ ]	Need some guidance on standard way to do this.
appx-scalar-sail.tex	[ ]	[ ]

ZKb instruction group:

File	Automated Conversion	Manual Fixes	Notes
sec-scalar-bitmanip.tex	[x]	[x]	Done

Entropy Source:

File	Automated Conversion	Manual Fixes	Notes
sec-entropy-source.tex	[x]	[x]
appx-entropy.tex	[x]	[x]

Vector:

These are not a priority right now, we are focusing on the scalar crypto work.

File	Automated Conversion	Manual Fixes	Notes
sec-vector-aes.tex	[ ]	[ ]
sec-vector-clmul.tex	[ ]	[ ]
sec-vector-grev.tex	[ ]	[ ]
sec-vector-intro.tex	[ ]	[ ]
sec-vector-profiles.tex	[ ]	[ ]
sec-vector-rotate.tex	[ ]	[ ]
sec-vector-sha2.tex	[ ]	[ ]
sec-vector.tex	[ ]	[ ]
appx-vector-encodings.tex	[ ]	[ ]

[elisa-riscv]

In answer to your open question about whether to have a monolithic document or to break it into sections, I recommend chapter-sized chunks. The chapter-sized chunks can be grouped into sections, and all can be included in a book header file. You can find an example at https://github.com/riscv/docs-templates. Right now some specifics are subject to change and there is a bug with respect to the use of wavedrom diagramming for which we might need to provide a temporary workaround.

[ben-marshall]

Hi @elisa-riscv

I've made a start translating some parts of the specification which are very stable just to try things out. Your template repository and guide have been extremely helpful!

The asciidoc source so far can be seen here and I've attached a working copy to this comment (riscv-crypto-spec-scalar.pdf). Without wanting to take up too much of your time, I hope I'm going in the right direction?

Cheers,
Ben

[elisa-riscv]

HI Ben, Definitely you are going in the right direction. I am glad that you've got a build working for you and are on your way. Just a couple of quick comments, after a quick look: - the pdf to which you pointed does *not* make use of the fonts and styles that I provided. I can imagine that you want to test that your conversion builds in the default pdf first--a good idea--but at some point you'll want to ensure that the customized look and feel builds properly. - I'm not certain about your heading use, because in general I am expecting that topics start with a heading 1, indicated by `==`, but some document structure and conventions are still under discussion. Do let me know if you run into any issues. I'm thinking that I should put together a checklist for people to use as they go through the conversion process. - Elisa

…

On Wed, Apr 28, 2021 at 7:29 AM Ben Marshall ***@***.***> wrote: Hi @elisa-riscv <https://github.com/elisa-riscv> I've made a start translating some parts of the specification which are very stable just to try things out. Your template repository and guide have been extremely helpful! The asciidoc source so far can be seen here <https://github.com/riscv/riscv-crypto/tree/dev/next-release/doc/adoc-scalar> and I've attached a working copy to this comment ( riscv-crypto-spec-scalar.pdf <https://github.com/riscv/riscv-crypto/files/6392560/riscv-crypto-spec-scalar.pdf>). Without wanting to take up too much of your time, I hope I'm going in the right direction? Cheers, Ben — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ASTDNURHYY5F3DKE2ONGG53TLALUJANCNFSM43KQ66AQ> .

[ben-marshall]

Closed with release v0.9.1