DO NOT MERGE - Update vale.adoc #70

kersten1 · 2025-04-25T14:57:09Z

Adding in options for review

Adding in options for review Signed-off-by: Kersten Richter <[email protected]>

ThinkOpenly · 2025-04-25T15:58:18Z

src/vale.adoc

@@ -24,3 +24,98 @@ Some of the errors that the AsciiDoc rules highlight include:

 The RISC-V style for Vale enforces the rules that are set by the RISC-V style guidelines. 

+=== Abbreviations
+
+Do not use punctuation in abbreviations.


What does this mean, exactly? (Maybe an example would help, but that would probably trigger Vale?)

I added: For example, do not use periods in IBM.

ThinkOpenly · 2025-04-25T15:58:54Z

src/vale.adoc

+
+=== Anthropomorphism
+
+Anthropomorphism is granting abilities to inanimate objects, such as "This code allows you to enable access." Instead, make the user the focus of the sentence: "You can use this code to enable access." 


Is this an actual rule, or a guideline? Does Vale enforce this?

ThinkOpenly · 2025-04-25T15:59:46Z

src/vale.adoc

+
+=== Camel case
+
+If you are using Camel case (`camelCase`), consider using backticks.


Is this a rule? What's the context in which this applies? (Not in a code block, I presume?)

Why is "Camel" capitalized?

As long as the word in Camel case is in backticks (as the word camelCase is in the example, it is ignored - including when in a code block. So think of it as a reminder to evaluate any word that uses Camel case as to why it isn't in backticks.

As to why I capitalized "Camel"? I suspect I was thinking about the word and capitalized it. I can lower case it, but it will erase the comment.

ThinkOpenly · 2025-04-25T16:01:41Z

src/vale.adoc

+
+=== Case sensitive terms
+
+Terms such as RISC-V are case sensitive. If your usage is in code, then be sure to place back ticks around the code phrase.


What does this mean, exactly? Is this only in inline code? Why is this necessary? What if I wanted to mention "SomeProject"?

Should "RISC-V" be in quotation marks?

RISC-V should always be capitalized. If you use "risc-v" then it is either an incorrect usage or it should be in back ticks, which is what we use for code phrases. Same with words such as CSR.

For "RISC-V" in particular, I was referring to the use in your original text. Since you say

Terms such as RISC-V ...

I am suggesting it should instead be

Terms such as "RISC-V" ...

I'm still not sure about usage in code. For example:

a = SomeFunction()

Are you suggesting additional backticks around "SomeFunction"?

Or, are you suggesting backticks only around code that has case-sensitive terms?

If the actual rule is "backtick all code", then this rule seems unnecessary.

ThinkOpenly · 2025-04-25T16:02:14Z

src/vale.adoc

+
+=== Conjunctions
+
+Do not overuse conjunctions when you begin a sentence, including the following conjunctions:


So, more a guideline than a rule?

This one will likely be set to suggestion and can be ignored. But should be considered as too many conjunctions can make your writing copy. And I don't think we want that. Or do we?

ThinkOpenly · 2025-04-25T16:44:30Z

src/vale.adoc

+=== Merge conflict markers
+
+Do not include any Git merge conflict markers in your source text. For example, `<<<<<<< HEAD`.


I think this is obvious and doesn't need to be explicitly stated.

Agreed but Vale will catch it and flag it if they sneak in there. And I've seen them in published docs.

I've also put PR in for it in pre-commit hook riscv/riscv-isa-manual#2006

ThinkOpenly · 2025-04-25T16:46:35Z

src/vale.adoc

+=== Repeated words
+
+Words such as "the" or "and" can end up duplicated in text. 


Also seems obvious, and I presume Vale will detect this?

Yup, vale looks for double words and flags them.

ThinkOpenly · 2025-04-25T16:51:32Z

src/vale.adoc

+
+=== Spelling
+
+The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].


"RISC-V" used as a noun here and elsewhere. My experience is that is discouraged, but I could be wrong?

ThinkOpenly · 2025-04-25T16:52:23Z

src/vale.adoc

+
+The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].
+
+RISC-V works with cutting edge technology and new words are to be expected. If you want to use a word that is not found in the Dictionary, you must first create an issue in the https://github.com/riscv-admin/riscv-vale/[Vale GitHub] repository. Your issue will be discussed at the Doc-Sig meeting. Please include the rationale for why your term should be included as well as any definitions that your term requires.  If approved, your term will be added to the spelling exception list as well as to the https://github.com/riscv/riscv-glossary[RISC-V glossary].


Add a link for "Doc-Sig meeting"?

Okay will add a link to https://lf-riscv.atlassian.net/browse/RVG-36

ThinkOpenly · 2025-04-25T16:54:11Z

src/vale.adoc

+
+=== Using
+
+To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not omit articles and prepositions that can increase the clarity of a sentence.


Replace "Do not omit" with "Use" ? (Seems very appropriate for this section! 😄 )

src/vale.adoc

Signed-off-by: Kersten Richter <[email protected]>

kersten1 · 2025-04-30T20:12:30Z

src/vale.adoc

+
+=== Em dashes
+
+Avoid em dashes. Instead use commas, parenthesis, or colons.


Suggested change

Avoid em dashes. Instead use commas, parenthesis, or colons.

Avoid em dashes. An em dash -- so called because it is the length of an English capital M -- sets off a comment in your text. Instead, use commas, parenthesis, or colons.

Removing the redundant sentence:

Avoid em dashes. An em dash -- so called because it is the length of an English capital M -- sets off a comment in your text. Instead, use commas, parenthesis, or colons.

