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
This commit is contained in:
Muhammad Moinur Rahman 2022-11-10 12:43:50 -06:00
parent f00b1c2b8d
commit 2f32670633
15 changed files with 50289 additions and 0 deletions

48
.vale.ini Normal file
View File

@ -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

View File

@ -0,0 +1,205 @@
SET UTF-8
TRY esianrtolcdugmphbyfvkwzESIANRTOLCDUGMPHBYFVKWZ'
ICONV 1
ICONV '
NOSUGGEST !
# ordinal numbers
COMPOUNDMIN 1
# only in compounds: 1th, 2th, 3th
ONLYINCOMPOUND c
# compound rules:
# 1. [0-9]*1[0-9]th (10th, 11th, 12th, 56714th, etc.)
# 2. [0-9]*[02-9](1st|2nd|3rd|[4-9]th) (21st, 22nd, 123rd, 1234th, etc.)
COMPOUNDRULE 2
COMPOUNDRULE n*1t
COMPOUNDRULE n*mp
WORDCHARS 0123456789
PFX A Y 1
PFX A 0 re .
PFX I Y 1
PFX I 0 in .
PFX U Y 1
PFX U 0 un .
PFX C Y 1
PFX C 0 de .
PFX E Y 1
PFX E 0 dis .
PFX F Y 1
PFX F 0 con .
PFX K Y 1
PFX K 0 pro .
SFX V N 2
SFX V e ive e
SFX V 0 ive [^e]
SFX N Y 3
SFX N e ion e
SFX N y ication y
SFX N 0 en [^ey]
SFX X Y 3
SFX X e ions e
SFX X y ications y
SFX X 0 ens [^ey]
SFX H N 2
SFX H y ieth y
SFX H 0 th [^y]
SFX Y Y 1
SFX Y 0 ly .
SFX G Y 2
SFX G e ing e
SFX G 0 ing [^e]
SFX J Y 2
SFX J e ings e
SFX J 0 ings [^e]
SFX D Y 4
SFX D 0 d e
SFX D y ied [^aeiou]y
SFX D 0 ed [^ey]
SFX D 0 ed [aeiou]y
SFX T N 4
SFX T 0 st e
SFX T y iest [^aeiou]y
SFX T 0 est [aeiou]y
SFX T 0 est [^ey]
SFX R Y 4
SFX R 0 r e
SFX R y ier [^aeiou]y
SFX R 0 er [aeiou]y
SFX R 0 er [^ey]
SFX Z Y 4
SFX Z 0 rs e
SFX Z y iers [^aeiou]y
SFX Z 0 ers [aeiou]y
SFX Z 0 ers [^ey]
SFX S Y 4
SFX S y ies [^aeiou]y
SFX S 0 s [aeiou]y
SFX S 0 es [sxzh]
SFX S 0 s [^sxzhy]
SFX P Y 3
SFX P y iness [^aeiou]y
SFX P 0 ness [aeiou]y
SFX P 0 ness [^y]
SFX M Y 1
SFX M 0 's .
SFX B Y 3
SFX B 0 able [^aeiou]
SFX B 0 able ee
SFX B e able [^aeiou]e
SFX L Y 1
SFX L 0 ment .
REP 90
REP a ei
REP ei a
REP a ey
REP ey a
REP ai ie
REP ie ai
REP alot a_lot
REP are air
REP are ear
REP are eir
REP air are
REP air ere
REP ere air
REP ere ear
REP ere eir
REP ear are
REP ear air
REP ear ere
REP eir are
REP eir ere
REP ch te
REP te ch
REP ch ti
REP ti ch
REP ch tu
REP tu ch
REP ch s
REP s ch
REP ch k
REP k ch
REP f ph
REP ph f
REP gh f
REP f gh
REP i igh
REP igh i
REP i uy
REP uy i
REP i ee
REP ee i
REP j di
REP di j
REP j gg
REP gg j
REP j ge
REP ge j
REP s ti
REP ti s
REP s ci
REP ci s
REP k cc
REP cc k
REP k qu
REP qu k
REP kw qu
REP o eau
REP eau o
REP o ew
REP ew o
REP oo ew
REP ew oo
REP ew ui
REP ui ew
REP oo ui
REP ui oo
REP ew u
REP u ew
REP oo u
REP u oo
REP u oe
REP oe u
REP u ieu
REP ieu u
REP ue ew
REP ew ue
REP uff ough
REP oo ieu
REP ieu oo
REP ier ear
REP ear ier
REP ear air
REP air ear
REP w qu
REP qu w
REP z ss
REP ss z
REP shun tion
REP shun sion
REP shun cion
REP size cise

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,11 @@
extends: substitution
message: Use '%s' instead of '%s'.
level: error
ignorecase: true
swap:
'(?:LetsEncrypt|Let''s Encrypt)': Let's Encrypt
'node[.]?js': Node.js
'Post?gr?e(?:SQL)': PostgreSQL
'java[ -]?scripts?': JavaScript
freebsd: FreeBSD
xml: XML

