search

riscv-admin / docs-sig

The repository of the RISC-V Docs Team
https://jira.riscv.org/browse/RVG-36
Creative Commons Attribution 4.0 International
1 stars 0 forks source link

Discuss ways to pull instructions out of prose in spec to enable inst/page reference manual #44

Open kbroch-rivosinc opened 5 months ago

kbroch-rivosinc commented 5 months ago

one idea for quickly doing this could be to use asciidoc tags that then could be used to pull out the content with includes: https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/ in a separate document.

/cc @kersten1 @wmat @kasanovic

wmat commented 5 months ago

On Tue, Jun 4, 2024 at 1:01 PM Kevin Broch @.***> wrote:

one idea for quickly doing this could be to use asciidoc tags that then could be used to pull out the content with includes: https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/

Yep. I actually was thinking a way to exclude non-normative text from generated documents would be to move all non-normative text into their own files as tag filtering only works with the include macro.

—

Reply to this email directly, view it on GitHub https://github.com/riscv-admin/docs-sig/issues/44, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAN6ZEZEASCTILFB564CFDZFXXIBAVCNFSM6AAAAABIY5G7D2VHI2DSMVQWIX3LMV43ASLTON2WKOZSGMZTGOJYHA3DONQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>

kbroch-rivosinc commented 5 months ago

Yep. I actually was thinking a way to exclude non-normative text from generated documents would be to move all non-normative text into their own files as tag filtering only works with the include macro.

That's a good point. And actually I have that example here: https://github.com/riscv-admin/docs-sig/blob/main/projects/csr-format/wavedrom-input.adoc?plain=1#L9

Also if we wanted the potential to leave the non-normative text in the doc as is, we could surround it with https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/ like ifdef::non-norm[] block.

Assuming we are pulling out mostly wavedrom definitions, those could then be used to create the reference model with one item/page. Also table format from the wavedrom using a template to generate the table?