update spec to use latest docs-spec-template features #342
Conversation
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 riscv-non-isa#340 Signed-off-by: Kevin Broch <[email protected]>
|
@kbroch-rivosinc Thanks much! |
relates to riscv-non-isa/riscv-iommu#342 Signed-off-by: Kevin Broch <[email protected]>
|
@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 riscv/docs-resources#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 |
Signed-off-by: Kevin Broch <[email protected]>
|
@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...
|
related to riscv-non-isa/riscv-iommu#342 Signed-off-by: Kevin Broch <[email protected]>
|
I wouldn't modify the content, if you want monospace for those commands in the headings (section titles). The diff for tables is:
I can just change the fontsize to 11.5 |
Signed-off-by: Kevin Broch <[email protected]>
Thanks! That looks good. |
|
|
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
<#342 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAN6ZCIHRBXLHZ7UNQETWDZF47CXAVCNFSM6AAAAABIXBPGEOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJQGUZDQMJSHE>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
Signed-off-by: Kevin Broch <[email protected]>
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. |
I grabbed that from the PCIe spec PDF as an example of how I wish it rendered. |
This is the source for that:
|
|
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))] ) |
|
@wmat : any reason we can't use a open source (apache) font like Roboto Mono |
|
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. |
|
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. |
Jetbrains Mono seems like a popular font for code - better ligatures support and disambiguation between things like O and 0. |
|
@kbroch-rivosinc another nit is the bullets - they are rendered as somewhat tiny. A bit larger bullets would make it look better: |
|
And one last nit is on list of figures and tables. They show up a bit wavy when going from one digit to two. Also not sure if this would be an easy fix. |
|
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 |
|
The icon for the informative note used to have a nice circled New template: |
|
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. |
|
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. |
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:
|
|
@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: riscv-admin/docs-sig#50 I've added this PR to the issue to make sure this discussion is considered In the meantime, I'd like to get riscv-admin/docs-sig#48 done so this and all specs can incorporate the unified (isa-manual) style. |
|
Okay. Looks like we will miss the getting these fixes for the planned publication of the PDF for 6/15. |
Signed-off-by: Kevin Broch <[email protected]>
|
With this commit 5d7181e I'm done with what I was trying to accomplish with this PR. |
|
Thanks. Would asciidoc allow overriding the theme through the header so I can fix the other things like the bullet size and such locally? |
|
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
<#342 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAN6ZEHDVZXOQJFAS7W5OTZGDZVPAVCNFSM6AAAAABIXBPGEOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNJTGU4TOMRYHA>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
Thanks much. I only have a goal to publish an updated revision by 6/15. I will wait for your update! |
|
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. |
|
@wmat Thanks a bunch! I will apply this PR then. |
|
Sorry, I pushed to main w/o a PR. |
|
@wmat I see the following issues still with the new theme:
|
|
Shoot, you're right. OK, now that there is only 1 theme is docs-resources I'll update it with your recommendations. |
no spec content changes, just long list of workflow/infra change:
relates to #340