update spec to use latest docs-spec-template features

[kbroch-rivosinc]

no spec content changes, just long list of workflow/infra change:

• update Makefile (src/build dir; html output;)
• update docs-resources to lastest commit
• adoc attributes
  • include global attributes from docs-resources
  • fix others to reflect src/build
• move spec files to src dir
• update github actions to latest
• install pre-commit (config file and github action)
• update README.adoc
  • add MAINTAINERS, CONTRIBUTING, CODE_OF_CONDUCT files

relates to #340

[ved-rivos]

@kbroch-rivosinc Thanks much! Two questions related to the headers: a) the ISA manual renders without colors b) the text in braces seems (fctl) seems to get rendered with a much smaller font (and without color; so maybe we dont need color - like the ISA manual). Is this fixable. Headers with this PR: Headers in ISA manual:

[kbroch-rivosinc]

@ved-rivos : the ISA manual uses a different theme then what is in the docs-resources repo. I'm not sure what the long term plan is for the ISA manual theme but for now I've copied the ISA theme to docs-resources https://github.com/riscv/docs-resources/pull/16 and will modify the Makefile to use that one instead since it would make sense to me that it looks the same as the spec it will end up in.

new version looks like:

/cc @wmat

[ved-rivos]

@kbroch-rivosinc @wmat Thanks much! The headers look nice now. But this theme seems to generate tiny font for text in tables. Perhaps the ISA manual does not have as many tables but large parts of this spec is all in tables ! So now debating whether I should just live with your older theme and fix the header issue by removing the backticks on the text in parenthesis in the headers...

[kbroch-rivosinc]

I wouldn't modify the content, if you want monospace for those commands in the headings (section titles).

The diff for tables is:

• riscv-spec.yaml theme has table:font-size: 9
• riscv-spec.yaml theme has table:font-size: 11.5

I can just change the fontsize to 11.5

[ved-rivos]

I can just change the fontsize to 11.5

Thanks! That looks good.

[ved-rivos]

@kbroch-rivosinc

1. Is there a way to fix how & gets rendered so it looks like a "&" Like this:

[wmat]

Try pointing docs-resources at the most recent commit. I had to add a font for sans-serif glyphs.

Bill Traynor Documentation Build and Release Engineer RISC-V International

Join us in Munich, Germany at RISC-V Summit Europe https://riscv-europe.org/summit/2024/ from 24-28 June. Be a part of the new wave of European computing innovation!

On Wed, Jun 5, 2024 at 12:54 PM Ved Shanbhogue @.***> wrote:

@kbroch-rivosinc https://github.com/kbroch-rivosinc

1. Is there a way to fix how & gets rendered so it looks like a "&" image.png (view on web) https://github.com/riscv-non-isa/riscv-iommu/assets/91900059/1e36070f-6d82-4937-b5ee-0b4dd0429328 Like this: image.png (view on web) https://github.com/riscv-non-isa/riscv-iommu/assets/91900059/01fae62b-8c3f-4e0b-8491-b527b3863f59

— Reply to this email directly, view it on GitHub https://github.com/riscv-non-isa/riscv-iommu/pull/342#issuecomment-2150528129, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAN6ZCIHRBXLHZ7UNQETWDZF47CXAVCNFSM6AAAAABIXBPGEOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJQGUZDQMJSHE . You are receiving this because you were mentioned.Message ID: @.***>

[kbroch-rivosinc]

Try pointing docs-resources at the most recent commit. I had to add a font for sans-serif glyphs.

Unfortunately that didn't change anything. Ved's example is using asciidoc monospace which in the pdf style yaml file maps to https://sk.fonts2u.com/m-1mn-medium.font which is where that funky ampersand is coming from.

@ved-rivos : where did the MCG example come from? I'm guessing that it is a formula which is why it is rendering with a different font (non-monospaced) which allows for a nice looking ampersand.

[ved-rivos]

where did the MCG example come from?

I grabbed that from the PCIe spec PDF as an example of how I wish it rendered.

[ved-rivos]

Ved's example is using asciidoc monospace which in the pdf style yaml file maps to https://sk.fonts2u.com/m-1mn-medium.font which is where that funky ampersand is coming from.

This is the source for that:

(A >> 12) & ~msi_addr_mask = (msi_addr_pattern & ~msi_addr_mask)

[ved-rivos]

If I use latexmath formula (from the CBQRI spec) it renders better. I can do that to update these formulas to latexmath

(source: latexmath:[Effective-MCID = (RCID \ll P) \mid (MCID \, \text{&} \, ((1 \ll P) - 1))] )

[kbroch-rivosinc]

@wmat : any reason we can't use a open source (apache) font like Roboto Mono as the codespan font?

[wmat]

No reason we can't. It'll require installation into docs-resources as well as to any repos not relying on docs-resources, such as riscv-isa-manual.

[kbroch-rivosinc]

No reason we can't. It'll require installation into docs-resources as well as to any repos not relying on docs-resources, such as riscv-isa-manual.

Ok, I'll put that PR in but first test it out on iommu.

Is there any reason why riscv-isa-manual isn't using docs-resources? If not I can put a PR in to have it start using it.

