Page MenuHomeFreeBSD
Files F148122586

D37381.diff
No OneTemporary
Actions

D37381.diff
View Options

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: Some 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.

File Metadata

Mime Type
text/plain
Expires
Mon, Mar 16, 11:01 PM (3 h, 57 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29792350
Default Alt Text
D37381.diff (7 KB)

Event Timeline