View File

@ -0,0 +1,36 @@
---
extends: substitution
ignorecase: true
level: warning
link: ""
message: Use '%s' rather than '%s.'
action:
name: replace
swap:
black list: blocklist|wronglist|banlist|deny list
blacklist: blocklist|wronglist|banlist|deny list
blacklisted: blocklisted|wronglisted|banlisted|deny-listed
blacklisting: blocklisting|wronglisting|banlisting|deny-listing
bugreport: bug report|snapshot
ghetto: projects|urban
grandfather clause: legacy policy|legacy clause|deprecation policy
grandfather policy: legacy policy|legacy clause|deprecation policy
grandfathered: deprecated
grandfathering: deprecate
master: primary|hub|source|initiator|requester|controller|host|director|reference
masters: primaries|hubs|references
non white: person of color|people of color
nonwhite: person of color|people of color
sophisticated culture: complex culture
sophisticated technology: complex technology
stone age: simple|indigenous|hunter-gatherer
slave: secondary|replica|responder|device|worker|proxy|performer
totem: favorite|inspiration|personal interest|personality type
white list: passlist|alrightlist|safelist|allow list
white space: space|blank
white spaces: spaces|blanks
whitelist: passlist|alrightlist|safelist|allow list
whitelisted: passlisted|alrightlisted|safelisted|allow-listed
whitelisting: passlisting|alrightlisting|safelisting|allow-listing
whitespace: space|blank
whitespaces: spaces|blanks

View File

@ -0,0 +1,42 @@
---
extends: substitution
ignorecase: true
level: suggestion
message: "Avoid contractions. Use '%s' rather than '%s.'"
action:
name: replace
swap:
"aren't": is not
"can't": cannot
"couldn't": could not
"didn't": did not
"doesn't": does not
"don't": do not
"hasn't": has not
"haven't": have not
"how'll": how will
"how's": how is
"isn't": is not
"it'll": it will
"it's": it is
"shouldn't": should not
"that'll": that will
"that's": that is
"they'll": they will
"they're": they are
"wasn't": was not
"we'll": we will
"we're": we are
"we've": we have
"weren't": were not
"what'll": what will
"what's": what is
"when'll": when will
"when's": when is
"where'll": where will
"where's": where is
"who'll": who will
"who's": who is
"why'll": why will
"why's": why is
"won't": will not

View File

@ -0,0 +1,7 @@
---
extends: existence
message: "End of lines should not have spaces"
level: warning
scope: raw
raw:
- ' +\n'

View File

@ -0,0 +1,12 @@
---
extends: substitution
message: When referring to application, consider using '%s' instead of '%s'.
ignorecase: true
level: warning
action:
name: replace
swap:
hang: the app froze|the app stopped responding|the app stopped responding to events|the
app became unresponsive
hanged: the app froze|the app stopped responding|the app stopped responding to events|the
app became unresponsive

View File

@ -0,0 +1,13 @@
extends: existence
message: "'%s' doesn't need a hyphen."
level: warning
ignorecase: false
nonword: true
action:
name: edit
params:
- replace
- '-'
- ' '
tokens:
- '\s[^\s-]+ly-'

View File

@ -0,0 +1,6 @@
extends: repetition
message: "'%s' is repeated!"
level: warning
alpha: true
tokens:
- '[^\s]+'

View File

@ -0,0 +1,7 @@
extends: existence
message: "'%s' should have one space."
level: error
nonword: true
tokens:
- '[a-z][.?!] {2,}[A-Z]'
- '[a-z][.?!][A-Z]'

View File

@ -0,0 +1,7 @@
extends: spelling
message: "'%s' is a typo!"
dicpath: .vale/styles/Dicts
dictionaries:
- en_US-default_none_strip_hacker
ignore:
- FreeBSD/spelling-exceptions.txt

View File

