diff options
author | Muhammad Moinur Rahman <bofh@FreeBSD.org> | 2022-11-10 18:43:50 +0000 |
---|---|---|
committer | Muhammad Moinur Rahman <bofh@FreeBSD.org> | 2022-11-10 18:52:31 +0000 |
commit | 2f326706331e23173f726dc3555cb74c9d23696d (patch) | |
tree | dc9aaaa248a944760d460c5ec0cb10f828c30b01 /.vale.ini | |
parent | f00b1c2b8dc666fc43c877e96fb9891262e7359c (diff) | |
download | doc-2f326706331e23173f726dc3555cb74c9d23696d.tar.gz doc-2f326706331e23173f726dc3555cb74c9d23696d.zip |
Introduce vale to the docs tree
Currently we do not have any language checker for our documentation
system. In previous we used igor which has not been upgraded and
sometimes are also not compatible with AsciiDOC and additionally the
maintainer is no longer a committer anymore. Considering this and
widespread use of Vale we have given a test on vale and initiating
introduction of vale with some basic set of rules. The rules are
described as below:
BrandTerms: Like The FreeBSD Project every major vendors and Companies
have specific rules on writing their Brand Name. Although we never read
but according to the Copyright rules of The FreeBSD Foundation whenever
we are writing we should write FreeBSD rather than freebsd. That is our
brand value. Similar to that we should be respective to other's brand
value and write PostgreSQL, Node.js, Let's Encrypt etc.
Contractions: Contracted words should not be used. This rule avoids all
contractions and suggests full words.
Hang: We often try to use the word hang to convey the meaning that the
application has stopped responding. This rule proposes better wording
Repetition: Often while working we type the same words twice; this
mostly happen we leave the keyboard while writing and returning to desk.
This rule finds repeated words
Weasel: This rule handles avoiding weasel words
ConsciousLanguage: This rule proposes uses of conscious languages like
avoiding the words white/black/master/slave
EOLSpacing: In most of our documents EOL spacing is present which is
not the ideal situation. This rule warns the user
Hyphens: Often adverbs ending with 'ly' are being added with a hyphen
which is wrong. This rule handles this
Spacing: Often double spaces are hard to catch on plain eye which is addressed here
Spelling: Spelling checks using a custom dictionary from
http://wordlist.aspell.net which uses strictly en_US and do not accept
the BRITISH spelling variant. It has also an exception list to ignore
the FreeBSD specific terms. Currently the list is a basic one with
minimal words just as a proof of concept
The next step will be restarting the CI process of FreeBSD docs, reduce
noises and implement git hooks.
Approved by: carlavilla (mentor)
Differential Revision: https://reviews.freebsd.org/D37297
Diffstat (limited to '.vale.ini')
-rw-r--r-- | .vale.ini | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000..2566579071 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,48 @@ +StylesPath = .vale/styles +MinAlertLevel = suggestion + +[asciidoctor] +# enable +experimental = YES + +# assign a specific value +attribute-missing = drop + +[*.adoc] +BasedOnStyles = FreeBSD +FreeBSD.BrandTerms = NO +FreeBSD.ConsciousLanguage = NO +FreeBSD.Contractions = NO +FreeBSD.EOLSpacing = NO +FreeBSD.Hang = NO +FreeBSD.Hyphens = NO +FreeBSD.Repitition = NO +FreeBSD.Spacing = NO +FreeBSD.Spelling = NO +FreeBSD.Weasel = NO + +[website/content/en/**/*.adoc] +BasedOnStyles = FreeBSD +FreeBSD.BrandTerms = YES +FreeBSD.ConsciousLanguage = YES +FreeBSD.Contractions = YES +FreeBSD.EOLSpacing = YES +FreeBSD.Hang = YES +FreeBSD.Hyphens = YES +FreeBSD.Repitition = YES +FreeBSD.Spacing = YES +FreeBSD.Spelling = YES +FreeBSD.Weasel = NO + +[documentation/content/en/**/*.adoc] +BasedOnStyles = FreeBSD +FreeBSD.BrandTerms = YES +FreeBSD.ConsciousLanguage = YES +FreeBSD.Contractions = YES +FreeBSD.EOLSpacing = YES +FreeBSD.Hang = YES +FreeBSD.Hyphens = YES +FreeBSD.Repitition = YES +FreeBSD.Spacing = YES +FreeBSD.Spelling = YES +FreeBSD.Weasel = NO |