git: eb6c0b65b8 - main - books/fdp-primer: Vale introducation in FDP

The branch main has been updated by bofh:

URL: https://cgit.FreeBSD.org/doc/commit/?id=eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96

commit eb6c0b65b8cce4891bd55c13fd3128ffb15cbd96
Author:     Muhammad Moinur Rahman <[email protected]>
AuthorDate: 2022-11-14 15:03:18 +0000
Commit:     Muhammad Moinur Rahman <[email protected]>
CommitDate: 2022-11-14 15:04:22 +0000

    books/fdp-primer: Vale introducation in FDP
    
    Introduction of vale in the fdp-primer. Describes about the current
    rules and howto use vale from command line or editors.
---
 .../en/books/fdp-primer/writing-style/_index.adoc  | 116 +++++++++++++++++++++
 1 file changed, 116 insertions(+)

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 1fe5811de1..215d5d30eb 100644
--- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
@@ -252,3 +252,119 @@ If a character is not on this list, ask about it on the {freebsd-doc}.
 | <=
 
 |===
+
+[[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.
+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.
+
+The following table describes the current rule names and respective severity.
+
+[.informaltable]
+[cols="1,1", frame="none", options="header"]
+|===
+| Name
+| Severity
+
+| BrandTerms
+| error
+
+| ConsciousLanguage
+| warning
+
+| Contractions
+| suggestions
+
+| EOLSpacing
+| warning
+
+| Hang
+| warning
+
+| Hyphens
+| warning
+
+| Repetition
+| warning
+
+| Spacing
+| error
+
+| Spelling
+| warning
+
+| Weasel
+| warning
+
+|===
+
+[[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.
+
+. 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.
+
+. 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.
+
+. 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.
+
+. Spacing: Often double spaces are hard to catch on plain eye 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.
+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.
+
+[[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:
+
+[source, shell]
+....
+$ pkg install vale
+....
+
+[[writing-style-using-vale-commandline]]
+==== Using Vale in command line
+
+Considering the fact that `doc` repository was cloned into [.filename]#~/doc#" the following commands are required to run:
+
+[source, shell]
+....
+% cd ~/doc
+% vale .
+....
+
+[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.
+======
+
+[[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.