-
Notifications
You must be signed in to change notification settings - Fork 35
Update vale.adoc #70
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update vale.adoc #70
Changes from all commits
c85a3c4
e1933c7
76a90a3
aafe2f8
50b209c
dab1f5e
c0f2bfc
72773ef
62abf23
301f1b1
2a31cfa
443992e
48bb84c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||
---|---|---|---|---|
|
@@ -24,3 +24,112 @@ 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. For example, IBM does not contain any periods. | ||||
|
||||
//// | ||||
|
||||
=== 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" and "GitHub" 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 ("and", "but", "or", "so") when you begin a sentence. | ||||
|
||||
* And | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||
* But | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||
|
||||
=== Contractions | ||||
|
||||
Avoid using contractions in your documentation. Contractions can cause ambiguity with translations. You don't have to avoid them completely though. | ||||
|
||||
=== 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. 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. | ||||
|
||||
=== First person | ||||
|
||||
Do not use words such as "I" or "we", unless you are indeed speaking on behalf of all of RISC-V International. | ||||
|
||||
=== Friendly terminology | ||||
|
||||
It is RISC-V policy to use modern word choices for terminology that is friendly for everyone. See [Friendly Terminology](https://lf-riscv.atlassian.net/wiki/spaces/TAXX/pages/565510188/Friendly+Terminology) technical process for more information. | ||||
|
||||
=== 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. | ||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why is "Title" capitalized here? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Also seems obvious, and I presume Vale will detect this? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 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]. | ||||
|
||||
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]. | ||||
|
||||
=== Using | ||||
|
||||
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. | ||||
|
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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)