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 @@ -256,11 +256,11 @@ [[writing-style-linting-vale]] == Linting with Vale -To maintain clarity and consistency across all documentation and website link:https://vale.sh[Vale] styles has been introduced in the documentation tree. +To maintain clarity and consistency across all documentation and the website link:https://vale.sh[Vale] styles have been introduced in the documentation tree. link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios. -At this moment link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipeline and integrated into editor of choice. +At this moment link:https://vale.sh[Vale] can be used as a command line tool, in a CI/CD pipeline, or integrated into editor of choice. -The following table describes the current rule names and respective severity. +The following table describes the current rule names and their respective severity. [.informaltable] [cols="1,1", frame="none", options="header"] @@ -303,42 +303,43 @@ [[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*. -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. +. BrandTerms: Like the FreeBSD Project every major vendor and company have specific rules on how to write their Brand Name. +According to the copyright rules of the FreeBSD Foundation *freebsd* should be written as *FreeBSD*. +Similarly, care should be taken to be respectful of other brands' value and one should write PostgreSQL, Node.js, Let's Encrypt etc. +Missing brand names should be added to [.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. . 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. +. Repetition: S0me words are often typed twice when leaving the keyboard and resuming the work again. +This rule finds repeated words and warns the author. -. 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. +. Weasel: This rule aims to avoid weasel words. +The use 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. +In case 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 languages like avoiding the words white/black/master/slave. +. ConsciousLanguage: This rule proposes use of conscious language like avoiding the words white/black/master/slave. -. EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation. +. EOLSpacing: Attempts to avoid whitespace at the end of lines. . Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong. -. Spacing: Often double spaces are hard to catch on plain eye which is addressed here. +. Spacing: Often double spaces are hard to notice which is addressed here. -. 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. +. 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 do 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. -More rules will be introduced in the upcoming days when and where required. +More rules will be introduced in the future when and where doceng team feels fusible. [[writing-style-using-vale]] === Using Vale -link:https://vale.sh[Vale] can be used from command line and from within editor or IDE. -package:textproc/vale[] can be installed as following: +link:https://vale.sh[Vale] can be used from command line and from within an editor or IDE. +package:textproc/vale[] can be installed by typing following: [source, shell] .... @@ -346,9 +347,9 @@ .... [[writing-style-using-vale-commandline]] -==== Using Vale in command line +==== Using Vale on the command line -Considering the fact that `doc` repository was cloned into [.filename]#~/doc#" the following commands are required to run: +Assuming that the `doc` repository was cloned into [.filename]#~/doc#", the following commands will run vale with the project's configuration: [source, shell] .... @@ -359,12 +360,12 @@ [NOTE] ====== link:https://vale.sh[Vale] is a CPU and memory intensive program due to the nature of the application and can take a while to show any output on the screen. -Better way to run the application is on specific folders or files rather than the entire `doc` repository as that is already done in the CI pipeline. +A Better way to run the application is on specific folders or files rather than the entire `doc` repository as that is already done in the project's CI pipeline. ====== [[writing-style-using-vale-editors]] ==== Using Vale in editors link:https://vale.sh[Vale] works with major mainstream editors like package:editors/vim[], package:editors/emacs[], package:editors/vscode[]. -At the moment the necessary configurations for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim]. -Necessary configurations for package:editors/emacs[] is being worked on. +At the moment the necessary configuration for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim]. +An example configuration for package:editors/emacs[] is being worked on.