From 5e82281fac35508f641723e67a47d5c75a2d1f7c Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Fri, 23 Aug 2024 08:59:34 -0500 Subject: [PATCH 01/17] Update writing.adoc making id unique Signed-off-by: Kersten Richter --- src/writing.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/writing.adoc b/src/writing.adoc index db51440..cb702e8 100644 --- a/src/writing.adoc +++ b/src/writing.adoc @@ -173,7 +173,7 @@ Avoid words such as "just", "simply", "easy", "easily", or "simple". These words These guidelines were adapted from the https://kubernetes.io/docs/contribute/style/style-guide/[Documentation style guidelines] for Kubernetes in August of 2024. ==== -[[style-guidelines]] +[[other-style-guidelines]] === Other style guidelines Other style guidelines for reference: From bbed23a70ad7bd60128a9c4b110eea104ae73811 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Sun, 25 Aug 2024 12:53:33 -0500 Subject: [PATCH 02/17] Update authoring.adoc Signed-off-by: Kersten Richter --- src/authoring.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/authoring.adoc b/src/authoring.adoc index 1c21b21..3e6b0dc 100644 --- a/src/authoring.adoc +++ b/src/authoring.adoc @@ -12,7 +12,7 @@ Asciidoctor toolchains: Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates repo for information about the automated build processes. -The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-templates/commit/5c18cc9761eb3f6516975ee0c109729a4ce66b93[document] that takes you through a local install process that supports all of the required features for a local build. +The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[document] that takes you through a local install process that supports all of the required features for a local build. Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output by using the following command: From 567b82ecdde5f8020d46c97a71eb6d144aa7e04b Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 27 Aug 2024 09:11:23 -0500 Subject: [PATCH 03/17] Update writing.adoc fixing the broken sentence Signed-off-by: Kersten Richter --- src/writing.adoc | 29 +++++------------------------ 1 file changed, 5 insertions(+), 24 deletions(-) diff --git a/src/writing.adoc b/src/writing.adoc index cb702e8..bd26232 100644 --- a/src/writing.adoc +++ b/src/writing.adoc @@ -35,7 +35,7 @@ Exception: Use passive voice if active voice leads to an awkward construction. === Use simple and direct language -Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." +Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." Direct language is easier to translate. [cols="1,1"] |=== @@ -54,6 +54,8 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying === Address the reader as "you" +Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" that you're describing. Does it mean the RISC-V team, the RISC-V members, open source people, hardware people, or even everyone? + [cols="1,1"] |=== |Yes @@ -70,7 +72,7 @@ An exception to this rule is the rationale sections. === Avoid Latin phrases -Prefer English terms over Latin abbreviations. +Prefer English terms over Latin abbreviations. Latin terms can be difficult for translation because it adds an additional language to translate. [cols="1,1"] |=== @@ -84,27 +86,6 @@ Prefer English terms over Latin abbreviations. |i.e., |=== - -=== Avoid using "we" - -Using "we" in a sentence can be confusing, because the reader might not know -whether they're part of the "we" you're describing. - -[cols="1,1"] -|=== -|Yes -|No - -|Version 1.4 includes -|In version 1.4, we have added - -|RISC-V provides a new feature for -|We provide a new feature - -|This page teaches you how to create CSRs. -|In this page, we are going to learn about CSRs. -|=== - === Avoid jargon and idioms Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. @@ -148,7 +129,7 @@ considered new in a few months. === Avoid words that assume a specific level of understanding -Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel +Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel not up to the task. [cols="1,1"] |=== From c24bbaa13a1c76f1557207b32f8eed25e213427b Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Thu, 5 Sep 2024 14:05:49 -0500 Subject: [PATCH 04/17] Update blocks_notes_markers.adoc Updating with admonitions Signed-off-by: Kersten Richter --- src/blocks_notes_markers.adoc | 106 ++++++++++++++++------------------ 1 file changed, 51 insertions(+), 55 deletions(-) diff --git a/src/blocks_notes_markers.adoc b/src/blocks_notes_markers.adoc index e835e04..42a5ffb 100644 --- a/src/blocks_notes_markers.adoc +++ b/src/blocks_notes_markers.adoc @@ -1,42 +1,29 @@ [[blocks_notes_markers]] === Admonition blocks -Five kinds of standard admonition blocks are available in AsciiDoc and these can be mapped to either default or custom icons. +Five kinds of standard admonition blocks are available in AsciiDoc. RISC-V uses these 5 standards with the default icons. Note that the admonition type is not displayed, only the icon. -[source,adoc] ----- -[NOTE] -==== -This is an example of an admonition block. +Note:: Highlight extra information that should stand out from the rest of the text. A "by the way, you should know this" statement. -Unlike an admonition paragraph, it may contain any AsciiDoc content. -The style can be any one of the admonition labels: +Caution:: Warns users about a condition or action that can lead to bad outcomes such as personal injury or damage equipment). A "we don’t recommend" statement. -* NOTE -* TIP -* WARNING -* CAUTION -* IMPORTANT -==== ----- +Warning:: Warns users about a situation that is undesirable. A "Do not do this!" or "You must do this" statement. -This renders as: +Important:: Information that a user must have. For example, "After you set your password, you cannot change it." -[NOTE] -==== -This is an example of an admonition block. +Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why other options were discontinued. RISC-V tech team is working on a solution that will allow these admonitions to be turned off. -Unlike an admonition paragraph, it may contain any AsciiDoc content. -The style can be any one of the admonition labels: +As a general rule, follow these guidelines for admonitions: -* NOTE -* TIP -* WARNING -* CAUTION -* IMPORTANT -==== +* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. +* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) +* Do not include results, steps, or prerequisites in admonitions. +* Make your admonition clear and concise. + +==== Single paragraph admonition -For a single paragraph admonition, simply use a double colon: +For a single paragraph admonition, use a double colon: [source,adoc] ---- @@ -47,52 +34,61 @@ which renders as: NOTE: Note content. -Alternate octicons: - -* alert-24 -* comment-discussion-24 -* flame-24 -* info-24 -* pencil-24 -* question-24 -* sheild-24 -* squirrel-24 -* zap-24 - +==== Admonition blocks -Another example of an admonition block: +An admonition block can contain any AsciiDoc content. [source,adoc] ---- [IMPORTANT] -.Feeding the Werewolves ==== -While werewolves are hardy community members, keep in mind the following dietary concerns: +As a general rule, follow these guidelines for admonitions: -. They are allergic to cinnamon. -. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens. -. Celery makes them sad. +* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. +* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) +* Do not include results, steps, or prerequisites in admonitions. +* Make your admonition clear and concise. ==== ---- -Rendered: +which renders as: [IMPORTANT] -.Feeding the Werewolves ==== -While werewolves are hardy community members, keep in mind the following dietary concerns: +As a general rule, follow these guidelines for admonitions: -. They are allergic to cinnamon. -. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens. -. Celery makes them sad. +* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. +* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) +* Do not include results, steps, or prerequisites in admonitions. +* Make your admonition clear and concise. ==== +==== Admonition with a title -https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#key-prefix-admonition-icon +You can add a title to your admonition block. + +[source,adoc] +---- +[WARNING] +.Security vulnerability +==== +*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +==== +---- + +Rendered: + +[WARNING] +.Security vulnerability +==== +*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +==== -The default admonition icons don't look right for RISC-V specification, and alternate icons and colors have been set in risc-v_spec-pdf.yml. and will be considered. +==== RISC-V admonition icon colors -Current icons, edited to tone down color: +The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <> table. NOTE: note From 54eee2107f84d153d7dbc5f2177b7f14fdc62f3e Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Thu, 5 Sep 2024 14:49:39 -0500 Subject: [PATCH 05/17] Update blocks_notes_markers.adoc Signed-off-by: Kersten Richter --- src/blocks_notes_markers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/blocks_notes_markers.adoc b/src/blocks_notes_markers.adoc index 42a5ffb..b0af4e7 100644 --- a/src/blocks_notes_markers.adoc +++ b/src/blocks_notes_markers.adoc @@ -1,7 +1,7 @@ [[blocks_notes_markers]] === Admonition blocks -Five kinds of standard admonition blocks are available in AsciiDoc. RISC-V uses these 5 standards with the default icons. Note that the admonition type is not displayed, only the icon. +Five kinds of standard admonition blocks are available in AsciiDoc. RISC-V uses these 5 standards with the default icons. Note that the admonition type is not displayed, only the icon. Note:: Highlight extra information that should stand out from the rest of the text. A "by the way, you should know this" statement. @@ -67,7 +67,7 @@ As a general rule, follow these guidelines for admonitions: ==== Admonition with a title -You can add a title to your admonition block. +You can add a title to your admonition block. [source,adoc] ---- From 3c6c75609fbe07edb593b773b9aa74333978b7c9 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Thu, 5 Sep 2024 14:54:03 -0500 Subject: [PATCH 06/17] Update blocks_notes_markers.adoc Signed-off-by: Kersten Richter --- src/blocks_notes_markers.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/blocks_notes_markers.adoc b/src/blocks_notes_markers.adoc index b0af4e7..4e3f3bd 100644 --- a/src/blocks_notes_markers.adoc +++ b/src/blocks_notes_markers.adoc @@ -20,7 +20,7 @@ As a general rule, follow these guidelines for admonitions: * Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) * Do not include results, steps, or prerequisites in admonitions. * Make your admonition clear and concise. - + ==== Single paragraph admonition For a single paragraph admonition, use a double colon: @@ -88,7 +88,7 @@ Rendered: ==== RISC-V admonition icon colors -The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <> table. +The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <>. NOTE: note From af0b145cbc1426ea1b39a87436a96ea60b296278 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Thu, 5 Sep 2024 15:29:17 -0500 Subject: [PATCH 07/17] Update style-guidelines.adoc Signed-off-by: Kersten Richter --- src/style-guidelines.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/style-guidelines.adoc b/src/style-guidelines.adoc index b9c2820..f720b4f 100644 --- a/src/style-guidelines.adoc +++ b/src/style-guidelines.adoc @@ -8,16 +8,16 @@ Whether you are creating a new extention or even a stand alone doc for RISC-V, f Follow these basic formatting guidelines. -* Use _italic_ for new terms. +* Use _italic_ for new terms. The _Atomic Layer Deposition_ is a layer-by-layer process that results in the deposition of thin films one atomic layer at a time in a highly controlled manner. * Use `monospace` for the following items: -** Filenames -** Directories -** Paths -** Inline code -** Commands +** Filenames: `a-st-ext.adoc` +** Directories: The `src` directory. +** Paths: `https://github.com/riscv/riscv-isa-manual/blob/main/src/a-st-ext.adoc` +** Inline code: The `push()` method adds elements to an array. +** Commands: The `make` command. * Use *`monospace bold`* for the following items: -** Hex numbers. Hex numbers start with `0x`. -** Binary numbers. Binary numbers start with `0b`. +** Hex numbers. Hex numbers start with *`0x`*. +** Binary numbers. Binary numbers start with *`0b`*. ** Non-base 10 literals ** Non-base 10 number ranges From 9b0c4aeec30c4060a374f62a11c66fbb54452b29 Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Mon, 9 Sep 2024 14:16:37 -0700 Subject: [PATCH 08/17] clean up wording, add link to adoc docs, add examples to see icons Signed-off-by: Kevin Broch --- src/blocks_notes_markers.adoc | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/blocks_notes_markers.adoc b/src/blocks_notes_markers.adoc index 4e3f3bd..8daabb5 100644 --- a/src/blocks_notes_markers.adoc +++ b/src/blocks_notes_markers.adoc @@ -1,18 +1,30 @@ [[blocks_notes_markers]] === Admonition blocks -Five kinds of standard admonition blocks are available in AsciiDoc. RISC-V uses these 5 standards with the default icons. Note that the admonition type is not displayed, only the icon. +Five types of standard link:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonition blocks] are available in AsciiDoc. RISC-V uses these five types with the default icons. + +NOTE: The admonition type is not displayed, only the icon. Note:: Highlight extra information that should stand out from the rest of the text. A "by the way, you should know this" statement. -Caution:: Warns users about a condition or action that can lead to bad outcomes such as personal injury or damage equipment). A "we don’t recommend" statement. +NOTE: example of note type + +Caution:: Cautions users about a condition or action that can lead to bad outcomes such as personal injury or damage equipment. A "we don’t recommend" statement. + +CAUTION: example of caution type Warning:: Warns users about a situation that is undesirable. A "Do not do this!" or "You must do this" statement. +WARNING: example of warning type + Important:: Information that a user must have. For example, "After you set your password, you cannot change it." +IMPORTANT: example of important type + Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why other options were discontinued. RISC-V tech team is working on a solution that will allow these admonitions to be turned off. +TIP: example of tip type + As a general rule, follow these guidelines for admonitions: * Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. From 909761d5690d5933bfbb188d451eba792520aafa Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Mon, 9 Sep 2024 15:10:25 -0700 Subject: [PATCH 09/17] refactor preface, add doc-sig email group link, remove markdown commentary, point to template repo Signed-off-by: Kevin Broch --- src/colophon.adoc | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/src/colophon.adoc b/src/colophon.adoc index 0c5745d..d533f3e 100644 --- a/src/colophon.adoc +++ b/src/colophon.adoc @@ -1,20 +1,14 @@ [colophon] = Preface -This document demonstrates the use of AsciiDoc for RISC-V specifications, with the goal of capturing information that will result in effective and efficient collaboration throughout the community. +This document demonstrates the use of AsciiDoc for RISC-V specifications, with the goal of capturing information that will result in effective and efficient communication of the specs. -AsciiDoc is currently the most feature-rich of the popular lightweight markup languages based on markdown. An Open Source effort, it is gaining wider adoption and there is an AsciiDoc working group. RISC-V also supports some documentation associated with testing that is written in another popular lightweight markup language, Restructured Text. +AsciiDoc is currently the most feature-rich of the popular lightweight markup languages. As an Open Source effort, it is gaining wider adoption and there is an link:https://asciidoc-wg.eclipse.org/[AsciiDoc working group] to standardize the AsciiDoc specification as well as other ways to get involved. -It’s helpful to think of AsciiDoc as https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/[Markdown grown up]. People in tech often have impulses to re-invent markdown with a brand new lightweight markup language of their own. As appealing as that idea can be, it is inherently flawed. Publishing, like music, can have simple forms, but when fully featured is quite complex. Everyone who has attempted to build upon Markdown to create a simple and feature-rich publishing solution faces the same reality--as we add features, the process necessarily becomes complex. +RISC-V specifications require the use of AsciiDoc markup and the Asciidoctor toolchain with advanced publishing features that are provided by several add-ons. The repo allows you to jump into writing a spec. -RISC-V specifications require the use of AsciiDoc markup and the Asciidoctor toolchain with advanced publishing features that are provided by several add-ons. The templates in this repo allow you to jump in with a hands-on approach and build a PDF using the example files. -[TIP] -==== -Because AsciiDoc is gaining in popularity, there are opportunities contributors to the AsciiDoc specification while it is still being developed. You might want to view what Dan Allen and Sarah White are doing. Along with a growing open source community, they support both AsciiDoc and the Asciidoctor toolchain. Feel free to find out about the working group, the specification under development, the toolchain and its various plugins, and other projects that make use of AsciiDoc. -==== - -If you'd like to add to the documentation build toolchain, please join the RISC-V group devoted to supporting the RISC-V publishing templates. As members of an Open Source community, we like to support other open source efforts, and for that reason we enourage coordination in adding features so that everyone benefits. +If you'd like to discuss the documentation build toolchain, please join the RISC-V group link:https://lists.riscv.org/g/sig-documentation[sig-documentation] devoted to supporting the RISC-V spec documentation. As members of an Open Source community, we like to support other open source efforts, and for that reason we encourage coordination in adding features so that everyone benefits. [NOTE] ==== From 127c5e1fc91c33ddcf502615c3c17878519de15d Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Tue, 10 Sep 2024 13:44:25 -0700 Subject: [PATCH 10/17] update link to discuss asciidoc questions, remove ruby version note as it doesn't apply anymore Signed-off-by: Kevin Broch --- src/a_few_basics.adoc | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 9618cb2..d4ce7fd 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -9,14 +9,10 @@ For details and additional options, see: * AsciiDoc http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[quick reference]. * Asciidoctor http://asciidoctor.org/docs/user-manual/[user manual]. -In addition, you can ask questions in the https://discuss.asciidoctor.org/[Asciidoctor discussion list]. - -As is true of any complex process, AsciiDoc/Asciidoctor has some quirks. Please be certain to use the templates, as the templates provide you with files that result in fully featured PDF output. +In addition, you can ask questions in Best practice is to test the PDF build frequently to ensure that you have not accidentally introduced something that breaks the build. -WARNING: PDF generation requires the use of Ruby 2.7.2. - [NOTE] ==== Send questions to help@riscv.org. From ed3fccc990f7459662306cf905ae820a7c311893 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:06:51 -0500 Subject: [PATCH 11/17] Update docs-dev-guide.adoc Signed-off-by: Kersten Richter --- src/docs-dev-guide.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index fd46c88..540f3be 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -2,8 +2,6 @@ = Authoring and Editing RISC-V Specifications :description: A working template for documenting RISC-V architecture in asciidoc :company: RISC-V.org -:revdate: 12/2021 -:revnumber: 0. :revremark: Pre-release version //development: assume everything can change //stable: assume everything could change From 5f49fc30bcaf867fae18d08ccf76a9ccc37c23b4 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:12:55 -0500 Subject: [PATCH 12/17] Update Makefile Signed-off-by: Kersten Richter --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 55bd97c..e7b17ea 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ # the Doc Template for RISC-V Extensions. DATE ?= $(shell date +%Y-%m-%d) -VERSION ?= v1.0.0 +VERSION ?= 3 REVMARK ?= Draft DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ riscvintl/riscv-docs-base-container-image:latest From 8551ef389e7864c528584ae5a9c3735244f39d22 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:18:10 -0500 Subject: [PATCH 13/17] Update Makefile changing version back Signed-off-by: Kersten Richter --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index e7b17ea..55bd97c 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ # the Doc Template for RISC-V Extensions. DATE ?= $(shell date +%Y-%m-%d) -VERSION ?= 3 +VERSION ?= v1.0.0 REVMARK ?= Draft DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ riscvintl/riscv-docs-base-container-image:latest From e8a8a6742324384cd58e045640debf5524be1449 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:25:15 -0500 Subject: [PATCH 14/17] Update build-pdf.yml Signed-off-by: Kersten Richter --- .github/workflows/build-pdf.yml | 145 +++++++++++++++++--------------- 1 file changed, 78 insertions(+), 67 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index a5581a7..ae0a56a 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,74 +1,85 @@ ---- -name: Create Specification Document +# Makefile for RISC-V Doc Template +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +# International License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to +# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. +# +# SPDX-License-Identifier: CC-BY-SA-4.0 +# +# Description: +# +# This Makefile is designed to automate the process of building and packaging +# the Doc Template for RISC-V Extensions. -# The workflow is triggered by pull request, push to main, and manual dispatch. -on: - workflow_dispatch: - inputs: - version: - description: 'Release version, e.g. X.Y.Z:' - required: true - type: string - revision_mark: - description: 'Set revision mark as Draft, Release or Stable:' - required: true - type: string - default: Draft - prerelease: - description: Tag as a pre-release? - required: false - type: boolean - default: true - draft: - description: Create release as a draft? - required: false - type: boolean - default: false - pull_request: - push: - branches: - - main +DOCS := \ + docs-dev-guide.adoc -jobs: - build: - runs-on: ubuntu-latest +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.0.0 +REVMARK ?= Draft +ifneq ($(SKIP_DOCKER),true) + DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \ + riscvintl/riscv-docs-base-container-image:latest \ + /bin/sh -c + DOCKER_QUOTE := " +endif - steps: - # Step 1: Checkout the repository - - name: Checkout repository - uses: actions/checkout@v3 - with: - submodules: recursive +SRC_DIR := src +BUILD_DIR := build - # Step 2: Pull the latest RISC-V Docs container image - - name: Pull Container - run: docker pull riscvintl/riscv-docs-base-container-image:latest +DOCS_PDF := $(DOCS:%.adoc=%.pdf) +DOCS_HTML := $(DOCS:%.adoc=%.html) - # Step 3: Build Files - - name: Build Files - run: make - env: - VERSION: v${{ github.event.inputs.version }} - REVMARK: ${{ github.event.inputs.revision_mark }} +XTRA_ADOC_OPTS := +ASCIIDOCTOR_PDF := asciidoctor-pdf +ASCIIDOCTOR_HTML := asciidoctor +OPTIONS := --trace \ + -a compress \ + -a mathematical-format=svg \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ + $(XTRA_ADOC_OPTS) \ + -D build \ + --failure-level=ERROR +REQUIRES := --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical - # Step 4: Upload the built PDF files as a single artifact - - name: Upload Build Artifacts - uses: actions/upload-artifact@v3 - with: - name: Build Artifacts - path: ${{ github.workspace }}/build/*.pdf - retention-days: 30 +.PHONY: all build clean build-container build-no-container build-docs - # Create Release - - name: Create Release - uses: softprops/action-gh-release@v1 - with: - files: ${{ github.workspace }}/build/*.pdf - tag_name: v${{ github.event.inputs.version }} - name: Release ${{ github.event.inputs.version }} - draft: ${{ github.event.inputs.draft }} - prerelease: ${{ github.event.inputs.prerelease }} - env: - GITHUB_TOKEN: ${{ secrets.GHTOKEN }} - if: github.event_name == 'workflow_dispatch' - # This condition ensures this step only runs for workflow_dispatch events. +all: build + +build-docs: $(DOCS_PDF) $(DOCS_HTML) + +vpath %.adoc $(SRC_DIR) + +%.pdf: %.adoc + $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) + +%.html: %.adoc + $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) + +build: + @echo "Checking if Docker is available..." + @if command -v docker >/dev/null 2>&1 ; then \ + echo "Docker is available, building inside Docker container..."; \ + $(MAKE) build-container; \ + else \ + echo "Docker is not available, building without Docker..."; \ + $(MAKE) build-no-container; \ + fi + +build-container: + @echo "Starting build inside Docker container..." + $(MAKE) build-docs + @echo "Build completed successfully inside Docker container." + +build-no-container: + @echo "Starting build..." + $(MAKE) SKIP_DOCKER=true build-docs + @echo "Build completed successfully." + +clean: + @echo "Cleaning up generated files..." + rm -rf $(BUILD_DIR) + @echo "Cleanup completed." From ec07d32e31b5b5c46f36130a4d8490c65dc27218 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:31:55 -0500 Subject: [PATCH 15/17] Update build-pdf.yml Signed-off-by: Kersten Richter --- .github/workflows/build-pdf.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index ae0a56a..fe4b60f 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -45,7 +45,7 @@ OPTIONS := --trace \ REQUIRES := --require=asciidoctor-diagram \ --require=asciidoctor-mathematical -.PHONY: all build clean build-container build-no-container build-docs +.PHONY: all build clean build-container build-no-containee all: build From d98949c2f5ff21fc70f35723606b4da18e42b3e4 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:32:43 -0500 Subject: [PATCH 16/17] Update build-pdf.yml Signed-off-by: Kersten Richter --- .github/workflows/build-pdf.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index fe4b60f..31c079a 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -45,7 +45,7 @@ OPTIONS := --trace \ REQUIRES := --require=asciidoctor-diagram \ --require=asciidoctor-mathematical -.PHONY: all build clean build-container build-no-containee +.PHONY: all build clean build-container build-no-container all: build From d2227ef2ff36f93b32e296f0c4a1cfe204441a2a Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Mon, 30 Sep 2024 11:35:00 -0500 Subject: [PATCH 17/17] Update build-pdf.yml Signed-off-by: Kersten Richter --- .github/workflows/build-pdf.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 31c079a..e0f4d90 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -12,8 +12,7 @@ # This Makefile is designed to automate the process of building and packaging # the Doc Template for RISC-V Extensions. -DOCS := \ - docs-dev-guide.adoc +DOCS := \docs-dev-guide.adoc DATE ?= $(shell date +%Y-%m-%d) VERSION ?= v0.0.0