@ -0,0 +1,208 @@
---
extends: existence
message: "'%s' is a weasel word!"
ignorecase: true
level: warning
tokens:
- absolutely
- accidentally
- additionally
- allegedly
- alternatively
- angrily
- anxiously
- approximately
- awkwardly
- badly
- barely
- beautifully
- blindly
- boldly
- bravely
- brightly
- briskly
- bristly
- bubbly
- busily
- calmly
- carefully
- carelessly
- cautiously
- cheerfully
- clearly
- closely
- coldly
- completely
- consequently
- correctly
- courageously
- crinkly
- cruelly
- crumbly
- cuddly
- currently
- daily
- daringly
- deadly
- definitely
- deliberately
- doubtfully
- dumbly
- eagerly
- early
- easily
- elegantly
- enormously
- enthusiastically
- equally
- especially
- eventually
- exactly
- exceedingly
- exclusively
- extremely
- fairly
- faithfully
- fatally
- fiercely
- finally
- fondly
- few
- foolishly
- fortunately
- frankly
- frantically
- generously
- gently
- giggly
- gladly
- gracefully
- greedily
- happily
- hardly
- hastily
- healthily
- heartily
- helpfully
- honestly
- hourly
- hungrily
- hurriedly
- immediately
- impatiently
- inadequately
- ingeniously
- innocently
- inquisitively
- interestingly
- irritably
- jiggly
- joyously
- justly
- kindly
- largely
- lately
- lazily
- likely
- literally
- lonely
- loosely
- loudly
- loudly
- luckily
- madly
- many
- mentally
- mildly
- monthly
- mortally
- mostly
- mysteriously
- neatly
- nervously
- nightly
- noisily
- normally
- obediently
- occasionally
- only
- openly
- painfully
- particularly
- patiently
- perfectly
- politely
- poorly
- powerfully
- presumably
- previously
- promptly
- punctually
- quarterly
- quickly
- quietly
- rapidly
- rarely
- really
- recently
- recklessly
- regularly
- remarkably
- relatively
- reluctantly
- repeatedly
- rightfully
- roughly
- rudely
- sadly
- safely
- selfishly
- sensibly
- seriously
- sharply
- shortly
- shyly
- significantly
- silently
- simply
- sleepily
- slowly
- smartly
- smelly
- smoothly
- softly
- solemnly
- sparkly
- speedily
- stealthily
- sternly
- stupidly
- substantially
- successfully
- suddenly
- surprisingly
- suspiciously
- swiftly
- tenderly
- tensely
- thoughtfully
- tightly
- timely
- truthfully
- unexpectedly
- unfortunately
- usually
- very
- victoriously
- violently
- vivaciously
- warmly
- waverly
- weakly
- wearily
- weekly
- wildly
- wisely
- worldly
- wrinkly
- yearly

View File

@ -0,0 +1,79 @@
Accetta
Beranek
Cheriton
[Cc]hroot
DARPA
Englewood
Ethernets
Ewens
Excelan
FIFOs
Filestores
Fortran
Gandi
Gingell
Interlan
Interprocess
Karels
Kbyte
Kernighan
Macklem
Makefile
Microsystems
O'Reilly
Ousterhout
Ritchie
Rosenblum
Rozier
Sebastopol
Tevanian
Winsock
autoconfiguration
basename
chdir
checksubdir
chmod
chown
coroutine
coroutines
datagrams
deallocate
deallocation
descendents
distfile
errno
execve
fchmod
fchown
filestore
filestores
fstat
interprocess
lseek
malloc
mkdir
mknod
mmap
multiuser
noncanonical
nongraphic
pathnames
poudriere
prepended
public_html
[Qq]uarterly
readv
recv
recvfrom
recvmsg
reimplemented
rmdir
rmport
sendmsg
sendto
subhierarchies
subdirectory
unbuffered
untyped
vnode
writev

40
.vale/vale.tmpl Normal file
View File

@ -0,0 +1,40 @@
{{- /* Keep track of our various counts */ -}}
{{- $e := 0 -}}
{{- $w := 0 -}}
{{- $s := 0 -}}
{{- $f := 0 -}}
{{- /* Range over the linted files */ -}}
{{- range .Files}}
{{$table := newTable true}}
{{- $f = add1 $f -}}
{{- .Path | underline | indent 1 -}}
{{- /* Range over the file's alerts */ -}}
{{- range .Alerts -}}
{{- $error := "" -}}
{{- if eq .Severity "error" -}}
{{- $error = .Severity | red -}}
{{- $e = add1 $e -}}
{{- else if eq .Severity "warning" -}}
{{- $error = .Severity | yellow -}}
{{- $w = add1 $w -}}
{{- else -}}
{{- $error = .Severity | blue -}}
{{- $s = add1 $s -}}
{{- end}}
{{- $loc := printf "%d:%d" .Line (index .Span 0) -}}
{{- $row := list $loc $error .Message .Check | toStrings -}}
{{- $table = addRow $table $row -}}
{{end -}}
{{- $table = renderTable $table -}}
{{end}}
{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}} and {{$s}} {{"suggestions" | blue}} in {{$f}} {{$f | int | plural "file" "files"}}.