diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -268,69 +268,88 @@ | Name | Severity -| BrandTerms +| FreeBSD.BrandTerms | error -| ConsciousLanguage +| FreeBSD.ConsciousLanguage | warning -| Contractions -| suggestions +| FreeBSD.Contractions +| suggestion -| EOLSpacing +| FreeBSD.EOLSpacing | warning -| Hang +| FreeBSD.Hang | warning -| Hyphens +| FreeBSD.Hyphens | warning -| Repetition +| FreeBSD.Spacing +| error + +| FreeBSD.SuperfluousOptArgInLinks +| suggestion + +| FreeBSD.Weasel | warning -| Spacing +| Vale.Avoid | error -| Spelling -| warning +| Vale.Repetition +| error -| Weasel -| warning +| Vale.Spelling +| error + +| Vale.Terms +| error |=== [[writing-style-linting-vale-rules]] === Current Vale Rules -. BrandTerms: Like The FreeBSD Project every major vendors and Companies have specific rules on writing their Brand Name. According to the Copyright rules of The FreeBSD Foundation *freebsd* should be written as *FreeBSD*. +. FreeBSD.BrandTerms: Like The FreeBSD Project every major vendors and Companies have specific rules on writing their Brand Name. +According to the Copyright rules of The FreeBSD Foundation *freebsd* should be written as *FreeBSD*. Similar to that care should be taken to be respective to other's brand value and write PostgreSQL, Node.js, Let's Encrypt etc. Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/BrandTerms.yml# in the `doc` repository. -. Contractions: Contracted words should not be used. This rule avoids all contractions and suggests full words. +. FreeBSD.ConsciousLanguage: This rule proposes use of conscious languages so that sensitive words pointing to the color, age, race, sexual orientation of personnel are avoided. + +. FreeBSD.Contractions: Contracted words should not be used. +This rule avoids all contractions and suggests full words. -. Hang: `Hang` is often used to convey the meaning that the application has stopped responding. +. FreeBSD.EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation. + +. FreeBSD.Hang: `Hang` is often used to convey the meaning that the application has stopped responding. This rule proposes better wording. -. Repetition: Same words are often typed twice when leaving the keyboard and rejoining the work again. -This rule finds repeated words and warns the users. +. FreeBSD.Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong. -. Weasel: This rule handles avoiding weasel words. +. FreeBSD.Spacing: Often double spaces are hard to catch on plain eye which is addressed here. + +. FreeBSD.SuperfluousOptArgInLinks: Suggest to empty square brackets in `link:` macros when the displayed text coincides with the URL. + +. FreeBSD.Weasel: This rule handles avoiding weasel words. The uses of weasel words is controversial so at the moment the list of words are being evaluated and the severity level is marked as warning on. In case a frequently used word is marked as weasel word it should be removed from [.filename]#.vale/styles/FreeBSD/Weasel.yml# in the `doc` repository. -. ConsciousLanguage: This rule proposes uses of conscious languages like avoiding the words white/black/master/slave. +. Vale.Avoid: Enforces the *DO NOT USE* vocabulary terms for The FreeBSD Project. +If any word is found that should not be n the documentation the word should be added to the [.filename]#.vale/styles/Vocab/Terms/reject.txt# in the `doc` repository. +The list is empty at the moment. -. EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation. - -. Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong. +. Vale.Repetition: Same words are often typed twice when leaving the keyboard and rejoining the work again. +This rule finds repeated words and warns the users. -. Spacing: Often double spaces are hard to catch on plain eye which is addressed here. +. Vale.Spelling: At the moment there is a mix of en_US and en_UK spellings in the documentation and website. +Vale comes with an in built dictionary from which uses strictly en_US and do not accept the en_UK variant of any words. -. Spelling: At the moment there is a mix of en_US and en_UK spellings in the documentation and website. -A custom dictionary from link:https://wordlist.aspell.net[Aspell] has been added which uses strictly en_US and do not accept the en_UK variant of any words. -It has also an exception list to ignore the FreeBSD specific terms. -At the moment the list is a basic one with minimal words just as a proof of concept but if any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/FreeBSD/spelling-exceptions.txt# in the `doc` repository. +. Vale.Terms: Enforces the *PREFERRED* vocabulary terms for The FreeBSD Project. +At the moment the list of terms is empty and the FreeBSD specific terms will be added gradually. +If any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/Vocab/Terms/accept.txt# in the `doc` repository. More rules will be introduced in the upcoming days when and where required.