Skip to content
95 changes: 95 additions & 0 deletions src/vale.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,98 @@

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


=== 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."

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, vale can enforce this. However, it creates a LOT of noise so I disabled for now (and commented out in doc)


=== Camel case

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Why is "Camel" capitalized?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


=== 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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" ...

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking that in there might be a case where you are using "riscv" or a variant in code. I dunno - type=riscv or something like that. This type of case would be the only time that not using "RISC-V" is acceptable...


=== Conjunctions

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, more a guideline than a rule?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


* And
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* And

* But
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* But

* Or
* So

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These could just be an inline list:

Do not overuse conjunctions ("and", "but", "or", "so") when you begin a sentence.


=== Contractions

Avoid using contractions in Extension documentation. Contractions can cause ambiguity with translations.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Avoid using" or "Don't use" (haha!) "Do not use"?

Same for other similar cases below. Are we stating rules, or guidelines? Does Vale know the difference?

Is there a reason "Extension" is capitalized?


=== Ellipses

Avoid ellipses (...) to indicated omitted words. Instead, spell out the complete phrase or use words such as "and so on" to indicate that a list is not complete.

=== Em dashes

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An example? Non-doc-nerds may not know what an "em dash" is. ;-)


=== First person

Do not use words such as "I" or "we", unless you are indeed speaking on behalf of all of RISC-V.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"RISC-V" is an adjective, so should this be "RISC-V International"?


=== Gender neutral language

Avoid using language that specifies a gender, such as "he" or "woman". Instead, use words such as "the author" or "human".

=== Heading punctuation

Do not use punctuation in headings.

=== Heading

Headings use Title case: all nouns, verbs, adjectives, and adverbs are capitalized. Do not capitalize conjunctions, prepositions, or articles.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is "Title" capitalized here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably because I capitalized "Camel case". I am consistent! But I do want to call it out a bit and I think that lowercase hides the word.


=== Hyphens

Do not use hyphens unless that usage is approved. See Spelling.

=== Merge conflict markers

Do not include any Git merge conflict markers in your source text. For example, `<<<<<<< HEAD`.
Comment on lines +94 to +96

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


=== Oxford comma

Use the Oxford comma. It saves lives.

=== Pascal case

If you are using Pascal case (`PascalCase`), consider using backticks.

=== Repeated words

Words such as "the" or "and" can end up duplicated in text.
Comment on lines +110 to +112

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, vale looks for double words and flags them.


=== Sentence length

Try to keep sentences to an average of 32 words or fewer, and vary sentence lengths.

=== Slash

Rather than use a slash, use either "or" or "and".

=== Spacing

Use one space between words and after the end of sentences.

=== 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].

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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].

Check failure on line 116 in src/vale.adoc

View workflow job for this annotation

GitHub Actions / vale

[vale] src/vale.adoc#L116

[RedHat.Spacing] Keep one space between words in 'requires. If'.
Raw output
{"message": "[RedHat.Spacing] Keep one space between words in 'requires.  If'.", "location": {"path": "src/vale.adoc", "range": {"start": {"line": 116, "column": 407}}}, "severity": "ERROR"}

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a link for "Doc-Sig meeting"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


=== 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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