kasanovic
commented
4 years ago We would like to move away from Latex for the standard docs, but this is a longer term project as it will take significant time to reformat the spec.
Open ethindp opened 4 years ago
kasanovic
commented
4 years ago We would like to move away from Latex for the standard docs, but this is a longer term project as it will take significant time to reformat the spec.
ethindp
commented
4 years ago I would highly recommend Pandoc, then. It can help you get pretty far on that little project; it may not produce the exact equivalent that you want (in -- say -- markdown onr commonmark) but it will do most of the heavy lifting for you. Then all you have to do is read over it to verify that the output is acceptable and meets your standards.
On 11/24/19, Krste Asanovic notifications@github.com wrote:
We would like to move away from Latex for the standard docs, but this is a longer term project as it will take significant time to reformat the spec.
-- You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub: https://github.com/riscv/riscv-isa-manual/issues/455#issuecomment-557990097
-- Signed, Ethin D. Probst
ethindp
commented
4 years ago What makes this harder is the way that the specification presents instructions. Its hard for me (for instance) to interpret this (HTML translation with Pandoc):
M@R@F@R@O
& & & &
& & & &
12 & 5 & 3 & 5 & 7
offset[11:0] & base & width & dest & LOAD
O@R@R@F@R@O
& & & & &
& & & & &
7 & 5 & 5 & 3 & 5 & 7
offset[11:5] & src & base & width & offset[4:0] & STOREWouldn't it make more sense just to write the instruction syntax without using fancy diagrams or ways like this (like the ARM manuals do) or by using a table (like Intel does)? I'd love to help with this (was thinking of making an initial copy with mdbook and then allowing you guys to take over) but I'd like to at least get this down. There's another problem -- the tables. Take, for example, the table describing the immediate encoding variants. This gets translated into markdown (GitHub flavor) like so:
| | | | | | | | | | |
| :- | :- | :- | :----- | :- | :----- | :----- | :- | :----- | :- |
| | | | | | | | | | |
| | | | | | | R-type | | | |
| | | | | | | | | | |
| | | | | | I-type | | | | |
| | | | | | | | | | |
| | | | | | | S-type | | | |
| | | | | | | | | | |
| | | | | | | | | B-type | |
| | | | | | | | | | |
| | | | U-type | | | | | | |
| | | | | | | | | | |
| | | | | | | J-type | | | |
| | | | | | | | | | |I'm not precisely sure why this is so. I haven't looked at the latex, but this definitely doesn't look good to me (though I do use a screen reader). It does produce large tables with a bunch of empty rows and it makes it difficult to make sense of them. The resulting table looks like this:
| R-type | |||||||||
| I-type | |||||||||
| S-type | |||||||||
| B-type | |||||||||
| U-type | |||||||||
| J-type | |||||||||
Thoughts?
rmccrary
commented
4 years ago Over the past few years I have looked at and used many of the available presentation markup languages. A fundamental shift I have made is to move to one that is “semantics first, presentation second” which is opposite from Latex.
I have not found this harder to translate to than other markups, but much easier to automatically create all the design files, headers is one basic example, I want from the these source files. The already mentioned latex presentation constructs are difficult for most markups.
SAMX (a fork and extension of SAM: Semantic Authoring Language) on github is an example that is under heavy development and I am currently investigating. It is immature compared to Latex, but has the foundation I was looking for.
Rex
On Apr 18, 2020, at 4:04 PM, Ethin Probst notifications@github.com wrote:
What makes this harder is the way that the specification presents instructions. Its hard for me (for instance) to interpret this (HTML translation with Pandoc):
M@R@F@R@O & & & & & & & & 12 & 5 & 3 & 5 & 7 offset[11:0] & base & width & dest & LOAD O@R@R@F@R@O & & & & & & & & & & 7 & 5 & 5 & 3 & 5 & 7 offset[11:5] & src & base & width & offset[4:0] & STORE Wouldn't it make more sense just to write the instruction syntax without using fancy diagrams or ways like this (like the ARM manuals do) or by using a table (like Intel does)? I'd love to help with this (was thinking of making an initial copy with mdbook and then allowing you guys to take over) but I'd like to at least get this down. There's another problem -- the tables. Take, for example, the table describing the immediate encoding variants. This gets translated into markdown (GitHub flavor) like so:
R-type I-type S-type B-type U-type J-type I'm not precisely sure why this is so. I haven't looked at the latex, but this definitely doesn't look good to me (though I do use a screen reader). It does produce large tables with a bunch of empty rows and it makes it difficult to make sense of them. The resulting table looks like this:
R-type
I-type
S-type
B-type
U-type
J-type
Thoughts?— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.
mariomac
commented
3 years ago I had a partial success by compiling sources with htlatex command and then using Calibre to manually convert it. See the attached file to see the final results.
However:
The RISC-V Instruction Set ManualVolume II - Unknown.epub.zip
ethindp
commented
3 years ago Sorry for getting back to this so late. @mariomac How did you compile the spec with tlatex? Did you just alter the makefile and change all the pdflatex references to use tlatex instead? Are there any updates on this issue?
laoshaw
commented
2 years ago Tried to use pandoc to convert to html to no avail. It's much more convenient to read(and search and copy) over html instead of PDF sometimes. Can the manual have a html output some time?
apws
commented
1 year ago hi, I highly recommend asciidoc; in combination with chrome extension asciidoctorjs its wonderfully fast rendering default quite nice layouts, but I even forced the asciidoctorjs extension to use my custom theme with inverted headings and modified/unified source code color syntax (bit higher tweaks inside extensions highlightjs usage, but nothing drastic). Result is directly printable to PDF as superior book. Will probably publish something about it to github soon...
kito-cheng
commented
1 year ago it's branch for asciidoc format: https://github.com/riscv/riscv-isa-manual/tree/riscv-isa-asciidoc, IIRC RVI has decide isa manual will use asciidoc as major format, so eventually that will marge back into master branch.
wmat
commented
1 year ago On Mon, Oct 3, 2022 at 10:13 AM Kito Cheng @.***> wrote:
it's branch for asciidoc format: https://github.com/riscv/riscv-isa-manual/tree/riscv-isa-asciidoc, IIRC RVI has decide isa manual will use asciidoc as major format, so eventually that will marge back into master branch.
That is the current plan. I'm actively working to convert all of the master branch to asciidoc format on the riscv-isa-asciidoc branch. At a future point the asciidoc version of the specs will become the master branch.
— Reply to this email directly, view it on GitHub https://github.com/riscv/riscv-isa-manual/issues/455#issuecomment-1265506040, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAN6ZH2J5OANVGOMQUTGPDWBLSW7ANCNFSM4JE5LHIQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>
Would it be possible to provide an HTML/EPub version of the specification? I have tried translating the specification from its latex sources to HTML with Pandoc, but Pandoc takes a ridiculously long time to generate any output (its taken so long I've usually ctrl-c'd it). I've tried using latex2html, but that generates unsatisfactory output. I ask this because I have a visual impairment and it is difficult for me to read PDF files with my screen reader, and HTML is just so much easier (not just because of the ease of reading but the navigational enhancements too).