src/vale.adoc

Signed-off-by: Kersten Richter <[email protected]>

kersten1 · 2025-04-30T20:14:42Z

src/vale.adoc

+
+=== Spelling
+
+The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].


Suggested change

The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].

The dictionary chosen for RISC-V International specification writing is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].

kersten1 · 2025-04-30T20:15:04Z

src/vale.adoc

+
+The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].
+
+RISC-V works with cutting edge technology and new words are to be expected. If you want to use a word that is not found in the Dictionary, you must first create an issue in the https://github.com/riscv-admin/riscv-vale/[Vale GitHub] repository. Your issue will be discussed at the Doc-Sig meeting. Please include the rationale for why your term should be included as well as any definitions that your term requires.  If approved, your term will be added to the spelling exception list as well as to the https://github.com/riscv/riscv-glossary[RISC-V glossary].


Suggested change

RISC-V works with cutting edge technology and new words are to be expected. If you want to use a word that is not found in the Dictionary, you must first create an issue in the https://github.com/riscv-admin/riscv-vale/[Vale GitHub] repository. Your issue will be discussed at the Doc-Sig meeting. Please include the rationale for why your term should be included as well as any definitions that your term requires. If approved, your term will be added to the spelling exception list as well as to the https://github.com/riscv/riscv-glossary[RISC-V glossary].

RISC-V International works with cutting edge technology and new words are to be expected. If you want to use a word that is not found in the Dictionary, you must first create an issue in the https://github.com/riscv-admin/riscv-vale/[Vale GitHub] repository. Your issue will be discussed at the Doc-Sig meeting. Please include the rationale for why your term should be included as well as any definitions that your term requires. If approved, your term will be added to the spelling exception list as well as to the https://github.com/riscv/riscv-glossary[RISC-V glossary].

kersten1 · 2025-04-30T20:15:35Z

src/vale.adoc

+
+=== Using
+
+To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not omit articles and prepositions that can increase the clarity of a sentence.


Suggested change

To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not omit articles and prepositions that can increase the clarity of a sentence.

To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not use articles and prepositions that can increase the clarity of a sentence.

Update vale.adoc

c85a3c4

Adding in options for review Signed-off-by: Kersten Richter <[email protected]>

ThinkOpenly suggested changes Apr 25, 2025

View reviewed changes

kersten1 commented Apr 30, 2025

View reviewed changes

src/vale.adoc Outdated Show resolved Hide resolved

Update src/vale.adoc

e1933c7

Signed-off-by: Kersten Richter <[email protected]>

kersten1 commented Apr 30, 2025

View reviewed changes

src/vale.adoc Outdated Show resolved Hide resolved

Update src/vale.adoc

76a90a3

Signed-off-by: Kersten Richter <[email protected]>

kersten1 commented Apr 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DO NOT MERGE - Update vale.adoc #70

DO NOT MERGE - Update vale.adoc #70

kersten1 commented Apr 25, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

ThinkOpenly Apr 25, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

ThinkOpenly Apr 30, 2025

ThinkOpenly Apr 30, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

kbroch-rivosinc May 6, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

ThinkOpenly Apr 25, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025

ThinkOpenly Apr 25, 2025

kersten1 Apr 30, 2025 •

edited

Loading

ThinkOpenly Apr 30, 2025

kersten1 Apr 30, 2025

kersten1 Apr 30, 2025

kersten1 Apr 30, 2025


		=== Anthropomorphism

		Anthropomorphism is granting abilities to inanimate objects, such as "This code allows you to enable access." Instead, make the user the focus of the sentence: "You can use this code to enable access."


		=== Camel case

		If you are using Camel case (`camelCase`), consider using backticks.


		=== Case sensitive terms

		Terms such as RISC-V are case sensitive. If your usage is in code, then be sure to place back ticks around the code phrase.


		=== Conjunctions

		Do not overuse conjunctions when you begin a sentence, including the following conjunctions:

		=== Merge conflict markers

		Do not include any Git merge conflict markers in your source text. For example, `<<<<<<< HEAD`.

		=== Repeated words

		Words such as "the" or "and" can end up duplicated in text.


		=== Spelling

		The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].


		The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].

		RISC-V works with cutting edge technology and new words are to be expected. If you want to use a word that is not found in the Dictionary, you must first create an issue in the https://github.com/riscv-admin/riscv-vale/[Vale GitHub] repository. Your issue will be discussed at the Doc-Sig meeting. Please include the rationale for why your term should be included as well as any definitions that your term requires. If approved, your term will be added to the spelling exception list as well as to the https://github.com/riscv/riscv-glossary[RISC-V glossary].


		=== Using

		To avoid ambiguity, replace "using" with either "by using" or "that uses". Do not omit articles and prepositions that can increase the clarity of a sentence.


		=== Em dashes

		Avoid em dashes. Instead use commas, parenthesis, or colons.

	Avoid em dashes. Instead use commas, parenthesis, or colons.
	Avoid em dashes. An em dash -- so called because it is the length of an English capital M -- sets off a comment in your text. Instead, use commas, parenthesis, or colons.

	The dictionary chosen for RISC-V is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].
	The dictionary chosen for RISC-V International specification writing is Webster's New College dictionary. You can find it online at https://www.yourdictionary.com/about/websters-new-world-college-dictionary.html[Webster's New World College Dictionary].

DO NOT MERGE - Update vale.adoc #70

Are you sure you want to change the base?

DO NOT MERGE - Update vale.adoc #70

Conversation

kersten1 commented Apr 25, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kersten1 Apr 30, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kersten1 Apr 30, 2025 •

edited

Loading