Date: Thu, 4 May 2023 20:14:08 GMT From: Muhammad Moinur Rahman <bofh@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 1391da325d - main - fdp-primer/writing-style: Refactor after adding new Vale rules Message-ID: <202305042014.344KE87l016398@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by bofh: URL: https://cgit.FreeBSD.org/doc/commit/?id=1391da325d317b3e5ee9c578da61b61b80de2f95 commit 1391da325d317b3e5ee9c578da61b61b80de2f95 Author: Muhammad Moinur Rahman <bofh@FreeBSD.org> AuthorDate: 2023-05-04 19:33:01 +0000 Commit: Muhammad Moinur Rahman <bofh@FreeBSD.org> CommitDate: 2023-05-04 20:13:56 +0000 fdp-primer/writing-style: Refactor after adding new Vale rules Over the last couple of day some new rules has been added, while some rules have been replaced with the one from Vale builtin engines and some have been removed. - Update the fdp-primer to reflect those changes. - As now there are mix of two different styles FreeBSD and Vale be more specific on naming those rules with dotted notation. - Reword the rule FreeBSD.ConsciousLanguage by avoiding sensitive words itself. Approved by: carlavilla (mentor) Differential Revision: https://reviews.freebsd.org/D39800 --- .../en/books/fdp-primer/writing-style/_index.adoc | 76 +++++++++++++--------- 1 file changed, 47 insertions(+), 29 deletions(-) diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc index a4d3755f5d..8d0161fb81 100644 --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -263,70 +263,88 @@ The following table describes the current rule names and their respective severi | 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: According to the copyright rules of The FreeBSD Foundation, *freebsd* should be written as *FreeBSD*. +. FreeBSD.BrandTerms: According to the copyright rules of The FreeBSD Foundation, *freebsd* should be written as *FreeBSD*. Similarly, every major vendor and company has specific rules on writing their brand names and trademarks. -Care should be taken to be respectful to the brand value others and to take time to write PostgreSQL, Node.js, Let's Encrypt etc. +Care should be taken to be respectful to the brand value of others and to take time to 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 people are avoided where possible. + +. FreeBSD.Contractions: Contracted words should not be used. +This rule avoids all contractions and suggests full words. -. Hang: `Hang` is often used to mean 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 mean that the application has stopped responding. This rule proposes better wording. -. Repetition: Some 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 added with a hyphen which is wrong. -. Weasel: This rule is aimed at avoiding weasel words. +. FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye and this 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 is aimed at avoiding weasel words. The concept of weasel words is controversial so at the moment the list of words are being evaluated and the severity level is marked as warning only. If a frequently used word is marked as a weasel word it should be removed from [.filename]#.vale/styles/FreeBSD/Weasel.yml# in the `doc` repository. -. ConsciousLanguage: This rule proposes uses of conscious language, for example 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 wanted. - -. Hyphens: Often adverbs ending with 'ly' are 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 with the naked eye and this 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_GB 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 does not accept the en_GB 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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202305042014.344KE87l016398>