I'd also like to resolve the minor differences between the two pdf styles yamls so that all specs use the same instead of different if they are in their separate repo vs. the isa-manual.

[wmat]

I asked Andrew and he said to go ahead and templatize riscv-isa-manual so long as it doesn't break anything. I may have an issue out there for this already in docs-sig.

[ved-rivos]

any reason we can't use a open source (apache) font like Roboto Mono

Jetbrains Mono seems like a popular font for code - better ligatures support and disambiguation between things like O and 0.

[ved-rivos]

@kbroch-rivosinc another nit is the bullets - they are rendered as somewhat tiny.

A bit larger bullets would make it look better: Not sure if this is a easy fix.

[ved-rivos]

And one last nit is on list of figures and tables. They show up a bit wavy when going from one digit to two. and not aligned like below:

Also not sure if this would be an easy fix.

[ved-rivos]

And very last nit. In previous template the TOC used to have these nice ... between text and page number:

With new theme those dots are gone and is now harder to eyeball section to page number

Also also the page numbers in new theme seem to have variable width causing that column of numbers to look visually wavy

[ved-rivos]

The icon for the informative note used to have a nice circled i before and now its rendered as a note. The circled i was more pleasant. This is subjective. So please decide what looks good to you :). I like the first one. Before:

New template:

[ved-rivos]

One nit is about how the bibliography entries get rendered. When they wrap the, second line starts from under the reference number.

Instead of being aligned like following:

It looks much nicer aligned.

[wmat]

I believe I can address the majority of your concerns in the theme. However, some of these things were expressly requested to be removed, i.e. the toc-dot-leader

I can turn it back on if you think it's better though.

[ved-rivos]

I believe I can address the majority of your concerns in the theme. However, some of these things were expressly requested to be removed, i.e. the toc-dot-leader

Thanks! Specifically the dot-leader if that was a conscious decision then I dont feel strongly about reverting it. If the following could be fixed that would be great:

• Jetbrains mono font for codespan
• Waviness of the page number column in TOC
• Waviness and alignment of the list of figures and tables
• Slightly larger bullets and sub-bullets
• note icon
• alignment/justification of the bibligraphy entries.

[kbroch-rivosinc]

@ved-rivos : IMO this pdf style discussion has grown outside the scope of this PR. I'd like to take a more systematic review of the pdf theme and have filed this issue to do so: https://github.com/riscv-admin/docs-sig/issues/50 I've added this PR to the issue to make sure this discussion is considered

In the meantime, I'd like to get https://github.com/riscv-admin/docs-sig/issues/48 done so this and all specs can incorporate the unified (isa-manual) style.

[ved-rivos]

Okay. Looks like we will miss the getting these fixes for the planned publication of the PDF for 6/15.

[kbroch-rivosinc]

With this commit https://github.com/riscv-non-isa/riscv-iommu/pull/342/commits/5d7181e423e102f3ef0009ea85fef6cbf6e8f256 I'm done with what I was trying to accomplish with this PR.

[ved-rivos]

Thanks. Would asciidoc allow overriding the theme through the header so I can fix the other things like the bullet size and such locally?

[wmat]

I will address those things tomorrow, Ved. You could always point your local build of the spec at a customized theme and build the PDF locally for a one off build.

Bill Traynor Documentation Build and Release Engineer RISC-V International

Join us in Munich, Germany at RISC-V Summit Europe https://riscv-europe.org/summit/2024/ from 24-28 June. Be a part of the new wave of European computing innovation!

On Thu, Jun 6, 2024 at 7:59 PM Ved Shanbhogue @.***> wrote:

Thanks. Would asciidoc allow overriding the theme through the header so I can fix the other things like the bullet size and such locally?

— Reply to this email directly, view it on GitHub https://github.com/riscv-non-isa/riscv-iommu/pull/342#issuecomment-2153597288, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAN6ZEHDVZXOQJFAS7W5OTZGDZVPAVCNFSM6AAAAABIXBPGEOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJTGU4TOMRYHA . You are receiving this because you were mentioned.Message ID: @.***>

[ved-rivos]

I will address those things tomorrow, Ved.

Thanks much. I only have a goal to publish an updated revision by 6/15. I will wait for your update!

[wmat]

Hi @ved-rivos , I moved the docs-resources to the latest and it addresses most of your concerns I think. The dot-leader is back in the TOC and the note admonition is the old circled i again. I don't see a List of Figures in the spec yet. Also, I'm still trying to figure out the bibliography alignment.

[ved-rivos]

@wmat Thanks a bunch! I will apply this PR then.

[wmat]

Sorry, I pushed to main w/o a PR.

[ved-rivos]

@wmat Please see the list of figures and tables in https://github.com/riscv-non-isa/riscv-iommu/actions/runs/9421593666

I see the following issues still with the new theme:

1. Bullets are tiny
2. The note admonition did not change to circles
3. The mono text is not updated - still see the oddly rendered "&" and "~"
4. No dot leader in TOC So looks like the build is not picking up your latest theme?

[wmat]

Shoot, you're right. OK, now that there is only 1 theme is docs-resources I'll update it with your recommendations.